Table of contents

What is VVV?Installing VVVGetting started with VVVDeveloper toolsNext stepsAdditional resources

Get the industry’s fastest hosting for WordPress◦ 99.999% uptime
◦ Comprehensive security
◦ 24/7 support

WordPress Guide → Local → Vagrant and VVV

Running WordPress locally with Vagrant and VVV

Today we’re going to look at one of the first tools that I dug into as I learned more about server configuration and working with WordPress Core code, Varying Vagrant Vagrants. That’s a bit of a mouthful, so it’s most often abbreviated to VVV, which is what I’ll use.

What is VVV?

VVV was started as an internal project at a WordPress agency called 10up. As it grew in popularity it was moved out of a company-specific project and an official organization was set up to govern the project. Since then a vibrant community of developers has continued to maintain and use VVV in their development environment.

VVV is based on Vagrant, which is open source software used to build virtual machines. You combine it with tools like VirtualBox, Hyper-V, Docker, or other supported platforms to run virtual computers on your machine.

Most people use VirtualBox to interact with Vagrant, and VVV is set up to expect VirtualBox by default.

Installing VVV

Let’s start by getting the default tools set up so that we can install VVV. First, head to the Vagrant downloads page and download the version that is meant for your computer.

On macOS, the download contains a package file that needs to be double-clicked to install. You’ll be asked for your password and then the installation will be complete.

For VirtualBox, head to the download page and download the version that is meant for your computer. For macOS, you’ll be looking at the same basic process. Double-click the package file to run it then enter your password when prompted and let the installer run.

Note: You may need to reboot your machine once you’ve installed VirtualBox to get all the network connections working. If it doesn’t work at first, turn it off and on again before you go further down the path of troubleshooting.

Now we’re ready to install VVV. While there are two methods to install VVV, we’re going to stick with the easy method via git.

First, create a directory to store all your VVV sites, I usually use ~/Sites. Then we’ll need to use git to clone the VVV repository with the command below.

git clone -b stable git://github.com/Varying-Vagrant-Vagrants/VVV.git ~/Sites/vagrant-nexcess

This creates a copy of the current stable branch of VVV in a folder called vagrant-nexcess in our current directory. Next, you’ll need to change into the vagrant-nexcess directory by using the cd vagrant-excess command. Once inside this directory use vagrant up to start running VVV.

If you’re on Windows, you’ll need to use a command prompt with administrator privileges to get custom hostnames working with VVV.

It may take a while the first time you install this because it has to download a copy of the virtual machine that is defined in the VVV configuration files, but after the first time, that data is cached so future installs will be much faster.

You may get asked to install some other plugins for Vagrant like the vagrant-goodhosts plugin. You want all this stuff so accept the installs when prompted. You may need to run the vagrant up command again after you’ve installed the plugins, and you may need to enter your administrator password to modify the hosts file so you can have custom domains available in VVV.

All computers have a hosts file, which maps hostnames to IP addresses. When you type in nexcess.net this file is part of the system that will translate that URL into the IP address that your computer is looking for. By adding a domain to your hosts file, you can force that domain to go to wherever you want.

Getting started with VVV for local WordPress work

Now that VVV is installed you can access the default site at the default URL of http://vvv.test.

Now, let’s go over how to add a custom domain and a clean WordPress install to VVV so you can get started with a new project. To start, open the vagrant-nexcess folder in your code editor. Then you’ll need to open config/config.yml to add our new domain. We’re going to create a new site called nexcess and use nexcess.test as our development domain.

Inside config.yml you can already see some extra sites configured. Let’s look at the first one to understand what’s going on.

# latest version of WordPress, can be used for client work and testing

# Check the readme at https://github.com/Varying-Vagrant-Vagrants/custom-site-template

wordpress-one:

    skip_provisioning: false

    description: "A standard WP install, useful for building plugins, testing things, etc"

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

    hosts:

      - one.wordpress.test

    custom:

      wpconfig_constants:

        WP_DEBUG: true

        WP_DEBUG_LOG: true

        WP_DISABLE_FATAL_ERROR_HANDLER: true # To disable in WP 5.2 the FER mode

First, we name the profile wordpress-one and under that, we set our configurations for this site. We can see that we give the site a description, and use the repo parameter to define where we want to clone the site from. Then we set up the host and define some of the constants that will be present in our standard wp-config.php file for debugging. You could even go to one.wordpress.test and see the site that is configured by default.

Modify the code above to match the changes made below. Note, we changed the name of the profile, the description, and host, and we added a plugin we want installed by default, Query Monitor.

nexcess-test:

    skip_provisioning: false

    description: "A standard WP install, useful for building plugins, testing things, etc"

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

    custom:

      # locale: it_IT

      delete_default_plugins: true

      install_plugins:

        - query-monitor

    hosts:

      - nexcess.test

Once you’ve made the changes above, head over to your terminal and run vagrant up –provision to tell Vagrant to run through its setup scripts again and provision the virtual server with our new settings. Then you can find your new site at nexcess.test.

A word of caution, the configuration file is written in YAML and YAML is sensitive to indentation. You should be using 2 spaces to indent things or it will all go up in flames.🔥

Developer tools

Because VVV is running a virtual server you’ll need to start by using ssh to connect to this virtual server. You can do this with the vagrant ssh command that is provided as part of your package.

Next, you’ll need to use terminal to get to your web directory, which is found at /srv/www. From here you can move to the directory that has your tests and run them like normal.

Another thing that I regularly need to do is connect directly to the database of the site I’m working on. If you’re using Sequel Pro, VVV comes bundled with a configuration file you can use to connect automatically. You can find this inside the cloned package at database/sequelpro.spf. Import it into Sequel Pro and you’ll get a connection.

The VVV database documentation also provides several other connection methods to suit your needs.

I also regularly need to check on the emails that are being sent in my WordPress installs. For this VVV provides the MailHog package. MailHog will capture all your emails and provides a nice web UI to view them. You can access Mailhog via the VVV dashboard which is found at vvv.test. You’ll also find access to phpMyAdmin and many other tools on the dashboard, so take note of it.

Troubleshooting common VVV issues

VVV not starting or stuck at boot

This is a common issue where VVV doesn’t boot up properly or is stuck on the loading screen. Here’s how to troubleshoot it:

Check VirtualBox version: Ensure that you have the latest version of VirtualBox installed. VVV works best with specific versions, so check compatibility with your current version.
VM resource allocation: Sometimes the virtual machine (VM) might be lacking sufficient resources (like RAM or CPU). You can adjust the settings in VirtualBox to allocate more resources by opening VirtualBox, selecting your VVV machine, going to Settings > System > Motherboard, and increasing the amount of memory.
Rebuild Vagrant box: Run the command vagrant destroy followed by vagrant up to rebuild the VVV VM. This will reset the environment but may take time.

“vagrant up” command fails

When running vagrant up, you may encounter errors that prevent VVV from starting the VM. Try:

Checking the logs: Check the terminal output for specific errors. It might be something like missing dependencies or incorrect configurations.
Checking Vagrant version compatibility: Ensure you’re using a version of Vagrant that is compatible with VVV. Generally, VVV works best with the latest stable version of Vagrant.
Reinitializing Vagrant: Run the following:
- vagrant destroy
- vagrant up
Checking VirtualBox: Make sure VirtualBox is running the latest version and the VirtualBox Extension Pack is installed.

Slow performance

Sometimes, VVV may perform slowly, affecting development. You’ll need to:

Increase resource allocation: In VirtualBox, you can assign more RAM and CPU cores to the VM. Try increasing it to 4GB of RAM and 2 CPU cores if possible.
Disable shared folders: Shared folders between the host and VM can be a performance bottleneck. You can disable or limit the shared folder usage by modifying the Vagrantfile.
Use NFS for shared folders: On some systems, NFS (Network File System) can improve performance when sharing files between the host and VM. You can modify the Vagrantfile to enable NFS.

WordPress sites not loading

Sometimes, after setting up a site in VVV, WordPress might not load, showing a white screen or error messages. You might need to:

Check database connection: Make sure that the database credentials in the wp-config.php file are correct. The default VVV database credentials are:
- define( 'DB_NAME', 'wordpress' );
- define( 'DB_USER', 'vagrant' );
- define( 'DB_PASSWORD', 'vagrant' );
- define( 'DB_HOST', 'localhost' );
Check for plugin/theme conflicts: Disable all plugins and themes via the database (using phpMyAdmin or MySQL command line) to see if a plugin or theme is causing the issue.
Increase PHP limits: Increase the PHP memory limit by editing the php.ini file located inside the VVV VM. In the VM, find the php.ini file (typically located in /etc/php/*/apache2/php.ini) and change: memory_limit = 256M
Check error logs: Look at the wp-content/debug.log file (if debugging is enabled) or Apache/PHP error logs to identify the issue.

Unable to access sites via browser

If you cannot access your WordPress sites hosted on VVV through your browser, it could be a network-related issue, so:

Check local hosts file: Ensure that your hosts file (located at /etc/hosts on Unix-like systems or C:\Windows\System32\drivers\etc\hosts on Windows) includes an entry for the WordPress site’s URL.
- define( ‘DB_NAME’, ‘wordpress’ );
- define( ‘DB_USER’, ‘vagrant’ );
- define( ‘DB_PASSWORD’, ‘vagrant’ );
- define( ‘DB_HOST’, ‘localhost’ );
Check firewall/antivirus: Sometimes, firewalls or antivirus programs block certain ports or connections. Ensure that the required ports are open (usually 80 and 443 for HTTP and HTTPS).
Check VVV network settings: If using VVV’s default settings, ensure that config.yml has the correct IP address for the Vagrant machine (typically 192.168.50.4).

PHP errors or compatibility issues

If you cannot access your WordPress sites hosted on VVV through your browser, it could be a network-related issue, so:

Check PHP version: Ensure that you are using the correct version of PHP for your WordPress site. VVV provides several PHP versions.
Enable debugging: Enable WordPress debugging to get more detailed error messages. Add the following lines to your wp-config.php:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
This will log errors to wp-content/debug.log.

Access to services (e.g., MySQL, phpMyAdmin) fails

If you’re unable to access services like MySQL or phpMyAdmin, it could be a misconfiguration. Try:

Checking service status: SSH into your VVV VM and check the status of services like Apache and MySQL with sudo service apache2 status and sudo service mysql status. Restart them if necessary with sudo service apache2 restart and sudo service mysql restart.
Checking phpMyAdmin access: By default, phpMyAdmin should be accessible at http://vvv.test/phpmyadmin/. If not, check that the phpMyAdmin configuration is correct and that it’s running.

Network or DNS issues

VVV often uses local DNS for the sites (e.g., my-site.test), but if DNS resolution fails, the sites may not be accessible. You’ll need to clear the DNS cache on your local machine.

On macOS, use:

sudo killall -HUP mDNSResponder

On Windows, use:

ipconfig /flushdns

Also, check DNS Resolution in VVV. SSH into VVV and use ping to verify DNS resolution:

ping my-site.test

Next steps for VVV and WordPress local

If you’re looking for a developer-focused environment to do your work, then VVV is a great choice. It installs everything you need without touching any of the internals of your computer. Coming from MAMP, which does touch stuff on your computer, VVV was a breath of fresh air because I knew that if something went drastically wrong, it would be contained in my Vagrant container and not mess with anything else on my machine.

The biggest problem with it is that if something goes wrong, you need to have a good understanding of how server provisioning works to work through and fix problems. The developers are very helpful, but it still takes some understanding to work through problems.

Depending on your projects the tailored to WordPress nature of VVV can also be an issue. If you work with both Laravel and WordPress you may end up fighting with the WordPress specifics. You certainly can run both Laravel and WordPress projects with VVV but you’re a bit more out on your own if you go that route.

If you haven’t tried VVV before, take it for a spin. And if you’re not hosting your WordPress website with Liquid Web yet, check out all our options today. Whether you need a VPS or a dedicated server—managed or unmanaged—our expert team has you covered.