Set up a WordPress development environment with vagrant

image: /assets/img/og-image.jpg
layout: post
title: Set up a WordPress development environment with vagrant
excerpt: A simple tutorial explaining how to setup a WordPress development environment using Vagrant and ScotchBox as the virtual machine.

date: 2017-06-27
author: Scott Baker

  • Tutorials
  • Web Development
  • WordPress
    permalink: /blog/set-up-a-wordpress-development-environment-with-vagrant
    slug: set-up-a-wordpress-development-environment-with-vagrant

Super easy Local WordPress Development Environment

In this tutorial I will explain how to setup a local WordPress development environment using Vagrant. Vagrant is a command line utility that manages our virtual machine’s lifecycle. In this instance we will be using Scotch box. It comes preconfigured with everything for WordPress to run.

Additional Requirements

ScotchBox explains how to set up the server in their docs and everything that we will need. We will need to download Vagrant.  We will also need to download the Virtual Box application.

Applications used for this setup

Setup our sites directory with ScotchBox

Open the terminal and cd to the directory that we want the sites to live. (I created a directory called Sites in my home directory.)

Mac Finder Window with sites highlited for a WordPress development environment

Then run the following commands:

cd Sites<br /> git clone my-project<br /> cd my-project<br /> vagrant up<br />

At this point we should have ScotchBox running. Once this is complete we should be able to go to and see the information screen. That address is set to point to the /public directory inside the sites folder, so we could run our WordPress sites in that directory. For this exercise we will be putting projects into the Sites directory.

Set up a hostname

Open the hosts file. On a mac it is located in /etc directory. Then we will write our development domain below everything in the hosts file. Add the entry like this:

hosts file for a local development domain

Create the site directory

At this point we will need to create a directory for our first site to live and we will do that within the Sites directory. So create a folder called wordpress. Then we will need to download WordPress into this Folder.

mac finder window

Virtual Hosts

Once we have WordPress in the folder it’s time to create our Virtual Hosts in the vagrant machine. In this step we need to SSH into the vagrant machine, create a configuration file in apache which we can copy the default.

cd Sites vagrant ssh cd /etc/apache2/sites-available sudo cp 000-default.conf wordpress.conf

Once we have made a copy of the default configuration file we need to modify the new wordpress.conf file. We will only need to edit two lines of the file.

The first line we need to change is theServerName line. So it should read like this: ServerName and this should match the domain we entered into the hosts file earlier. The second line should be theDocumentRoot which is where it tells apache to find our files. This one should read like this: DocumentRoot /var/www/wordpress.

Vhosts config file for apache

Keep in mind that the wordpress folder was created on our system in the Sites folder, but it’s also available through the server in /var/www/wordpress. This is why the directory structure is different, but whatever files we create in either folder will be shared with each other. So we can write code on our machine and it will be updated to the virtual machine automatically.

Now that we have modified our conf file we should be able to save and close it. If you are using nano, then press ctrl + 0 then ctrl + x to save and close the file. Then we need to run the following commands to initialize the site within apache:

sudo a2ensite wordpress.conf<br /> sudo service apache2 restart

Now we can access the wordpress install by going to and we will be able to run through the wordpress install process. We now have a fully functioning WordPress development environment with the help of vagrant and scotch box. With this setup we can include as many sites as we want in our Sites directory and run as many WordPress installs as we need.