Use the VIP local development environment
⚠️ 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.
The VIP local development environment can be used to perform local development, local debugging, or minor testing.
Create a local development environment with clones of a customer repository and the VIP Go MU Plugins repository. This permits easy local development; you can even change branches, make changes, test, and then push those changes to GitHub.
A detailed reference guide is available.
Set up necessary software (dependencies)
To create and use local VIP environments, you must first install the required software.
That consists of Node and Node Package Manager, the VIP Go CLI, and then the Docker Desktop software. If you don’t have the git command installed locally, you may need that as well.
If you’re working on a Mac, at some point you may be prompted to install the xcode command line tools. This is normal, go ahead and install those as well. They can also be manually installed with xcode-select --install.
Install Node & NPM
Node.js and npm (node package manager) are required to install and run the VIP-CLI. Node Version Manager (NVM) is recommended for switching between versions. These development tools are also used in many WordPress plugins and themes, including Gutenberg.
Details for NVM are at https://github.com/nvm-sh/nvm#installing-and-updating
A simple install option:
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 14Install the VIP Go CLI
It’s likely VIP-CLI and Node/npm are already installed on your system, but if not, our documentation will help you get the most out of this powerful tool. It is required for the local development environment, and easy to install:
Simple option:
npm install -g @automattic/vipInstall Docker Desktop
The local environment will run in Docker containers.
Docker Desktop installation starts on the Docker website. Follow the steps to download and install.
Docker also has a basic tutorial built in. If you’re not familiar with Docker, it’s a good introduction, but not essential. Create a Docker Hub account if you wish.
Creating and using environments
The VIP-CLI is used to create (or define) an environment, via the vip-dev command. When you need to use that environment, the start subcommand will bring it to an up and running state.
The create subcommand can take a list of arguments, or prompt the user for their choices.
Basic prompt-based creation
This creates an environment based on some attributes of your production environment.
Note that the prompts provide the option to source vip-go-mu-plugins and a customer repository from a directory – if you intend to do this, the code directories should 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.
First, identify the application ID you’d like to use from your VIP dashboard, and then run the following command (replacing 345 with your application ID):
vip @345 dev-env createThe command will prompt for any additional choices, and give output like the following:
$ vip @345 dev-env create
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-demo
✔ PHP version · 7.4
✔ Multisite (y/N) · true
✔ How would you like to source wordpress · image
✔ Which version would you like · 5.7.2
✔ How would you like to source muPlugins · image
✔ How would you like to source jetpack · inherit
✔ How would you like to source clientCode · local
✔ What is a path to your local clientCode · ~/vipdev/vip-demo
NAME 345
LOCATION /Users/vip/.local/share/vip/dev-environment/345
SERVICES devtools, nginx, php, database, memcached, phpmyadmin, vip-search, statsd, wordpress, mu-plugins
STATUS DOWN
✓ environment created.
To start it please run:
vip @345 dev-environment startNow start the development environment:
vip @345 dev-env startThis is the output as it brings up the stacks in Docker Compose:
$ vip @345 dev-env start
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:65010The environment is ready to use.
Open the site in your browser. E.g. http://345.vipdev.lndo.site/
Add /wp-admin/ to the URL to log in. The credentials are:
Username: vipgo
Password: password
Advanced argument-based creation
This command launches the wizard, but the environment slug, mu-plugins and client code source are specified in the command line.
You can substitute your own client-code for the VIP “skeleton” repository here. Leave out any of the arguments and you’ll be prompted for that info. In this example, the two repositories are also being cloned.
$ mkdir ~/vipdev
$ cd ~/vipdev
$ git clone https://github.com/Automattic/vip-go-mu-plugins.git
$ cd vip-go-mu-plugins
$ git submodule update --init
$ cd ~/vipdev
$ git clone https://github.com/Automattic/vip-go-skeleton.git
$ vip dev-env create --slug="wpvip" --title="WPVIP Dev" --multisite --mu-plugins="~/vipdev/vip-go-mu-plugins" --client-code="~/vipdev/vip-go-skeleton" --wordpress="5.7.2" --php="7.4" --jetpack="mu"