chronic overengineering

DISCLAIMER: I wouldn't recommend for anything but maybe small and simple sites residing in US/Canada. To Europe their support is slow to respond, site latency is bad and the stack is dreadful compared to Cloudways.

Varying Vagrant Vagrants 2 is an opinionated local development setup for WordPress core, plugins and themes. It's built upon Ubuntu Linux Vagrant box (running on eg. VirtualBox virtual machine) and is helpful when setting up local development environment for WordPress/PHP that more modern languages and web frameworks have had "built-in" for ages.

The VVV setup is somewhat complex and documentation seems to be all over the place. If you're facing any problems, refer to VVV documentation on adding new domain (plus documentation on the configuration files, repo issues etc).

Duplicating VVV WordPress stable site

After having VVV2 set up and running, configured and running, you have the latest stable WP running at We'll start by duplicating this site into a new site called mysite that's accessible locally at and stored at www/mysite-dev.

$ cp -r www/wordpress-default www/mysite-dev

Remove that's executed to bootstrap the WordPress installation during provisioning, as we are going to manually configure the already provisioned site further:

$ rm www/mysite-dev/provision/

Modify server configuration file www/mysite-dev/provision/vvv-nginx.conf:

server {
    listen       80;
    listen       443 ssl;
    server_name;  # <- Enter your domain here
    root         {vvv_path_to_site}/public_html;

    error_log    {vvv_path_to_site}/log/error.log;
    access_log   {vvv_path_to_site}/log/access.log;

    set          $upstream {upstream};

    include      /etc/nginx/nginx-wp-common.conf;

Modify www/sitename/provision/vvv-hosts

# WP Stable

Create (or modify) vvv-custom.yml to contain:


Copy WP installation from

Now when you run your Vagrant machine with $ vagrant up, you should be accessing a bare bones WordPress stable installation at reporting problems with it's database connection. Next we're going to copy and configure the site and database from Pressable.

A copy of the www-directory and database can be downloaded easily from backup system (VaultPress or AWS S3 backup provided by Pressable). You can also copy the files via SFTP and get the SQL-dump via PHPMyAdmin that's accessed via control panel. WordPress Duplicator plugin does not work straight out of the box because of restrictions on filesystem.

Then copy and replace all files from your server www dir into www/mysite-dev/public_html/.

Modify wp-config.php

Pressable handles the database connection and some other settings outside the wp-config.php, so you need to set that manually.

Open www/mysite-dev/public_html/wp-config.php and configure/add following lines:

define('DB_NAME', 'mysite');
define('DB_USER', 'root');
define('DB_PASSWORD', 'root');
define('DB_HOST', 'localhost');
define('DB_CHARSET', 'utf8');
define('DB_COLLATE', '');

define('WP_HOME', 'http://' . $_SERVER['SERVER_NAME']);
define('WP_SITEURL', WP_HOME . '/');

Additionally enable debugging on the site by adding lines:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

Import database

During provisioning VVV imports any SQL dump file in database/backups/ dir mapped by filename to the specific database. First you need to make sure the custom database with permissions exists by editing database/init-custom.sql to contain:

GRANT ALL PRIVILEGES ON `mysite`.* TO 'root'@'localhost' IDENTIFIED BY 'root';

Then copy your SQL dump file into database/backups/mysite.sql. In case you have the database dump as separate files, just combine them into one with $ cat *.sql > mysite.sql.

Now with Vagrant running, run the provisioning vagrant provision to set up the database, or alternatively boot it up with vagrant up --provision.

Replace database strings

As WordPress uses absolute urls for posts in the database, you need to convert each url to pointing to your earlier domain to the local development environment. Eg. site was accessed at and needs to be changed to

VVV comes with WP-CLI installed that allows easy search and replace for the database. Connect view ssh to your machine, navigate to site www directory and replace all string in database:

vagrant ssh
cd /vagrant/www/mysite/public_html

# Dry run first to check what would be replaced
wp search-replace ' '' --dry-run

# After checking validating dry run output, run
wp search-replace ' ''

Alternatively a tool such as Search Replace DB can be used for doing replacements.


Now (if you're lucky) the site should be accessible at on your local machine.

Accessing it externally requires forwarding ports from guest VM to host in Vagrantfile and opening passage through your networking devices to your computer (or using eg Ngrok for reverse tcp tunneling from host/guest). Additionally guest VM Nginx conf might need to be set to listen all interfaces and a new MySQL user should be created that's accessible from all hosts to connect straight to MySQL from sql client residing elsewhere than the guest machine.

It's also probably good idea to upgrade the VM specs used by Vagrant if doing some heavy lifting with the installation. Eg add the following lines to Vagrantfile:

defaults['memory'] = 8192
defaults['cores'] = 4

Updating the site with new changes

Drop the database on local Vagrant site. With VVV up and running, access (user root, pass root). Select the database from left side menu, select Operations tab from top navbar. Hit "Drop the database (DROP)".

Download database from backup site or get the SQL dump as explained earlier on the tutorial and replace the earlier mysite.sql. Replace wp-content/ directory with updated files.

Run provisioning again with vagrant provision and after that replace database strings and you're good to go.

Tagged:  wordpress  dev  vagrant  tutorial