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.
Prerequisites
On the user’s local machine:
- VIP-CLI is installed and is updated to the most current version.
- Docker Desktop is installed.
git
is installed.- For macOS users: Xcode Command Line Tools are installed.
Xcode can be installed by running the command:xcode-select --install
. - For Debian-Based Linux distributions:
docker-compose
may need to be installed viasudo apt-get install docker-compose
. - Only
docker-compose
versions 1.X.X are compatible with VIP Local Development Environment. Specific versions ofdocker-compose
can be installed via command line for Linux users, anddocker-compose
versions 2.X can be disabled in the Docker Desktop “Preferences” panel for Windows and macOS users. - Simultaneously running more than one type of local development environment application can lead to unexpected results. Any other local development environment applications (e.g., Laravel or VVV) on a local machine should be shut down before creating and running VIP Local Development Environments.
A new VIP Local Development Environment is created with the VIP-CLI command:
vip dev-env create [options]
vip dev-env create -h
Caution
VIP-CLI commands, including dev-env
, should never be run with sudo
.
If sudo
is used, destroy
the affected VIP Local Development Environment. Create a new environment without the sudo
command in order for the local environment to work as expected.
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.