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.

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.

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:

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 to how many local environments you can have locally. They only need to have unique names.

As with other VIP-CLI 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" 

For some of the environment services, you will have the 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 the environment you would execute the following command:

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

info

To get information about the status and location of configuration files for existing local environments, use the info subcommand with the @APPID.environment alias, --slug name, or use --all to get an info list of all existing local environments.

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 and volumes, 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

Note

Commands executed this way run inside the containers as opposed to the host machine. Therefore they do not have direct access to the hosts. One implication of this is that paths to local files on the host machine might not work as expected.

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

Note

Behind the scenes, we share the import file provided for SQL import with the container. Place the import file under the home directory of the current user.

After the SQL import, the command will clear the cache and add a super-admin user vipgo/password automatically.

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.

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.

Last updated: January 03, 2022