Most of the time I’ve been developing WordPress sites I’ve been using MAMP Pro to run the local versions of the site. This has served me well 99% of the time, but every once in a while I’ve hit a bug that only presents itself in a certain version of PHP, or if a server is configured a certain way.
Unfortunately MAMP doesn’t really let you configure your development environment to match other servers, at least not easily. Really the best option to mimic servers for your local configuration is Vagrant.
What is Vagrant?
Vagrant uses VMWare or Virtual Box to host a virtual server on your computer. Since all your configurations are on a virtual machine, you can make it match a server environment perfectly without affecting any other setups.
Now Vagrant is not necessarily for the beginner. You should probably be very comfortable with a command line interface (Terminal in OSX) and have a decent understanding of how servers work. I don’t want to scare you off though, there is a great project by Jeremy Felt and 10up called Varrying Vagrants Vagrants to get you started.
If you’re just starting to learn how to build WordPress sites, bookmark this article and stick with MAMP or XAMPP for now. There are lots of other things you should learn before delving in to custom VM setups for hosts.
Today we’ll go over a basic install of Vagrant on OSX with the Github project from Jeremy.
Getting Set Up
The first thing you need to do is install Vagrant and Virtual Box, if you don’t have them already installed.
Simply double click on them and follow the install prompts. If you already had terminal open, you will need to shut it down and start it again to get the Vagrant commands.
To test if Vagrant is installed just type
vagrant --help in terminal and you should see the same thing I have below.
Next we need to clone the Github repository in to a folder on our local machine. Navigate to wherever you keep the rest of your local development projects and type the following in to Terminal:
git clone email@example.com:10up/varying-vagrant-vagrants.git wpthemet-vagrant-test
That will clone the whole repository in to a folder called ‘wpthemet-vagrant-test’.
Getting Vagrant Running
Now we need to do a couple more things to get our development server up and running.
First we need to add a new entry to our hosts file so that when we type a URL in our web browsers we see the WordPress site on our new virtual machine. Type the following in Terminal.
sudo vim /private/etc/hosts
That will prompt you to type in your admin password (sudo is a command that allows you root access to your machine, use it wisely) and then it will open up vim to allow you to edit your hosts file.
For the default settings in Varrying Vagrant Vagrants you need 2 domains added as we see below:
192.168.50.4 local.wordpress.dev local.wordpress-trunk.dev
local.wordpress.dev will access the default latest version of WordPress on your virtual machine and
local.wordpress-trunk.dev will access the default WordPress trunk version on your virtual machine.
At this point if you type either of those two URL’s, nothing will happen because we haven’t started our virtual machine.
Navigate in to the ‘wpthemet-vagrant-test’ folder and type
vagrant up. The first time you do this on a new VM it’s going to take a bit since the VM has to download a bunch of dependencies (280mb worth). Once you’ve run a VM once, it takes way less time since the 280mb is cached.
Now navigate to either
local.wordpress-trunk.dev to see a WordPress install running. By default the WordPress admin can be accessed with:
un: admin pw: password
To see a full list of the credentials (for MySQL, Unit Tests…) visit the Github project documentation.
This is the point I got stuck at for a while. Partly I didn’t read the documentation it detail, and partly I think that there is some assumed knowledge with the documentation. Either way, I had no idea how to edit the WordPress files that my VM was running on.
Turns out it’s really easy. Varrying Vargant Vagrants automatically sync’s the folders found in
wpthemet-vagrant-test/www to the virtual machine. So see the wordpress-default folder, that is what you are accessing at
http://local.wordpress.dev and when you type
http://local.wordpress-trunk.dev your seeing the files in the wordpress-trunk folder.
To work on a site that is in your VM, just edit the files in either of the folders (depending on which version you want to use) like you would have with MAMP installed.
Accessing the Virtual Machine
So you have your full virtual machine running, but what if you need to change the virtual machine configuration? Well it’s a fully running server so you can just SSH in to it and make the changes you need. Type
vagrant ssh and you will be SSHing in to the VM.
Few other Vagrant Basic Commands
vagrant halt– stops the virtual machine
vagrant suspend– like putting your computer to sleep for quick boot later
vagrant resume– wakes from sleep
vagrant destroy– totally kills the VM on your machine. This does mean that you need to download that 280mb again so only use it if you need the space. Your project files will be safe still.
I highly recommend that you read all the articles below. I found reading through the getting started documentation on the Vagrant site immensely helpful in understanding Vagrant in general when I was stuck.
- Vagrant Getting Started docs
- Hi WordPress Meet Vagrant
- Evolving WordPress Development with Vagrant
- Clear Nginx Cache in Vagrant
- Using Vagrant as a Team