Skip to content

Backgrounds

How-to Guides

Technical References

Local development /

Using 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.

Caution

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 xcode-select --install.

NVM (optional)

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

Creating Environments

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.

Note: The vip dev-env command has multiple other subcommands, available with the --help flag.

Using Application ID

Identify the application ID you’d like to use from your VIP dashboard to create the environment (replace 345 with your 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.

1) Create

Replace 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 vip dev-env.

1) Set Up a Working Directory

Open a Terminal window and create a working directory. In the example below, we’ll use vipdev:

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.

3) Create

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-go-mu-plugins and vip-go-skeleton ):

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 --client-code parameter.

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.

You can open Docker Desktop to see the status of the stacks, but the buttons there may not work. Use the VIP command line tools to restart, destroy, etc.

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.

Default Credentials

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

Username: vipgo
Password: password

Cleaning Up

When you’re completely done, the destroy command will take care of removing the stacks:

vip @345 dev-env destroy

Last updated: October 18, 2021