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.
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 Windows users: WSL should be set to version 2 for Windows Docker Desktop compatibility. All
vip dev-env
commands should be made from the chosen distribution app’s command line, or by targeting a WSL installation in Microsoft Terminal. Additional considerations for runninggit
commands and making edits to a locally cloned GitHub repository will be required when working across Windows and Linux file systems. - For Debian-Based Linux distributions:
docker-compose
may need to be installed viasudo apt-get install docker-compose
. - Since VIP-CLI version 2.28.0, the VIP Local Development Environment requires
docker-compose
versions 2.X.X.- For Linux users, specific versions of
docker-compose
can be installed via command line. - For Windows and macOS users,
docker-compose
versions 2.X.X can be enabled in the Docker Desktop application:- Navigate to the “Settings” panel by selecting the gear icon in the upper right of the Docker Desktop application.
- Enable the option labeled “Use Docker Compose V2“.
- Select the button labeled “Apply & restart“.
- For Linux users, specific versions of
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.
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. Each one must have a unique --slug
value so that a user can accurately run dev-env
commands against the intended target environment.
- In the local machine’s command line, create a new local environment and assign the
--slug
valueexample-site
by running the command:
vip dev-env create --slug=example-site
- 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 application-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”.
- Enable Mailpit (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.
- The environment is created but not yet running. Run the
start
command to update the environment’sSTATUS
fromDOWN
toUP
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
.
- 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. - 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/ - Retrieve the default login credentials for a VIP Local Development Environment with the
info
command:
vip dev-env info --slug=example-site
- 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 “Demo” was selected as the value for “source-application-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 repository.
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.
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.
--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.
--php
Accepted values: 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: Path to a built copy of VIP MU plugins on the local machine.
Default value: demo
The default demo
value will provision a VIP Local Development Environment from the staging branch of VIP MU plugins.
For a built copy of VIP MU plugins to be assigned, a git clone
of the vip-go-mu-plugins-built repository is recommended.
Last updated: May 24, 2023