Back in October I penned a two piece series on setting up Yosemite with Apache with PHP, APC, Virtual Hosts and other goodies. There are other options available however, and one of the more popular ones is to use Vagrant to easily spin up a pre-configured virtual-machine.
In this tutorial, we'll step through the process of getting an RTD (ready-to-develop) environment installed on your Mac, Windows, or Linux desktop.
Vagrant provides functionality that makes it easy to configure and provision reproducible environments on your local machine. What this means is that you can create an environment that you know will always run your software, and will run it the same way no matter what platform you are on, be it Mac, Windows or Linux. This is a very useful capability in this modern web development world where dealing with setup and platform requirements can be tricky, especially to the uninitiated.
Vagrant has a simple native installer for Mac, Windows or Linux (DEB, RPM). So head over to the Vagrant Download page, grab the appropriate package, and install it.
VirtualBox is free cross-platform virtualization platform that is very well supported by Vagrant. Parallels and VMWare Workstation/Fusion are also supported and provide better performance, but they are commercial products. In this guide, we will focus on VirtualBox, but you will find comments about Parallels where appropriate.
To install VirtualBox, you simply need to head over the VirtualBox official downloads page and download the appropriate package for you platform. Then install the application.
Now you have Vagrant installed, the next step is to configure and build your Vagrant box. To make this process easier, we have already created a manifest with the help of a great online tool called PuPHPet. It provides a nice GUI to configure our Vagrant box with all the bits we need to run Grav properly.
This configuration is also useful for other development such as for WordPress and Joomla because it already comes with the following features:
- Debian 7.5 x64 OS (vim, htop, curl packages)
- Apache 2.4 (cache, expires, headers, rewrite, ssl packages)
- PHP 5.6 (composer, apc, xdebug, cli, common, curl, gd, imagick, intl, mbstring, mcrypt, memcache, sqlite packages)
- NFS File Shares (Mac/Linux)
- MariaDB (MySQL compatible)
Click the big blue button below to grab the latest version of the pre-configured Grav manifest:
Now we have pretty much all we need to get our Vagrant box up and running. Extract your freshly downloaded
grav-puphpet-master.zip manifest file into a good location on your computer (
Projects/vagrant for example) and rename the randomly created folder to something more useful. I have mine named
apache-php56, so the full folder name is
Projects/vagrant/apache-php56. You can do this easily from a terminal:
$ mkdir ~/Projects/vagrant $ cd ~/Projects/vagrant $ unzip ~/Downloads/grav-puphpet-master.zip && mv grav-puphpet-master apache-php56 $ cd apache-php56
Before we go any further, you should install the BindNFS Vagrant plugin:
$ vagrant plugin install vagrant-bindfs
If yor on a windows-based machine you should also install WinNFSd Vagrant plugin also for improved performance:
$ vagrant plugin install vagrant-winnfsd
NOTE: If you wish to install with Parallels rather than VirtualBox, you will need to install the Parallels Vagrant plugin:
$ vagrant plugin install vagrant-parallels
Now we can bring start the process of installing our Vagrant box:
$ vagrant up
NOTE: to use Parallels you will need to run:
$ vagrant up --provider=parallels
This will kick off the process of download the VM image and setup according to our configuration. This can take a little time this first time, but not to worry, it will be faster after the initial heavy-lifting is done.
If you are on Mac or Linux, Vagrant will use NFS file shares, and these require your system password to setup, so when you see the prompt:
==> default: Exporting NFS shared folders... ==> default: Preparing to edit /etc/exports. Administrator privileges will be required...
Simply enter your administrator password and press return, the installation should proceed after. When you are returned to a command prompt, your Vagrant box will be up and running.
To ensure the box is running properly, we can SSH to it with Vagrant:
$ vagrant ssh Linux packer-parallels-iso 3.2.0-4-amd64 #1 SMP Debian 3.2.57-3 x86_64 Welcome to your Vagrant-built virtual machine. Last login: Thu Jul 17 11:48:07 2014 from 10.211.55.2 [12:33 PM]-[vagrant@packer-parallels-iso]-[~] $
To Exit, simply type
Grav Virtual Host
The Vagrant box has already been configured with a Grav virtual host, but to take advantage of this, we need to add an try in our local hosts file:
192.168.50.4 grav.dev, www.grav.dev
Now you will be able to use
www.grav.dev in your browser to reach the web server.
You will notice there is an existing
~/Projects/vagrant/apache-php56/grav folder. This actually is mounted directory for your
http://grav.dev virtual host.
Simply point your browser to
http://grav.dev and you should see the landing page with links to each of the installed Grav instances.
Of course you can install others or copies of these and modify them as you wish.
To shutdown the Vagrant box simply bring up a terminal, ensure you are in the correct Vagrant directory and run halt:
$ vagrant halt
There are situations where you wish to make changes to your Vagrant box. Perhaps to update a configuration setting, or include a new module, or perhaps enable a new service. To accomplish this all you need to is edit your
puphpet/config.yml file directly, or drag it to the PuPHPet.com service again and modify there.
After you have make your changes, you need to instruct Vagrant to re-provision the box:
$ vagrant provision
This will perform all the processing tasks similar to those that it ran through when you ran
vagrant up the first time.
Destroying a Vagrant instance
For the sake of completeness, if you ever need to start over, you can completely destroy a Vagrant box. Note, this does not cause the mounted files to be lost, but the VM will be completely removed.
$ vagrant destroy
You will be able to create a new vagrant instance by calling
vagrant up again.