Getting Started with eZ Platform on Vagrant
Last year, I had a somewhat negative experience with installing eZ Publish on a Vagrant box. Since then, they’ve significantly improved both the software and the VM-friendliness by, well, flat out removing the legacy stack. The VM setup we’ll be using in this tutorial comes from the labs of NetGen and the mind of @vranac, and is followed by the installation procedure on our very own Homestead Improved modified by yours truly.
Note: the new eZ system, now called eZ Platform, is still in deep alpha mode and doesn’t really contain all the features of the old one yet. In fact, if you want to do any kind of serious content management and modification, you need to add the legacy stack into the mix, the process of which is described here.
Vranac defined an Ansible recipe for provisioning a raw Ubuntu/Trusty box with all the prerequisites for eZ Platform. This means that, while it keeps your raw box highly reusable for other projects (thus saving on disk space), the provisioning procedure can be very long (upwards of 40 minutes). Likewise, to use this approach, you need Ansible on the host machine unlike with Homestead Improved. It’s up to you to choose which setup you like more – both work just fine. The instructions for Homestead Improved are in the next section, but first, let’s look at Vranac’s approach.
Your host machine should have:
Note that if you’re on Windows, Ansible is not available. However, the configuration will make sure it downloads and installs Ansible inside the guest VM, and executes it from within, so no worries.
Clone and Up
To set up an environment, we’ll clone @vranac’s Vagrantfile setup and
vagrant up it.
git clone https://github.com/netgen/vagrant-ansible-ezpublish.git cd vagrant-ansible-ezpublish vagrant up
up procedure should take care of all provisioning automatically, including folder sharing. It might take a while, depending on the speed of your machine and of your internet connection. It might also ask you for your admin password (or get the UAC dialog on Windows) on the host machine, due to using NFS for file sharing.
By default, the folder you’re in (
vagrant-ansible-ezpublish) will be linked to
var/www/ezpublish inside the VM. A database called
ezpublish will also be automatically created with the username
ez and the password
Now, there are a couple of caveats to keep in mind.
Due to some Apache 2.4 shenanigans the team couldn’t get around, the folder in the VM that gets shared with the host machine is
var/www/ezpublish rather than the traditional
var/www. Thus, to power an eZ Platform instance on this VM, you need to do the following once you’re inside the machine with
cd /var/www/ezpublish composer create-project ezsystems/ezplatform mv ezplatform/* .
We need to do this because the create project command creates an eZ project in the
ezplatform folder, and Apache’s vhost is linked into
Then, install the demo bundle and clear cache with:
php ezpublish/console ezplatform:install --env prod demo php ezpublish/console cache:clear --env prod
To visit the front end, go to
172.21.12.10, and to visit the back end, go to
The login credentials are
Important note: Due to this setup, if something goes wrong, you shouldn’t
rm -rf the contents of the
ezpublish folder and assume everything will be fine if you create a new project. If you delete the folder or its contents, you’re effectively removing the contents of the folder on the host, which includes provisioning scripts and the Vagrantfile. To avoid these problems, you can either:
- create sub-projects inside
/var/www/ezpublish/project1and configure new Apache virtual hosts to accommodate this
or follow the instructions below, applied to Homestead Improved but easily applicable to all other systems and virtual machine environments as well.
Configuring eZ on Homestead Improved
The setup above favors Apache instead of Nginx, and is a bit clumsy in terms of multi-project setups. Let’s set it up on an environment we’re familiar with now, and with which we can be up and running in under 10 minutes: Homestead Improved. Follow the tutorial and set it up. Then,
vagrant halt it into shutdown mode and set up a new site:
- map: ez.app to: /home/vagrant/Code/ezplatform/web
Now that our new Nginx host is set up, let’s enter the VM and create a new MySQL database:
mysql -u homestead -psecret -e "create database ezpublish";
Note that the username and password are
secret, as per default Homestead configuration.
We also need some PHP extensions installed:
sudo apt-get update sudo apt-get install php5-intl php5-xsl
Now, let’s go into the Code folder while inside the VM and create the project.
cd ~/Code composer create-project ezsystems/ezplatform
This might take a while so grab a cup and relax. When it finishes, wrap up the installation by installing the demo bundle and clearing the cache.
cd ezplatform php ezpublish/console ezplatform:install --env prod demo php ezpublish/console cache:clear --env prod
Don’t forget to add
ez.app (or whichever site name you chose) to your
/etc/hosts file on the host machine, as per instructions in the Homestead Improved quickstart.
Now, visit the URL http://ez.app/ (the trailing slash is important, as it forces your browser to look for the site directly, rather than use Google to search for it if DNS servers don’t resolve it) and enjoy!
Diving into EZPublish and Symfony at PHPSummerCamp
With the installation done, we can finally dive in and build wonderfully complex systems that even the most demanding websites can’t out-demand. It’s important to be patient with the system – being in alpha mode, it’s still incredibly unstable and very slow, but getting there. Keep testing and help the team out with suggestions – let’s make sure it gets released soon by providing as much feedback as possible. Use it with the dev tools open and review the errors, discuss on the forums, tweet at them, or let us know in the comments below.
To dive in an learn about the platform, you could go and read the documentation, or you could come and join us as PHPSummerCamp – the same event we attended last year. This time around, some even more high profile speakers are flying in, including but not limited to:
- Ryan Weaver of KNPLabs,
- Bernhard Schussek, creator of Puli
- David Buchman of Liip fame
- Pawel Jedrzejewski from Sylius
- Nicolas Grekas from SensioLabs
…and many more, with topics like:
- Deep insights into object-oriented programming with Symfony
- Managing assets with Puli
- HTTP caching with Varnish
- Rapid API development with Lionframe
- Modeling by example
- Profiling PHP applications (Blackfire)
- Migrating to Symfony 3.0
With not only three full days of hands-on workshops (rather than the traditional theoretical bombardment you usually get at conferences) but also boat trips, lunches, and the experience of the Croatian coastline (something you shouldn’t miss – trust me), it’s a no-brainer.
The event has just had its super-early-bird prices announced and tickets made available for purchase, so make sure you check out the announcement post.
Too expensive? Just convince your boss! Make sure they know that your education and training will benefit the company much more in the long term than you staying at work for those three extra days.
As you can see, the installation has gone a long way since last year. The system has been upgraded to a great extent, Symfony’s DX program helped with the multi-platform aspect and the symlink problems, and the excellent work of NetGen and @vranac has improved the flow immeasurably. Go ahead and install eZ now, play with it, tell us what you think. Use it to boot up a CMS that needs more than a blog and let us know how you feel about it. If you do something interesting with it, get in touch, I’d love more eZ tutorials!
Feedback? Comments? Leave them below or tell me live at PHP Summer Camp!