How to Install WordPress Locally With Vagrant

By Daniel Pataki. in WordPress. Updated on October 18, 2022.

Developing locally is one of the best things that can happen to you. Not only does it let you dispense with upload/download times, but you can also create as many projects as you want, work with real domains locally and generally speed up everything you do.

Vagrant is a great piece of software that create reproducible and portable virtual machines, which you can use as local web server environments. In this article, I’ll show you why Vagrant is so awesome and how you can get up and running with awesome WordPress testing environments pretty quickly.

You may also be interested in the following posts:

What is Vagrant?

In Vagrant’s own words, it can be used to “create and configure lightweight, reproducible, and portable development environments”.

Let’s find out what each of those terms means with regards to your local environment.

Configurable

Your virtual machine is easy to create, easy to configure, and more importantly: it can be extensively configured. Default setups are just fine for most projects and casual testing,so you don’t have to fiddle around with it, but if you need the power, it’s there.

You can set things up just like you would in a real server environment; from configuring the IP to automatically installing git and other software, it’s all possible and up to you.

Lightweight

I run multiple virtual machines on my computer, and each one has two configuration files with a combined size of no more than 4KB — that’s right, two files, 4KB in total. To be honest, my setups are all pretty basic, but even if you have something extremely elaborate, it will amount to 10-100KB at the very most.

Portable

Portability comes with the fact that the files have a tight waistline. One file is a special Vagrantfile, the other is a bash file; each contains simple text, nothing special. As a result, you can email them back and forth and save them on Evernote, Google Drive, or Dropbox.

Reproducable

This is one of the best features of Vagrant. Due to the size and portability of the files required, specific server configurations can be replicated with ease. Suppose you create an application that requires a highly tuned server. Create the Vagrantfile and the installation bash file for it and get it up and running.

You can now email the configuration to your team members, and they will be running the exact same server within a few minutes.

Installation

Generally speaking, there are three parts to getting started with a development environment using Vagrant.

Install Vagrant & Virtualbox
Create a server configuration
Create your web environment (eg: install WordPress)

Installing Vagrant

Vagrant can be installed by visiting the download page, selecting your OS and running the downloaded package. Since Vagrant relies on virtualization, you’ll need virtualization software.

Vagrant has built-in support for VirtualBox but can be made to work with others, but for the sake of this example, we’ll go with VirtualBox. Grab it here.

Creating a Server Configuration

You can use ready-made scripts to do everything for you. Jeffrey Way has put together a great tutorial about ditching MAMP and going with Vagrant instead. Take a look and make sure to note down the code at the top:

curl -L -o 'install.sh' https://bitly.com/1hBfq57 && curl -L -o 'Vagrantfile' https://bitly.com/1mE3Qt9 && vagrant up

If you create a folder, navigate to it using your terminal or command prompt and paste the code above, you will have created a local environment in one quick move. Let’s dissect this, though, and see what is happening.

It consists of 3 parts:

curl -L -o 'install.sh' https://bitly.com/1hBfq57

This command downloads a pre-made installation file: the install.sh file responsible for installing and configuring software once the virtual machine is running. PHP, Apache, MySQL, and other similar things are taken care of here.

curl -L -o 'Vagrantfile' https://bitly.com/1mE3Qt9

This will download the Vagrantfile which contains information about the server configuration and other basic installation instructions. This determines the operating system the server uses, and the IP the network is mapped to; it can be used to control file permissions and ownerships, and more.

vagrant up

This command boots up the server.

When you do this for the first time, it will take anywhere between 5-20 minutes. The so-called “box” needs to be downloaded (this contains the OS, for example), which may be around 700+ MB. The server is then provisioned (installed and configured) and will be up and running.

If you restart your computer or shut down the virtual machine (VM), you will need to run the command again. This time it will only take a couple of seconds to get it running.

In a nutshell, this is very much like installing your OS and environment on a computer. The Vagrantfile takes on the responsibilities of the Windows/Linux/Mac installation disk; it has everything needed to get the basic system working. The install.sh file automates the initial software needs. For your computer, this would be like installing the newest video driver, Photoshop, your favorite text editor, browsers and so on.

The vagrant up command is akin to turning on your computer. When you do this for the first time, it takes quite some time because you’ll need to install the OS and the software. After that it takes 10-20 seconds to get things up and to run.

Installing WordPress

If you’ve followed the instructions here, you should now have a server up and running, but what can you do with it, how can you use it?

Here are a few things to know:

You can reach the local environment via http://192.168.33.21
The html folder within the installation directory is your root directory
Access to your MySQL database is as follows: Username: root, Password: root and Host: localhost.

The first thing we should do is use SSH to gain access to our server so we can set our database up, getting it ready for WordPress.

Use the terminal to go to the folder you’ve installed your virtual machine in and type vagrant ssh.

Once you’re in, you can type mysql -uroot -p to gain access to MySQL, type root when prompted for the password.

All we need is a simple empty database for WordPress which we’ll create with the following command: CREATE DATABASE wordpress

Next, go to the WordPress download page and grab the latest version. Extract it into the html directory (the root directory) and make sure to move all the files from the created wordpress sub-directory a level up.

In the end you should see the two WordPress directories (wp-admin, wp-includes) and the default WordPress files right inside your html directory.

Detour: Troubleshooting

If you follow these instructions, you’ll find that you may not be able to upload files via the WordPress interface. This has to do with user and group issues, which can be easily fixed.

SSH into the server and type the following sudo vi /etc/apache2/apache.conf. This will open a VI editor you can use to edit this file.

Note: This will be a bit alien to many but never fear, here are some specific instructions. If you need some more help, take a look at a VI cheat sheet.

Type /User. This searches the document for occurrences of “User”. You should see the section where you can define the user and the group.

Press “i” to go into Edit mode. Use the arrow keys to navigate with the cursor and edit the user and the group to be “vagrant”, like this:

User vagrant
Group vagrant

Once done, press escape, then type the following command: :wq. This saves the file and quits the vi editor.

You should now type vagrant halt to stop the virtual machine, followed by vagrant up to restart it.

That’s it, file operations will now work in WordPress.

At this point, you can visit http://192.168.33.21 and install WordPress as usual. Make sure to use the database access credentials above and the database name you created. You can install plugins, themes, create your own code, and do anything else you normally would do on a real server.

Changing the Hostname

http://192.168.33.21 is not exactly the most friendly way of opening up a project. Luckily it’s easy to change this to something easier to remember, such as http://wordpress.local.

SSH into the server and navigate to the site configurations folder by typing cd /etc/apache2/sites-available.

Type ls to list the contents of the folder. You should see a file named 000-default.conf. Let’s edit this file to see what it contains by typing sudo vi 000-default.conf.

Press “i” to enter Insert mode and navigate down to line 8 which should say #ServerName www.example.com. Using the ServerName directive, you can create a named route to the website.

Uncomment the line by removing the hash at the beginning and changing the server name to whatever you’d like. It is customary to use something like wordpress.dev, wordpress.local, or perhaps even just wordpress — it’s up to you. In fact, you could even use facebook.com!

Save the file by pressing escape and typing the :wq command and restart the server by typing sudo service apache2 restart.

Finally, outside of your virtual machine (make sure you are not SSH-d in) edit your hosts file using the sudo vi command. On Windows this can be found at C:\windows\system32\drivers\etc\hosts, on linux based systems it can be found at /etc/hosts

Add the following line to the file anywhere:

192.168.33.21    wordpress.local

Make sure to use the hostname you defined in the config file and save the hosts file. This file essentially tells our computer were to load a server name from and how to resolve it. By default, your computer will look to the Internet. If you type in facebook.com, it will load it from the web.

However, if you’ve bound facebook.com to the virtual machine IP and defined it as the ServerName, it will load it locally.

You should now be able to type wordpress.local and see the same result as when you typed 192.168.33.21.

If you do this after you install WordPress you may see things such as styles and scripts broken. The reason is that WordPress stores the installation target location in the database and it will be set to the IP.

To make sure this doesn’t happen you should create your named server first and install WordPress by going to wordpress.local (or whichever other name you chose) instead of using the IP.

Using Virtual Servers

We’re now doing well, but as it stands, we’ll have to run a virtual machine for each project which is a waste. By using virtual servers you can run as many independent websites as you’d like from the same virtual machine.

The key to this lies in the site configuration file, the same file we used to change the ServerName. Let’s create two virtual hosts now.

First, go to the directory you created the virtual machine in and create two sub-directories: blog and store. Your original HTML directory should still be there as well.

Next, SSH into the server and navigate to the /etc/apache2/sites-available directory.

Create two new files by copying the default config file:

cp 000-default.conf blog.conf;
cp 000-default.conf store.conf

Edit the shop.conf file using the method we discussed previously. Make sure the ServerName is set to shop.dev and set the DocumentRoot directive to /var/www/shop — this is the directory we created just now.

Do the same with the blog.conf file, using the correct values.

Use the sudo a2ensite blog and sudo a2ensite shop commands to enable these sites and use the sudo service apache2 restart command to restart the server and quit the SSH connection by using the exit command.

Now edit the hosts file to make sure our computer knows how to resolve the virtual hosts:

192.168.33.21    blog.dev
192.168.33.21    shop.dev

Now you have two more sites to work with: one can be reached by typing blog.dev in the URL bar, and the root directory of this site will be the blog directory. The other is the shop.dev site, which uses the shop directory as its root.

This is a lot easier than creating multiple virtual machines and will require less resource usage from your computer.

Conclusion

We went through a lot in this article: we installed Vagrant, learned how to create a local environment, and installed WordPress. We also learned a few tricks, such as using server names and virtual hosts.

This should get you started on the path to local development. Don’t forget that you can easily recreate your environment anywhere, all you need is the Vagrantfile and the install.sh file.

Do more!

We’ve only just scratched the surface of what Vagrant can do. You can find custom boxes to work with at Vagrantcloud or you can even look up boxes which will mimic your actual online host environment.

A lot of tasks can be automated and/or customized and you can use automation tools such as WP-CLI to install WordPress and related plugins/themes using a few commands.

Finally, take a look at some WordPress-specific Vagrant environments such as VCCW, Vagrantpress and the 13 Vagrant Resources from WPTavern.