Skip to content

Backgrounds

How-to Guides

Technical References

VIP Local Development Environment

⚠️ This feature is in beta

This documentation is subject to change. Features described here may not be available, may not be fully functional, or may change without notice, prior to general availability.

The VIP-CLI command now contains the ability to run an environment that mimics the environment run on the VIP platform, right on supported local machines. 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.

VIP-CLI Command

The local development environment can be controlled (created, started, stopped, and destroyed) by a VIP-CLI command dev-env.

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.

Hat tip: Lando

The VIP local development environment uses Lando under-the-hood to simplify orchestration. Looking for a free, open source, Docker-based tool that simplifies your local development experience? Check them out!

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

As with other terminal and CLI commands, you may use the --help parameter to list all possible dev-env operations (subcommands) and their descriptions.

$ vip dev-env --help

Here are the subcommands you will use most often:

Create

The first step to use a local environment is to configure it by calling the create command.

$ vip dev-env create
$ vip @myapp.production dev-env create
$ vip dev-env create --slug=wpvip --title="WPVIP Dev" --multisite --mu-plugins="~/vipdev/vip-go-mu-plugins" --client-code="~/vipdev/vip-go-skeleton" --php=7.4 --wordpress="5.7.2" --jetpack=mu

This command will start a setup wizard to guide you through the configuration. When using the @ notation the command will try to fetch information about the real environment and set some options in the wizard accordingly.

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 dev-env start --slug=wpvip
$ vip dev-env stop --slug=wpvip

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 are stopped and removed. Then the configuration files created by the create subcommand will be removed as well.

$ vip dev-env destroy --slug=test

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 dev-env exec --slug=wpvip -- wp post list

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.

php

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

jetpack

Specifies a Jetpack code directory. Set this to mu to use the latest version of Jetpack in the vip-go-mu-plugins repository.

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 data

You may import tables or an entire database export via the PHPMyAdmin import tab.

Select the database “wordpress” and then click import.

If you have a SQL file, compress it into a GZIP archive (e.g. with gzip dbexport.sql), then click Choose File and select the zipped SQL file and import. If your file is very large, you may need to split it and import in steps. If so, do this carefully, with a code editor such as vim that will not alter the contents.

Depending on whether you’re importing one subsite, a multisite, or a single site, you will need to run 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 dev-env exec --slug=wpvip -- wp search-replace docs.wpvip.com docs.wpvip.vipdev.lndo.site --all-tables-with-prefix wp_2_* --dry-run
$ vip dev-env exec --slug=wpvip -- wp search-replace docs.wpvip.com docs.wpvip.vipdev.lndo.site --all-tables-with-prefix wp_2_*
$ vip dev-env exec --slug=wpvip -- wp cache flush --url=http://docs.wpvip.vipdev.lndo.site/

You may also need to visit the site admin dashboard for the subsite, and change https to http in the URLs, and then flush the cache again.

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( 'wpvip.vipdev.lndo.site', 'wpvip.com', $url );
}

You can upload images via WordPress functionality, and those should be accessible. (Note: uploads may not work, and is a known issue in the beta)

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 search:

$ tail -f ~/.local/share/vip/dev-environment/search/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
Success: The cache was flushed.

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)

Docker network errors

We have noticed that sometimes the underlying docker-compose state gets corrupted. This may be related to unexpected termination of docker processes.

To solve this issue, a rebuild of the containers/network might be needed. To do so, use soft destroy and then start the environment again:

# soft destroy will remove all running containers and network connected to given environment without removing the configuration files
$ vip dev-env destroy --soft

# start after the cleanup done by destroy will spin up fresh containers where applicable 
$ vip dev-env start

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             vipdevsearch                                                                         
 LOCATION         /Users/vip/.local/share/vip/dev-environment/search                                 
 SERVICES         devtools, nginx, php, database, memcached, phpmyadmin, vip-search, statsd, wordpress 
 NGINX URLS       http://search.vipdev.lndo.site/                                                      
                  http://*.search.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/search
$ 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.

Last updated: June 28, 2021