VIP Local Development Environment

VIP-CLI can create and control a local environment that mimics an environment running on the VIP platform on a supported local machine. This environment can be used for local development, quick testing, tutorials, or other activities where a local stack is more convenient than a pre-production WordPress VIP environment.

Architecture

Just like the VIP Platform, the local development environment uses a container-based solution to provide the various services and code needed for an application.

The WordPress VIP local environment provides the following services:

• A web stack (nginx, PHP, WordPress) including a customer repository (for the application code) and VIP’s vip-go-mu-plugins codebase.
• Memcached, an object cache solution
• MySQL / MariaDB, the database needed for WordPress
• Elasticsearch, a dedicated indexing and search solution that is the basis of Enterprise Search

We also supply PHPMyAdmin as a development tool. This is not included in the stack by default, therefore, the --phpmyadmin argument must be included in your chosen $ vip dev-env create command if you wish to use this tool.

Dependencies

The local development environment requires:

• VIP CLI (which requires Node.js and NPM)
• Docker Desktop

These should be supported on Mac (OS/X), Linux, and Windows 10.

Please follow our installation guide to get the dependencies set up and a basic development environment running.

Environment Naming

There is no theoretical limit of how many local environments you can have locally. They only need to have unique names.

In most cases you don’t need to specify the name explicitly. As with other vip commands, the @<site-id>.<environment-name> notation is supported (but not required for dev environments). This will among other things be used to name the environment accordingly.

To give the environment an alias or create a different environment that would otherwise conflict in name you can use the --slug=<name> argument for all dev-env subcommands.

The rest of the examples in this document will rely on default naming without explicitly targeting the environment by name.

Command reference

dev-env

The VIP Local Development Environment is controlled (created, started, stopped, and destroyed) by the VIP-CLI command dev-env.

To list all possible dev-env operations (subcommands) and their descriptions run vip dev-env with the --help parameter:

vip dev-env --help

create

create must be called in order to use the VIP Local Development Environment using one of three methods.

Method 1: Create a local environment using a setup wizard

vip dev-env create

Method 2: Create a local environment using a setup wizard that has some setting values pre-populated with those of an existing VIP Platform environment.

vip @appID.production dev-env create

Method 3: Create a local environment and configure settings by using available arguments.

vip --slug=example-site dev-env create --title="WPVIP Dev" --multisite --phpmyadmin --mu-plugins="~/vipdev/vip-go-mu-plugins" --client-code="~/vipdev/vip-go-skeleton" --wordpress="5.7.2" --jetpack=mu

For some of the environment services, you will have following options to source them:

• image – This will fetch a publicly accessible docker image of that component that was prepared for this purpose. This is easier to set up, since it will be provided without too much of your interaction. However the drawback is that it is more difficult to update the code in such components and changes are not persisted in all cases (you can do that by changing the code directly in the running container).
• local – Providing a full path to the folder containing the given service source code. For example, a local clone of your repository, or a local clone of vip-go-mu-plugins. Changes to that code should be reflected in the running environment(s).

start and stop

To start or stop environment you would execute following command:

vip --slug=example-site dev-env start 
vip --slug=example-site dev-env stop 

info

To get information about status and location of configuration files of all local environments use the following command with either --slug or --all.

vip dev-env info --all

destroy

Stopping merely suspends a stack. Destroy cleans it up.

Environments can be destroyed using this command. The base command will make sure all the underlying docker containers and volumes are stopped and removed. Then the configuration files created by the create subcommand will be removed as well.

vip --slug=example-site dev-env destroy 

Note that locally cloned directories will not be affected.

Alternatively, --soft can be specified as an option, to only remove the docker containers, but leave the configuration intact, so it may be restarted later.

exec

We provide support for a few useful commands to be executed directly on a running local environment. To separate the arguments for the vip process and the command to be executed, use -- (two standard hyphens).

The help command’s example section lists a few useful examples:

vip dev-env exec --help

The most notable: there is an option to run wp cli commands on the environment. For example, the following will list posts on the environment. Note that this runs the WP-CLI inside the environment and supports all CLI operations you are used to, including any custom commands that are enabled in code.

vip --slug=example-site dev-env exec -- wp post list

import

You may import tables or an entire database export via the import command. import has also a support for media files import.

Sql import comes with --search-replace support that can be used to change domains.

vip -slug=example-site dev-env import sql ./wordpress.sql --search-replace="example-site.com,example-site.lndo.site"

Depending on whether you’re importing one subsite, a multisite, or a single site, you will need to run additional search/replace commands and then flush the object cache before you can continue.

For example, after creating a subsite via wp-admin, and then importing all tables for that subsite, these commands should update the tables with the correct URLs. This example is for this website, with tables for subsite 2 beginning with wp_2_.

vip --slug=example-site dev-env exec -- wp search-replace example-subsite.example-site.com example-subsite.example-site.lndo.site --all-tables-with-prefix wp_2_* --dry-run
vip --slug=example-site dev-env exec -- wp search-replace example-subsite.example-site.com example-subsite.example-site.lndo.site --all-tables-with-prefix wp_2_*
vip --slug=example-site dev-env exec -- wp cache flush --url=http://example-subsite.example-site.lndo.site

Argument reference

These command arguments are typically prefaced by a double hyphen (--). Not every argument has meaning for every subcommand.

slug

Specifies the target environment name, helpful when multiple environments are defined.

title

Specifies the site title, which will appear in the site’s UI.

client-code

Specifies the client / customer code directory, typically your working copy of a GitHub repository.

mu-plugins

Specifies the vip-go-mu-plugins code directory, if you’d like to clone the main repository for use in debugging or to contribute to the project. Submodules should be initialized with git submodule update --init.

multisite

Include this with no attribute to indicate the environment is a multisite.

wordpress

Use this to specify the version (e.g. “5.7.2”) of WordPress core to use, or provide a file path to use a local copy.

phpmyadmin

Include this with no attribute to include a PHPMyAdmin instance in the environment stack.

php

Use this to specify a particular version of PHP (e.g. “7.4”)

all

A shorthand to reference all sites, useful with the info subcommand.

soft

Modifies the destroy subcommand to be not fully destructive, leaves the named environment’s configuration in place for later use.

Tips

Accessing WordPress

Newly created environments get a brand new empty database. This can be accessed via the PHPMyAdmin web url supplied by the start subcommand. Each environment has its own stack and PHPMyAdmin instance. PHPMyAdmin can be used to import a database to replace the default.

The super-admin credentials created for a new (empty) environment are vipgo/password.

Changes made to the database should be persisted until the environment is destroyed.

Working with images & media

The local development environment does not have a files service replica, so all images are served locally. If data is imported and URLs search-replaced, these will likely 404 unless the corresponding media is placed in the container filesystem or the attachment URLs are filtered.

The following snippet, placed in a file in client-mu-plugins, can be used to rewrite attachment URLs to point to a production site. It’s a crude method, and there may still be broken images when URLs are given query parameters to resize them. This example works for this website, with a slug of wpvip. You will need to amend it for your environment.

<?php

/**
 * local development image filter
 *
 */
add_filter( 'wp_get_attachment_url', 'localvip_use_production_url' );
function localvip_use_production_url( $url ) {
        return str_replace( 'example-site.lndo.site', 'example-site.com', $url );
}

You can upload images via WordPress functionality, and those should be accessible. The uploads directory is also mapped to your host machine and can be found within a location of the environment.

vip dev-env info

NAME        example-site                                                                           
  LOCATION    /home/wpvip/.local/share/vip/dev-environment/example-site                               
  SERVICES    devtools, nginx, php, database, memcached, phpmyadmin, vip-search, statsd, wordpress 
  NGINX URLS  http://example-site.vipdev.lndo.site/                                                   
  STATUS      DOWN 

ls -al /home/wpvip/.local/share/vip/dev-environment/example-site

total 28
 drwxrwxr-x 5 wpvip wpvip 4096 aug 23 09:01 .
 drwxrwxr-x 7 wpvip wpvip 4096 aug 20 15:55 ..
 drwxrwxr-x 2 wpvip wpvip 4096 aug 23 09:10 config
 -rw-rw-r-- 1 wpvip wpvip 4449 aug 16 09:46 .lando.yml
 drwxr-xr-x 2 wpvip wpvip 4096 jun 18 09:04 log
 drwxr-xr-x 3 wpvip wpvip 4096 aug 16 09:48 uploads

Working on client code

The local development environment allows you to work on custom code (described here as client code, it is equivalent to the VIP Go repository code) locally on your machine, which makes the development feedback loop faster. Another advantage is that you have access to all the development tools you have in your environment. Finally, you have full access to all parts including the database.

For example:

# clone code locally if you don’t have it yet
git clone https://github.com/wpcomvip/my-environment.git ~/site-code

# pass the path to the code to the client-code component or provide the path when asked by the setup wizard. 
vip dev-env create --client-code="~/site-code" 

Stack services

The various services are running in containers, and some may expose ports on your machine. Of course, nginx is on port 80, and the PHPMyAdmin URL will be reported when you run the create command (or in the output from info).

WordPress

The site is available through the URLs shown in the start output.

To log in to the site backend, use these credentials:

Username: vipgo
Password: password

Database

The MySQL (MariaDB) database can be accessed via the PHPMyAdmin web interface, the URL will be listed in the start command output. This tool can be used to import and export the entire database or specific tables.

Logs

PHP error logs are going to be available in Query Monitor in the browser, but raw logs can be tailed from the directory where the site configuration is stored.

Each slug or environment name has a separate subdirectory in ~/.local/share/vip/dev-environment containing a config and log directory and a .lando.yml YAML file.

To tail the PHP logs for the environment named example-site:

tail -f ~/.local/share/vip/dev-environment/example-site/log/debug.log

Object cache

The same object cache used in production is running in the local development environment. You may notice that some database queries are automatically cached and do not show up in Query Monitor. This is normal!

To clear the object cache (add a --url argument as needed, the cache for subsites in a multisite must be flushed individually):

wp cache flush

Enterprise Search

The Elasticsearch service that supports Enterprise Search is running locally as well, so you can test all aspects of search, including indexing.

Known Issues (Beta version)

Lando & Docker Compose

Lando is used to enable these stacks, via an npm package that is part of the VIP-CLI, and Lando orchestrates Docker Compose and Docker. But not every part of Lando or Docker may work well for managing this environment.

During the beta, you may find it necessary to install and use Lando. If so, here are the installation instructions:

Install Lando

Follow the documentation at https://lando.dev/download/ to install, depending on your operating system.

Click and download the latest file from https://github.com/lando/lando/releases – for MacOS, this is the DMG file.

Double click the DMG file to open it, you should see a Finder window with several files.

Double click the PKG file to start the installation.

If Docker is already installed, skip that in the Lando installer.

Lando commands

You may use some Lando commands if Lando is installed in your Terminal path. Lando’s execute command can be run from the LOCATION directory that is reported after the vip dev-env start subcommand, or via the info subcommand.

The config and logs are located in the directory called LOCATION that is output in the create command. 

  NAME             example-site                                                                         
  LOCATION         /Users/vip/.local/share/vip/dev-environment/example-site                                 
  SERVICES         devtools, nginx, php, database, memcached, phpmyadmin, vip-search, statsd, wordpress 
  NGINX URLS       http://example-site.vipdev.lndo.site/                                                      
                   http://*.example-site.vipdev.lndo.site/                                                    
  PHPMYADMIN URLS  http://localhost:61867    

So you can run a WP CLI command and a few other things there via the lando command:

cd ~/.local/share/vip/dev-environment/example-site
lando --help
lando wp option get siteurl

Docker commands can be used to clean up and prune things, but may not work for interacting with the container stacks.

The Docker Desktop dashboard buttons to stop and restart each stack will not work, and will throw errors.