Create a VIP Local Development Environment

Create one or more local development environments, each with their own unique configurations, using the VIP Local Development Environment built into VIP-CLI.

Create a basic local environment

A VIP Local Development Environment has several configurable options that can be selected in a setup wizard during the creation process. New users are recommended to get started with the VIP Local Development Environment by following the instructions below to create a local environment with basic settings. Once a user gains familiarity with the dev-env commands and options, settings can later be updated with new values to make more advanced customizations to a local environment.

Multiple local environments can be created with the VIP Local Development Environment, and each one must have a unique --slug value so that a user can accurately run dev-env commands against the intended target environment.

1. In the local machine’s command line, create a new local environment and assign the --slug value example-site by running the command:

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

2. Select settings for the local environment in the setup wizard:
   • WordPress site title · Select the Enter or Return key to accept the default value “VIP Dev”, or type a new custom value and then select the Enter or Return key to proceed to the next option.
   • Multisite (y/N) · Select the Enter or Return key to accept the default value “False”, or type “y” to create a WordPress multisite local environment.
   • PHP version to use · Select the Enter or Return key to accept the default version.
   • WordPress – Which version would you like · Select the Enter or Return key to accept the highlighted default version.
   • How would you like to source vip-go-mu-plugins · Select the Enter or Return key to accept the default value “Demo”. This will automatically load the production branch of VIP MU plugins on the created local environment.
   • How would you like to source site-code · Use the Down Arrow to highlight the “Demo” option and select the Enter or Return key to proceed to the next option.
   • Enable Elasticsearch (needed by Enterprise Search)? (y/N) · Select the Enter or Return key to accept the default value “false”.
   • Enable phpMyAdmin (y/N) · Select the Enter or Return key to accept the default value “false”.
   • Enable XDebug (y/N) · Select the Enter or Return key to accept the default value “false”.

If the creation process is successful, details about the newly created environment will be output in the command line followed by a confirmation message ✓ environment created.

3. The environment is created but not yet running. Run the start command to update the environment’s STATUS from DOWN to UP and bring it into a running state.

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

If successful, details about the running created environment output in the command line will display STATUS as UP.

4. Confirm that the environment is running as expected by copying the first listed NGINX URLS value and loading it in a browser window: http://example-site.vipdev.lndo.site/
   A successfully running environment will have a core WordPress theme enabled and display a default “Hello World!” post on the homepage.
5. Access the WordPress log in portal for the running environment by copying the LOGIN URL value and loading it in a browser window: http://example-site.vipdev.lndo.site/wp-admin/ 
6. Retrieve the default login credentials for a VIP Local Development Environment with the info command:

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

7. Access the WordPress Admin dashboard of the running environment by entering the default log in credentials then select the “Log in” button.

The newly created and running local environment will only list the “Hello Dolly” plugin on the Plugins screen, and core WordPress themes on the Themes screen. Because “image” was selected as the value for “source site-code” in the creation wizard, the environment is currently loading a remote image of the vip-go-skeleton code repository.

After a local environment is successfully running, it can be updated to load a local copy of the VIP application’s code.

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

A VIP Local Development Environment can be created with some 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

Command reference

Common commands and options for creating and interacting with a VIP Local Development Environment.

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

vip dev-env -h

create

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

vip dev-env create [options]

start

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>

stop

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>

update

Option values can be updated with the update command:

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

destroy

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>

--slug

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

When multiple local environments exist, each environment must be created with a unique --slug value:

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

If a local environment is created with@<app-alias>|<app-id>.<env>—and a custom slug value is not assigned to it—a unique slug value for the environment will be created automatically.

Find an environment’s assigned --slug value by running the command vip dev-env list. The information listed in the command’s output includes the SLUG value that was assigned to an environment’s --slug option when it was created.

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

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

The default demo value will provision a VIP Local Development Environment from the production branch of VIP MU plugins.

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

--app-code

Accepted values:  Local path to an application’s GitHub repository where it has been git cloned to the local machine
Default value: demo

The default demo 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.

--debug

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.