Setup a Local WordPress Development Environment with Vagrant
On this page
- Installing VirtualBox
- Installing Vagrant
- Installing Git
- Install Varying Vagrant Vagrants
- Additional Tools
If you develop with WordPress, it is preferable to set up a local environment where you have installed a server, a database tool, and a few Wordpress sites along with other tools that you need. This is fine if you only work on a few projects. But when they multiply, problems occur. And also the headaches of maintaining multiple environments, because the client has a different setup than you do.
To work around this problem, we can use what we call Vagrant. Vagrant is a tool for working with virtual environments. It provides an easy way to set up a local development environment with a few commands, and you can replicate a complete setup as many times as you want, with ease and without the hassle of installing everything manually. To run Vagrant, you need to define a set of rules. Vagrant sets up your virtual machine based on these rules. Vagrant needs two files for this: Vagrantfile, which tells Vagrant what kind of hardware the virtual machine needs, and a deployment file, which tells Vagrant what to do on the virtual machine.
Because Vagrant works with virtual environments, you need virtual machine software to run Vagrant. For our purposes, we will use the Open Source Virtualbox.
Head over to the download page of Virtualbox and download a binary file corresponding to your Guest host. (Guest host is the Operating system from where you will be running your dev environment.) Install Virtualbox.
Download the binary corresponding to your operating system from Vagrant's download page and install it.
To test whether its successfully installed, type the following command in your OS's command-line.
$ vagrant -v
Installing Vagrant Hosts Updater Plugin
The vagrant-hostupdater plugin will modify your OS's hosts file so that the domains set up by Vagrant works. To install it, run the following command
$ vagrant plugin install vagrant-hostsupdater
Reboot your OS after installing Vagrant/Virtualbox so that there are no networking issues.
We will also need Git version control for this tutorial. If you don't have it installed, then install it by using the following command if you have a Debian/Ubuntu distribution
$ sudo apt install git
or if you have Fedora
$ sudo dnf install git
or if you have CentOS/RHEL
$ sudo yum install git
Check the version of Git installed via the following command
$ git --version
You will see something like
$ git version 2.20.1
You need to setup Git via the following commands.
$ git config --global user.name "Your Name"
$ git config --global user.email "[email protected]"
To install Git on Windows, head over to Git's Download page and install the binary.
If you have homebrew installed, then you can install Git via the following command.
$ brew install git
or you can download a binary package from Git's Download page and install it.
Install Varying Vagrant Vagrants
Instead of creating a Vagrant set up from scratch, we will use Varying Vagrants Vagrant(VVV) - an open source Vagrant configuration aimed specifically at creating WordPress Development Environments. A standard VVV will sets up your Virtual machine based on Ubuntu 18.04 along with Nginx server, MariaDB database, PHP, WP-CLI, Node.js, MailHog, Composer, memcached, phpMyAdmin, git and various other tools. VVV will give you multiple WordPress installations by default, one of them being the latest bleeding-edge version to help you experiment.
First step is to clone the Git repository of VVV to a local directory on your system.
$ git clone -b master git://github.com/Varying-Vagrant-Vagrants/VVV.git ~/vvv
Here we are cloning the master branch of the repository on the system. If you want faster updates, then you can use the develop branch.
Change to the directory where you cloned VVV.
$ cd vvv
Launch Vagrant environment which will install the Virtual machine and set up everything.
$ vagrant up
This process can take a while so be patient. You may be asked for your root password during the process which is required for setting up your system's hosts file.
Note for Windows 8/10 Users
If you are on Windows, then you may get the following error
==> default: Booting VM...
There was an error while executing `VBoxManage`, a CLI used by Vagrant
for controlling VirtualBox. The command and stderr is shown below.
Command: ["startvm", "1fe83aa1-2f23-4ddd-ad77-b7e7e00aabe6", "--type", "headless"]
Stderr: VBoxManage.exe: error: Failed to open/create the internal network 'HostInterfaceNetworking-VirtualBox Host-Only
Ethernet Adapter #3' (VERR_INTNET_FLT_IF_NOT_FOUND).
VBoxManage.exe: error: Failed to attach the network LUN (VERR_INTNET_FLT_IF_NOT_FOUND)
VBoxManage.exe: error: Details: code E_FAIL (0x80004005), component ConsoleWrap, interface IConsole
Note the Adapter referred here:
VirtualBox Host-Only Ethernet Adapter #3
Open Control Panel >> Network and Sharing Center. Now click on Change Adapter Settings. Right click on the adapter whose Name or the Device Name matches with VirtualBox Host-Only Ethernet Adapter # 3 and click on Properties. Click on the Configure button.
Now click on the Driver tab. Click on Update Driver. Select Browse my computer for drivers. Now choose Let me pick from a list of available drivers on my computer. Select the choice you get and click on Next. Click Close to finish the update. Now go back to your Terminal/Powershell/Command window and repeat the vagrant up command. It should work fine this time.
Once this is finished, you can visit your VVV dashboard at http://vvv.test url.
VVV comes with two default WordPress installs - http://one.wordpress.test and http://two.wordpress.test Both sites have same login details, admin as username and password as password. Database credentials for both sites are wp as username and password. MySQL Root user credentials are root as both the username and password. And the VM's root user's credentials are root as username and vagrant as the password.
There is a developer wordpress install at http://trunk.wordpress.net but it won't work since it was not provisioned. This install is useful if you are a WordPress contributor who works with Trac tickets and patches. To enable it, open vvv-custom.yml and change the value of skip_provisioning under wordpress-trunk to false and then reprovision the VM by using the command
$ vagrant reload --provision
There is another wordpress install with no url labled as wordpress-meta-environment. This install will create an environment useful for contributions to the WordPress meta team eg, WordCamps, .org etc. To enable this install add the following line under wordpress-meta-environment in the file vvv-custom.yml.
And then change the value of skip_provisioning to false and reprovision the VM.
$ vagrant reload --provision
Add a New Site
If you want to add another site to the VM, you will need to edit the vvv-custom.yml file which you can find in the vvv directory. If its not there, just copy vvv-config.yml and create it. This is a one time process and you won't need to do it again. Always make your changes in vvv-custom.yml because vvv-config.yml gets overwritten when you update VVV.
Add the following code under the sites section to vvv-custom.yml to add a new site.
newsite: repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template description: "A WordPress subdir multisite install"
nginx_upstream: php skip_provisioning: false hosts: - newsite.test custom: wp_type: subdirectory
repo variable refers to a predefined Github repository which contains information on how to set up a new WordPress site on the VM. For now, we are using a repo maintained by VVV.
description variable is self-explanatory.
vm_dir is the actual directory inside the VM where your site will reside.
local_dir is the directory on your host machine where your site lives.
branch variable tells Vagrant to check out the master branch of the repo in the example here.
nginx_upstream is used to set where Nginx passes requests to and is usually used to change the PHP version needed for your install. php here refers to the default PHP version which is 7.2. You can use php71 to change it to PHP 7.1 or php56 to change it to PHP 5.6.
skip_provisioning is set to false which means we need to include this site on to the VM.
hosts variable is used to set the url which we will need to access the site.
custom section is useful if you need some additional control over your WordPress site. You can use this section to setup multisite installation or install a different version of WordPress and even change the name of the database or your site that will be used for your installation.
wp_type variable decides whether your install will be a single, mulsite with domains or multisite with subdirectory. wp_type takes four values: single, subdomain, subdirectory and none. With subdomain install, you can define multiple hosts for your multisite installation in the following format
hosts: - multisite.test - site1.multisite.test - site2.multisite.test custom: wp_type: subdomain
You can add one more variable under the custom section which is wp_version. You can set it to nightly if you want to install the Nightly version of WordPress. It takes three values: nightly, latest and a version number.
custom: wp_version: nightly
There is another variable, db_name which allows you to set the name of the database for your installation.
custom: db_name: super_secet_db_name
And lastly, site_title variable allows you to set the Title of your WP site.
custom: site_title: My Awesome Dev Site
This should cover all the variables and options you would need to add your own website in VVV. After changing the vvv-custom.yml file just run the following command to make your new site work.
$ vagrant reload --provision
Add an Existing Site
So far, we learned how to add an entirely new site to VVV. But what if you are already working on a site and want to add it under VVV. Let's see how we can do that.
To add an existing site, the first step is same as before, i.e. editing the vvv-custom.yml file and adding the following code.
howtoforge: repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template description: "A WordPress site"
hosts: - howtoforge.local
This will tell VVV to setup a new site accessible via http://howtoforge.local But its an entirely new site. What we need to do is to convert it into our existing install. For this we need to copy over the files from our existing WordPress installation over to the local directory i.e. /home/user/vvv/www/newsite
$ cp /var/www/howtoforge/ /home/user/vvv/www/newsite/
Now we need to copy the database. A simple way of doing it is to export your existing database as a .sql file, copy that file over to our blog's directory and by importing the database again by SSHing to our VM.
First, login to mysql in your local system's command line and use the following command to export the database.
$ cd /home/user/vvv/www/newsite $ mysqldump -u username -p database_name > data-dump.sql
Now we can provision the VM again.
$ vagrant reload --provision
SSH into your VM.
$ vagrant ssh
Now import the database back into your VM.
$ cd /srv/www/newsite $ mysql -u root -p newsite < data-dump.sql
VVV has already created a new database during provisioning for our blog named newsite. The password for root user is root here. The above command will import our existing database into the new one.
This completes the setup of an existing site in VVV.
Localhost installs are usually not secured. And installing your own certificate on localhost can be a lengthy and a tedious process, even with Let's Encrypt. But VVV makes this process quite easy and by default has SSL enabled on all your WordPress installs. Just start using https with your sites. For the first time, your browser will complain about an invalid certificate but add it as an exception and it should be fine from now on.
You can update your WordPress install from your dashboard. Also, VVV will update your wordpress whenever you reprovision the VM. You can also update WordPress manually by downloading it from WordPress.org and extracting the zip file. And you can also use WP CLI which is bundled with VVV. To update your site with WP CLI, use the following commands.
$ cd /srv/www/newsite $ wp core update
First step is to stop the Vagrant machine.
$ vagrant halt
Now make sure, your vagrant and Virtualbox are up to date. If not, download them again and install.
Run the following command to update your Vagrant box. It is optional but its best that you should go ahead with it.
$ vagrant box update
Now, pull the latest VVV version from Github.
$ git pull
Reprovision the box again to complete the update.
$ vagrant up --provision
VVV ships with various utilities that you can install. You will find them listed under utilities section in your vvv-custom.yml file. By default, tls-ca and phpmyadmin are enabled. You can further install memcached, opcache, webgrind, mongodb, tideways and php versions from 5.6 to 7.3 by removing the # in front of them in the utilities section.
You can even add your own software you want to install. You would need to modify the vvv-custom.yml file with something like
utilities: core: - tls-ca
- phpmyadmin java: - java7 utility-sources: java: repo: https://github.com/example/java-utilities.git branch: master
You will add a new section, java here, for example. The code for the installation will come from a git repository. Your git repository should be structured something like
The provision.sh file will contain the necessary code to install java in your VM. The name of the folder should match the name you used above in the vvv-custom.yml file.
That concludes our tutorial on how to set up a local WordPress development environment with Vagrant. Let us know if you have any questions.