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:
- Node and npm
- VIP CLI
- Docker Desktop
- git on command line
- NVM (optional)
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.
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