Create a VIP Local Development Environment

The VIP Local Development Environment is intended for local development, debugging, and minor testing. The VIP Local Development Environment can be set up to include a copy of a VIP Platform application environment’s code and database. When created with a local clone of a customer GitHub repository and the VIP Go MU Plugins, the VIP Local Development Environment permits branch changes, code updates, code testing, and pushing of those updates to GitHub.

A new VIP Local Development Environment is created with the VIP-CLI command:

vip dev-env create [options]

A complete list of subcommands and options for the vip dev-env create command—and examples for how to use them—can be reviewed in the command line help menu:

vip dev-env create -h

Command options

The following command options are the most commonly used for creating a new VIP Local Development Environment. If a value is not explicitly set for an option, its default value will be set instead.

--slug

Accepted values: String
Default value: “vip-local”

When multiple local environments are created, each environment must have a unique --slug value assigned to it.

vip dev-env create --slug=<custom-name>

To ensure that vip dev-env commands target an intended local environment after it is created, pass the environment’s assigned slug value in those commands. For example, to retrieve information about a local environment with the assigned slug example-site:

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

--title

Accepted values: String
Default value: “VIP Dev”

--multisite

Accepted values: y or false
Default value: y

This value should be set based on the configuration of an application’s VIP Platform environment. Set this value to false to create a WordPress single site environment, and y to create a WordPress multisite environment.

--php

Accepted values: 7.4, 8.0, or 8.1
Default value: 7.4

This value can be automatically set to the same PHP version running on an application’s VIP Platform environment by creating a local environment based on a VIP Platform environment’s settings.

--mu-plugins

Accepted values: Local path to where vip-go-mu-plugins has been checked out to the local machine
Default value: image

The default image value will provision a VIP Local Development Environment from the master branch of vip-go-mu-plugins.

For a local path to be assigned, a git clone of vip-go-mu-plugins must exist on the local machine. Submodules in the cloned vip-go-mu-plugins must be initialized with git submodule update --init.

--client-code

Accepted values:  Local path to where an application’s GitHub repository has been checked out to the local machine
Default value: image

The default image value will provision a VIP Local Development Environment with the vip-go-skeleton.

For a local path to be assigned, a git clone of the application’s GitHub repository must exist on the local machine.
The URL for an application’s GitHub repository can be found in the main dashboard of the VIP Dashboard.

Setup wizard

The command line setup wizard will prompt a user to confirm settings for any option values that are not passed in the vip dev-env create command.

For example, by including --multisite=y in the vip dev-env create command, the setup wizard will skip the Multisite (y/N) prompt but include all other prompts (e.g., “WordPress site title“, “WordPress version“):

vip dev-env create --multisite=y --slug=example-site

An example command that sets multiple option values:

vip dev-env create --title="WPVIP Dev" --multisite=y --php=8.0 --mu-plugins="~/vipdev/vip-go-mu-plugins" --client-code="~/vipdev/vip-go-skeleton" --slug=example-site

Creating a local environment based on a VIP Platform environment’s settings

A VIP Local Development Environment can be created with option values that pre-populate based on an existing VIP Platform environment. To pre-populate values, reference the VIP application’s environment with @<app-alias>|<app-id>.<env> when running the vip dev-env create command.

For example, to create a new environment with the slug example-site that pre-populates settings based on the develop environment for an application with the alias mytestsite:

vip@mytestsite.develop dev-env create --slug=example-site

Updating option values after they are set

Option values can be updated with the update command:

vip dev-env update --<option>=<new_value>

Starting an environment

After it is successfully created, a local environment is brought into an UP state with the start command:

vip dev-env start --slug=<custom-name>

Stopping an environment

The stop command will preserve an environment but transition it from an UP state to a DOWN state:

vip dev-env stop --slug=<custom-name>

Destroying an environment

When no longer needed, an environment can be completely destroyed from the local machine with the command:

vip dev-env destroy --slug=<custom-name>

This will remove all underlying docker containers and volumes, as well as the configuration files for that specific environment.

Running destroy with the --soft option will remove all underlying docker containers and volumes, but will preserve the environment’s configuration files for later use.

vip dev-env destroy --soft --slug=<custom-name>

Debug option

The --debug option can be passed with dev-env subcommands to add verbose debugging details to command output. Passing the --debug option with the argument @automattic/vip:bin:dev-environment will filter out Docker details and return only debugging output for the VIP-CLI command.

vip dev-env start --slug=<custom-name> --debug=@automattic/vip:bin:dev-environment

Additional debugging and troubleshooting options for the VIP Local Development Environment are available.