⚠️ 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.
Running multiple local environments with different stacks might lead to unexpected results. For example, if you use
Laravel Valet you will need to first stop that service with
valet stop to be able to run our VIP Local Environment.
The VIP local development environment can be used to perform local development, debugging, or minor testing.
Creating a local environment with clones of a customer repository and the VIP Go MU Plugins repository permits easy local development; you can change branches, make changes, test, and then push those changes to GitHub.
A detailed reference guide is available.
Set Up Necessary Dependencies
To create and use local VIP environments, you must first install the below required software:
If you’re working on a Mac, at some point you may be prompted to install the xcode command line tools. This is expected and can also be manually installed with
Installing Node Version Manager to switch between versions of node and npm is recommended:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
Note: Do not use sudo!
Choose node version 14 and the latest npm
nvm install 14 && nvm use 14
The VIP-CLI is used to create (or define) an environment via the
vip dev-env command. The
create subcommand can take a list of arguments, or prompt the user for their choices. When you want to use that same environment you just created, the
start subcommand will bring it to an up and running state.
vip dev-env command has multiple other subcommands, available with the
Using Application ID
vip @345 dev-env
If you’d prefer not to use an application ID, you can leave it out on the below commands and instead, pass in the
--slug parameter with the desired name:
vip --slug=example-site dev-env
Method A: Basic Prompt-Based Creation
This creates an environment based on some attributes of your production environment.
Note: The below prompts provide an option to source vip-go-mu-plugins and a customer repository from a directory please ensure that the code directories are already be in place on your local filesystem. If they are not, use
git clone to create them, and then if they contain submodules or need to be built, use the usual build commands before starting the site the first time.
345 with your application ID:
vip @345 dev-env create
2) Fill Prompt-Based Inputs
The command will prompt for any additional choices, and give output like the following:
This is a wizard to help you set up your local dev environment. Sensible default values were pre-selected for convenience. You can also choose to create multiple different environments with different settings using the --slug option. ✔ WordPress site title · VIP Dev ✔ Multisite (y/N) · true ✔ How would you like to source WordPress · image ✔ Which version would you like · 5.8 ✔ How would you like to source vip-go-mu-plugins · image ✔ How would you like to source site-code · local ✔ What is a path to your local site-code · ~/vipdev/vip-go-skeleton NAME 345 LOCATION /Users/vip/.local/share/vip/dev-environment/345 SERVICES devtools, nginx, php, database, memcached, phpmyadmin, vip-search, statsd, wordpress, mu-plugins, client-code NGINX URLS http://345.vipdev.lndo.site/ http://*.345.vipdev.lndo.site/ STATUS DOWN ✓ environment created. To start it please run: vip @345 dev-environment start
Method B: Advanced Argument-Based Creation
If you rather specify inputs, you could manually set up by
1) Set Up a Working Directory
Open a Terminal window and create a working directory. In the example below, we’ll use
cd ~ mkdir vipdev cd vipdev
2) Create Local Clones
Git clone will clone the public GitHub repositories locally so that you can work with them. The submodules command will bring in other repositories that are loaded using git submodules. After the clones are set up, they will appear as subdirectories.
git clone https://github.com/Automattic/vip-go-mu-plugins.git git clone https://github.com/Automattic/vip-go-skeleton.git cd vip-go-mu-plugins git submodule update --init cd ~/vipdev
You may wish to review Understanding your VIP codebase.
This command launches the wizard, but the environment slug, mu-plugins and client code source are specified in the command line (earlier, we cloned the two repositories
vip @345 dev-env create --title="WPVIP Dev" --multisite --mu-plugins="~/vipdev/vip-go-mu-plugins" --client-code="~/vipdev/vip-go-skeleton" --wordpress="5.8"
If you leave out any of the arguments, you’ll be prompted for that info. Feel free to substitute your own client-code instead of using the VIP “skeleton” repository in the
Starting the Environment
vip @345 dev-env start
This is the output as it brings up the stacks in Docker Compose:
Creating network "vipdev345_default" with the default driver [ many messages ... ] Waiting until vip-search service is ready... Scanning to determine which services are ready... Please standby... Checking for database connectivity... ERROR 1045 (28000): Access denied for user 'wordpress'@'172.23.0.10' (using password: YES) No WordPress database exists, provisioning... Checking for WordPress installation... Error: Site '345.vipdev.lndo.site/' not found. Verify DOMAIN_CURRENT_SITE matches an existing site or use `--url=<url>` to override. No installation found, installing WordPress... Created single site database tables. Set up multisite database tables. Success: Network installed. Don't forget to set up rewrite rules (and a .htaccess file, if using Apache). Deleting index for posts... Success: Index deleted Adding post mapping... Processed 2/2. Last Object ID: 1 Number of posts indexed: 2 Total time elapsed: 2.704 Success: Done! Success: Added 'view_query_monitor' capability for vipgo (1). NAME vipdev345 LOCATION /Users/vip/.local/share/vip/dev-environment/345 SERVICES devtools, nginx, php, database, memcached, phpmyadmin, vip-search, statsd, wordpress, mu-plugins NGINX URLS http://345.vipdev.lndo.site/ http://*.345.vipdev.lndo.site/ PHPMYADMIN URLS http://localhost:65010
The Docker Desktop dashboard should show two docker-compose stacks after this completes.
The environment is now ready to use and you may open the site in your browser (e.g. http://345.vipdev.lndo.site/). While your local development environment site is running, you can test code changes instantly!
After a reboot, if you find the environment is “down”, use the
start command to restart it.
To access the backend, use the below credentials after appending
/wp-admin to your local URL (e.g. http://345.vipdev.lndo.site/wp-admin):
When you’re completely done, the destroy command will take care of removing the stacks:
vip @345 dev-env destroy