A Detailed Guide on Varying Vagrant Vagrants for WordPress

It’s been four years since I have been actively using WordPress for my client’s web application projects. Being a WordPress developer and contributor, it takes a lot of time and effort to set up a local environment for my WordPress projects.

I believe that most of the WordPress customizers or even the WordPress plugin and themes developers use Desktop servers such as MAMP, LAMP or XAMPP as their local server environment.

Why not use them? They have all the required resources to run WordPress efficiently bundled already within them. Also, easy to implement and to interact with.

No doubt that for beginners, the Desktop servers are great software for setting up WordPress on Local machine and getting started with it.

So, What is the Problem With Desktop Servers?

Scenario 1: Repetitive Robotic Tasks

If you are a regular WordPress person, eventually you’ll start to notice that you have to do everything from scratch while you set up WordPress for a new project on the Desktop server.

The repetitive tasks like

1. Downloading WordPress. (Also updating the WordPress)
2. Database Creation
3. Database Connection
4. Setting up WordPress credentials
5. Setting up wp-config.php for debugging.
6. Essential Plugins installation.

and a whole lot of other repetitive and boring tasks. At first, it looks normal to perform these tasks every time a new project arrives but by the time it feels like somewhere these tasks are consuming your precious time.

There should be a way to perform these tasks automatically. When you feel like you need something to perform all the robotic tasks automatically for you, that’s when the VVV (Varying Vagrant Vagrants) comes in to the picture.

Scenario 2: Development Environment Synchronization

Suppose you are working on a project with a remote WordPress development team. and You don’t have any freaking idea about their local development environment setup (OS configurations, dependencies, libraries, etc.) Unless you guys waste a lot of time on Video conferencing to tell each other your local dev environment setup.

In this case how you guys will synchronize your project development environment. What if there is a bug on your local environment setup but not on the other developer’s system. You know what they say in this situation “Works on my machine bug”.

Naturally, there will be chaos as the project will grow bigger and bigger and you’ll all struggle to maintain your development cycle. The common and easy solution is to create a configuration file that contains the instructions to set up a standard local development environment.

And Tell each developer to set their local machine environment according to that configuration file… but wait What if I don’t want to change anything on my current system as I love to work with all my present configurations and settings.

Here’s where the scenario 3 comes in

Scenario 3: Complete Isolation

When you install the desktop servers on your machine, they simply use your current system resources and make changes to the current configuration as their runtime requirements.

Let’s say when you install Apache and MySQL on your system, by default your current system acts as a server machine. With a few configuration options, even you can make your current system live running on the internet. This feels a little creepy when you think of your personal computer as a server.

Indeed, it is true that desktop server software modifies your computer settings. If you are a beginner and don’t know what I am talking about, let me show you a practical.

1. Start the desktop server (e.g. XAMPP, LAMP or MAMP) you have installed on your computer.

2. Connect your phone to the same Wi-Fi network as your computer (where the Desktop servers are running) is connected with.
3. Find your computer local IPv4.

• For Windows User: Win+R -> CMD -> Enter Command ipconfig /all. and look for the wifi adapter, copy the IPv4.
• For LINUX and MAC: Open terminal -> Run Command ifconfig, and copy IPv4.
• It will be like (192.168.x.x)

4. Once you have the local IP address, open the browser on your phone and paste the local IP address in the browser’s address bar and boom!!!!!!!!

5. Your default desktop server page (localhost or 127.0.0.1) can be accessed on your phone through the local IP address. and let me remind you that the IP address belongs to your Personal computer. This is the point where I say “What the heck?” why my PC is acting as a server

In other words, there is no isolation between the local development environment and your machine. At this point, VVV (Varying Vagrant Vagrants) comes in the scene for WordPress.

Scenario 4: Contribution to WordPress Core and Meta websites

There is a whole lot of documentation on contribution to WordPress core and META websites. Also, you can create a local development environment as the WordPress core project requires. but, Believe me, there are a lot of things you need to know before you start to contribute code to WordPress. 

Even if you are proficient in PHP or JavaScript and know enough about WordPress, still you need a local development environment according to WordPress’s core contribution guidelines.

So, if you want to avoid reading a whole bunch of documentation on setting up WordPress’s core contribution environment, VVV is your way to achieve it effortlessly. Here I have found a guide to contributing to WordPress core.

But first, you need to know about VVV and how to set it up on your machine. Let’s start with the Term Vagrant.

What Is Vagrant?

If you often work with Virtual Machine simulators like VMware, VirtualBox or hypervisor you may have heard about Vagrant. If not, then, In the simplest term

Vagrant is a command-line tool to manage virtual machine environments. It is a tool to manage and manipulate virtual machines’ environments through a text-based interpreting file called Vagrantfile.

Vagrant is open-source hence the source code can be modified according to your needs. It is developed by Hashicorp and is written in Ruby language.

Vagrant works for virtual machine simulators like VirtualBox, KVM, Hyper-V, Docker containers, VMware, and AWS.

Now as you know the formal definition of Vagrant, I would like to explain it in my way.

In the simplest form, Vagrant is software that can be installed on host machines (Windows, Linux or Mac) and with the support of a Virtual machine simulator it allows to automatically create the virtual machine environment as described in the Vagrantfile.

All you need to do is create a Vagrantfile and run command vagrant up and everything will be done automatically.

Few things more you need to know before getting started with Vagrant are:

1. Vagrant Box – Nothing fancy, just a pre-packaged Virtual Machine environment that can run on any platform regardless of the OS or hardware type. There is a Vagrant Box library from where you can either download a Vagrant Box or you can upload one of your own. This is how developers share the environment while working with Vagrant.
2. Provider: It is the location where the Virtual environment runs. For example, your Personal computer or any other machine where the Virtual machine simulator and Vagrant are installed.
3. Provisioner: it is the most important tool which finally sets ups the virtual environment on the machine. A provisioner may be a simple shell script file or a professional framework tools like Chef, Puppet, or Ansible.

At this point you may wonder that Vagrant is good but what’s in it about WordPress? Don’t worry in the next section you’ll get the whole picture and the role of Vagrant in it.

What is VVV (Virtual Vagrant Vagrants)?

Before introducing you to VVV, I would discuss a little bit about history. There was a Web development Agency (it is still there) called 10up. They primarily work with WordPress. All was going nice but at one point their developers started to feel overwhelmed because of the repeated robotics task of configuring the WordPress development environment each time when a new project came on board.

So, the brilliant developers of the 10up agency came up with this idea to create a universal configuration for local WordPress development. They created a Vagrant configuration especially for WordPress that includes all the necessary software and other dependencies that are required to run WordPress efficiently in a completely isolated environment.

And they called this configuration VVV or Varying Vagrant Vagrants. It was initially used for internal project needs for 10up. In 2014 they decided to make it an open-source and community-driven project. Now The VVV is MIT licensed.

Objectives of VVV:

1. Approachable local development environment with Modern Server configuration for WordPress themes and plugins development
2. A stable set of software and configuration in default provisioning

At this point, I’m sure that you have a common idea behind using VVV for WordPress. Without wasting further time let’s dig deep into the step by step method to setting up VVV for the first time.

What VVV installs for you?

A bunch of modern software set to make a fully-featured modern server environment. Here is the list of tools you got

Step by Step Process to Setting up VVV

In this section, I will show you how to set up VVV for the first time. Follow the steps carefully and if all goes well, you’ll end up having a nice working VVV configuration on your system.

Hardware Requirements:

First thing first, Let’s talk about the minimum hardware requirements for the VVV configuration. So according to the official documentation of VVV, you need following things to set up VVV on your system

If your system is Okay with the above hardware configuration you are good to go for required software installation.

Software Requirements

At this point, the actual practical configuration for VVV begins. All the requirements must have to be fulfilled to run VVV efficiently on your system.

If you are reading this line, means you have done installing the required software. It’s time to reboot your computer system to work virtualization and Vagrant properly with your host OS resources.

Installing VVV

Finally, Here’s the step you are waiting for. There are two ways to install VVV on your computer.

1. Using GIT repository – Recommended
2. Using ZIP file

Using GIT Repository:

It is the recommended method because the GIT repository of VVV always stays updated with the new features and bug fixes. To update your local installation, you just need to hit git command git pull and your installation automatically updated to the latest version.

To install the VVV from GIT all you need to do is open your terminal or (CMD if you are on Windows) and fire below command:

git clone -b master git://github.com/Varying-Vagrant-Vagrants/VVV.git ~/vagrant-local

Here notice the vagrant-local directory. Where all of your VVV files reside. Also, the local WordPress installation can be found inside the vagrant-local/www directory.

If you want bleeding-edge features and faster updates of VVV, you can alternatively use the develop branch instead of the master branch.

Without GIT (Using ZIP file):

Although it’s not recommended if you want to install VVV without using GIT, you can simply download the VVV develop branch zip from the GIT and extract it into the directory vagrant-local.

Also, you can download the latest stable release zip file from the same repository.

I recommend you to install VVV from the first method i.e using the GIT method.

Essential Configuration Changes Before First Boot of VVV

If you made it to this section of our guide, you are ready to launch VVV for the first time. But wait, there are still a few changes you need to make before you start VVV for the first time.

Remember your local VVV folder is vagrant-local (the location where we have cloned the GIT repository) from now on whenever I mention the VVV folder, which means I am pointing to the vagrant-local directory on your system. All the commands from here should be run from the location inside the vagrant-local folder.

As you can see in the picture above, there is a folder called config, In which all the VBOX configuration files reside.

In vagrant-local/config there is a file called default-config.yml which contains the configuration regarding the first provisioning. All the WordPress site and their configuration can be managed from that file only.

It is a good idea to create a custom configuration file based on the default configuration file before we make any changes to the configuration. To create a custom configuration file you need run command vagrant status inside the vagrant-local folder. And it will create config/config.yml copying the content of the default-config.yml file. Now you can make changes to the custom configuration file i.e. config.yml

Note: While working with a YAML file, you should keep in mind that Whitespace and tabs mean different things. It is really important to stick with whitespaces when editing the YAML file, otherwise, there will be issues in provisioning.

Starting VVV for the First Time

You are ready to roll VVV for the first time. It’s not rocket science but still needs attention. Follow the steps carefully

1. Open terminal or CMD for windows users. (Windows user must open CMD with administrator privileges)
2. Cd to VVV folder i.e. cd vagrant-local

3. Start Vagrant with command vagrant up

At this point, if you followed the instruction from the start, Vagrant should start its magic. It could take some time because it’ll download required files on a local machine.

4. Wait until the script finishes. For Linux and Mac users it may ask for the SU password to update the local machine hosts files.
5. If It all goes right you will end with the VVV logo and Teddy bread artwork on your terminal.

6. Now you can visit http://vvv.test (Dashboard) to view your provisioned WordPress website.

What Did the Vagrant Up Command Do?

You might wonder what was going on after you fired the command vagrant up.

For the sake of clarity and of course knowledge, you should know how that worked and what just happened?

When you entered the command vagrant up, it started to download a pre-packaged Vagrant box that contains the basic virtual machine. Earlier versions of the VVV used Ubuntu 14.04 LTS as a basic virtual machine but after the version 3.0, they have replaced the basic virtual machine with Ubuntu 18.04. And it’s about 800MB.

Once the Vagrant Box is downloaded it starts Virtual Machine in a sandboxed environment. Once the machine boots up, it starts the provisioning scripts that came with the VVV.

Also, the provisioning script will download around 100MB of other packages. Once it’s all done your local WordPress installation is ready to get started.

The time the vagrant up will take solely depends on your internet connection. The faster the internet connection, the faster vagrant up finishes.

Don’t worry, only for the first time, it takes some time to download and set up the things, so you can work efficiently in the future.

Once the package box is cached in the local machine, future runs of vagrant up will only need to apply the newly requested provisioning.

Note: if you want to see vagrant up magic, you can simply open VirtualBox on your system and there you can a virtual machine running named vagrant-local_{id}. Isn’t it awesome? That by just issuing a command vagrant up, the whole configured virtual machine is running with the environment you desired. This is the power of VVV.

Basic Commands to Work with VVV for WordPress:

If you have followed the installation instructions, you must have seen some of the vagrant commands such as vagrant status and vagrant up. Here I would like to show you some other basic commands to control the vagrant environment on your local machine.

Create config file: vagrant status

You have already seen vagrant status command in action, where you have passed this command to create config.yml file from default-config.yml file. You only need to run this once before starting the VVV for the first time.

Start Vagrant: vagrant up

vagrant up commands starts the VVV environment. And if you are starting VVV for the first this command also runs the initial configuration provision files.

Restart VVV: vagrant reload

vagrant reload commands help you to restart the VVV environment if you wish to restart it.

Stop Vagrant: vagrant halt

To stop the VVV, just issue the command vagrant halt and all the services that are started by VVV will be immediately stopped.

Warning: On the official website of Vagrant you might come across the command vagrant destroy. But keep in mind that vagrant destroy command will remove the vagrant box from the caching and also you’ll lose the provisioning. Unless you want to install VVV from scratch, be careful while using vagrant destroy.

Reload config/config.yml

You might wonder how VVV will notice the changes you make to the config.yml file. Well, there is command vagrant reload –provision which will tell vagrant to provision again according to the changes made to the config.yml file.

Note: Each time you make changes to the config.yml file, You have to reload the provision using vagrant provision or vagrant reload –provision. If the VVV is already running, you can simply issue the vagrant provision command.

By default VVV sets up two local WordPress installations for you. What are they let’s have a look at them

Default Websites You Got in VVV

If you are here that means you have successfully installed the VVV and also completed the first provision of VVV using vagrant up command. You can see the VVV dashboard here http://vvv.test

Once you visit the VVV dashboard you’ll notice that there are by default two local WordPress installations.

1. http://one.wordpress.test – Standard WordPress installation, useful for Plugin development, themes development, and testing.
2. http://one.wordpress.test – These also have a standard WordPress installation the same as the first one, the only thing this includes is a pre-installed query monitor plugin.
3. http://trunk.wordpress.test – It is an SVN based WordPress core setup. Useful for contributing to WordPress using tickets, patches, etc. Also, it’s suitable if you are organizing WordPress contributors day. By default, the installation is skipped in the default-config.yml file as skip-provision: true. If you want to enable it just change the value from true to false.

Note: Also, there is by default setup for the WordPress meta website in the default-config.yml file. But the default provision is set false because it makes provision lengthier in terms of time. But if you are interested in contributing to the WordPress meta sites, just set default settings as skip-provisioning: false and you are good to go.

You always get the latest version of WordPress, unless you mention specific version in the config.yml file

These are the standard WordPress installation you got from the default-config.yml file.

These local installations of WordPress are configured specially for themes and plugins development.  They say if you are a theme or plugin developer, these two WordPress installations would be enough for you, as you can use them for many themes and plugins.

But you might be wondering how to add custom WordPress installations or new WordPress sites. Be patient next section is about adding a new WordPress website using VVV.

Note: Default username and password you for WordPress admin is: admin and password is: password

How to Add a New Website to VVV?

As you are coming from understanding Vagrant to installing VVV, you must have had overwhelming thoughts about adding a new website to VVV.

Okay let me tell you first, It’s really easy to add a new WordPress installation to VVV, Still not convinced, what if I tell you that it’s a lot easier than the adding site to XAMPP, MAMP or LAMP.

You just need to edit the config/config.yml file to add a new website in VVV.

Suppose you want to add a standard WordPress installation with the domain name: dev.test

Another thing you keep in mind is selecting the site template.

What are site templates?

Site templates are shell script-based WordPress installation configuration, structured to follow VVV provisioning. You can have your oven site template; you just need to have a directory structure as guided by the VVV for the site template. Know more about the site template on the official VW website.

VVV provides two default site templates

1. custom-site-template – A standard WordPress installation. Suitable for theme and plugins development and Testing.
2. custom-site-template-develop – For working with Core WordPress development. E.g. contributing to WordPress, or enhancing WordPress itself.

Now as you have domain and site template, you just need to add below line of code under the site: in config.yml file

sites:

  .... other sites...

  dev:
    repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template.git
    hosts:
      - dev.test

.... other sites…

Warning: As I have already warned about the YAML file indenting, Keep in mind that WHITESPACES is used as an indent in YAML files. And especially in VVV prefers 2 spaces as indent.

Don’t forget to reprovision. Always reprovision using vagrant reload –provision. The changes in config.yml file only affect after the reprovision is done.

How to Add Multisite?

To add multisite in VVV, the process is the same as adding the single site. Only an extra parameter is added.

sites:

  .... other sites...

  multisite:
    repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template
    hosts:
      - multisite.test
    custom:
      wp_type: subdirectory

  .... other sites...

I hope till here you got all the things sorted. In the next section let me tell you about the directory structure of both machines, i.e. local machine and virtual machine. This simply means where your website files and folder resides.

Where Your Website Files and Folder Reside in VVV?

Okay, VVV and all the things are good, but where are the website files? You may say if the server is in the Virtual Machine then website files must be inside the virtual machine. How to access them or edit them?

Naturally, you will ask the above question, because I assume that most of you people must have worked on desktop servers like MAMP, XAMPP or LAMP at some point. And You know where to find website files (WordPress installation, themes, and plugins) but what about the VVV as it provides isolation from the local machine, So the files are not on the local machine?

In this case, I would say no. a big fat Noooo.

As we know the objective of VVV is that changing anything on our local computer yet VVV allows us to work with local WordPress installation from the Virtual machine.

So, we get two working machines when we start VVV. Once there was our main machine called the Host machine where we work, and another one is a guest machine which is configured by VVV for WordPress installation.

On the local machine i.e. our Host machine we can find all the installed websites at

vagrant-local/www folder

On the Guest machine, the location for the website is

/srv/www

These two folders are in real-time synchronization. In simple words, if you change anything at vagrant-local/www it’ll immediately reflect at /srv/www

There is also a way to customize the location of websites in VVV. But I recommend you to read the official guidelines before you apply it practically.

How to change PHP Version?

It’s the simple perk of VVV that you can change the PHP version for a specific website once at a time. You just need to mention it in the config.yml file.

Let’s say You want to change the PHP version for the website we have just added. I.e. dev.test go ahead and make the below changes in config.yml file

sites:
  dev:
    nginx_upstream: php74

utilities:
  core:
    - php74

You’ll find utilities at the bottom of the config.yml file. The supported PHP versions are already mentioned there, you just need to uncomment the version you want to install.

Once you are done with changes, don’t forget to reprovision using vagrant reload –provision.

Where is the Database Manager?

The other question you may come across is that Where is the database manager?

Luckily VVV provides the PHPMyAdmin (our favorite) tool to manage databases. It is default installed with the first provision. You find it from the http://vvv.test (the dashboard) or by simply going to the http://vvv.test/database-admin/.

Note: the default database username and password are wp and wp respectively.

Updating VVV (Varying Vagrant Vagrants)

VVV is built in a way that the first-time setup for VVV may work for the years, but it’s a good practice to stay updated with future bug fixes and feature improvements. It’s not rocket science here to update the VVV, but I have to mention these steps to make sure that you don’t lose the changes you made while working with VVV.

Steps to Update VVV:

1. If vagrant is running, first of all, stop it by the command vagrant halt
2. Update Vagrant and Virtual box separately. You can check for the latest version of both software on their respective websites. Download the latest version and install it.
3. Run vagrant box update command. It’ll update the vagrant box if there is anything updated.
4. Once you run the vagrant box update, you have to destroy the existing machine by vagrant destroy command. Unless you destroy the machine, the update won’t take effect
5. Run command git pull to update the VVV itself. (it’ll only work if you have installed the vagrant using git method)
   1. If you have not used the git method, you have to download the latest VVV zip from the GIt repository. And extract it to the current directory. Make sure you don’t override the www folder, otherwise the changes may get overwritten.
6. Congratulations! Your VVV is up to date.
7. Last but not the least run vagrant up –provision and wait for provision to end.

Preserve Data Perfectly: VVV is developed while keeping in the mind the development environment. If you destroy the vagrant box or even uninstall vagrant or VirtualBox itself. There should be no loss in the data. But for the sake of data, you should avoid storing the data on virtual machines.

Always take backups of databases in Website files. By default, VVV provides functionality to take database backups for you should not rely on them.

If you here mean you have gone through the truckload of documentation on VVV set up, but believe me, it is worth it, in the long run. It is always a good practice for developers to embrace automation tools. Automation tools just not make the process easier but also, they help us to save a lot of time, which we can use in wise work.

Conclusion

When I installed the VVV for the first time, it took almost a day studying the documentation and installing the things currently. But now whenever I need to work on WordPress, I just need to run a simple command vagrant up and the things are ready to work. VVV is the god level tool for WordPress developers, just embrace it, folks.

I have tried to mention all the basic things in the article, but if you still have questions, I would be happy to guide you in the comment section. Meanwhile, you can read my article on WordPress security as well.