⚠️ 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.
VIP-CLI can create and control a local environment that mimics an environment running on the VIP platform on a supported local machine. This environment can be used for local development, quick testing, tutorials, or other activities where a local stack is more convenient than a pre-production WordPress VIP environment.
Just like the VIP Platform, the local development environment uses a container-based solution to provide the various services and code needed for an application.
The WordPress VIP local environment provides the following services:
- A web stack (nginx, PHP, WordPress) including a customer repository (for the application code) and VIP’s vip-go-mu-plugins codebase.
- Memcached, an object cache solution
- MySQL / MariaDB, the database needed for WordPress
- Elasticsearch, a dedicated indexing and search solution that is the basis of Enterprise Search
We also supply PHPMyAdmin as a development tool. This is not included in the stack by default, therefore, the
--phpmyadmin argument must be included in your chosen
$ vip dev-env create command if you wish to use this tool.
Hat tip: Lando
The VIP local development environment uses Lando under-the-hood to simplify orchestration. Looking for a free, open source, Docker-based tool that simplifies your local development experience? Check them out!
The local development environment requires:
These should be supported on Mac (OS/X), Linux, and Windows 10.
Please follow our installation guide to get the dependencies set up and a basic development environment running.
There is no theoretical limit to how many local environments you can have locally. They only need to have unique names.
As with other VIP-CLI commands, the
@<site-id>.<environment-name> notation is supported (but not required for dev environments). This will among other things be used to name the environment accordingly.
To give the environment an alias or create a different environment that would otherwise conflict in name you can use the
--slug=<name> argument for all dev-env subcommands.
The rest of the examples in this document will rely on default naming without explicitly targeting the environment by name.
The VIP Local Development Environment is controlled (created, started, stopped, and destroyed) by the VIP-CLI command
To list all possible
dev-env operations (subcommands) and their descriptions run
vip dev-env with the
vip dev-env --help
create must be called in order to use the VIP Local Development Environment using one of three methods.
Method 1: Create a local environment using a setup wizard
vip dev-env create
Method 2: Create a local environment using a setup wizard that has some setting values pre-populated with those of an existing VIP Platform environment.
vip @appID.production dev-env create
Method 3: Create a local environment and configure settings by using available arguments.
vip --slug=example-site dev-env create --title="WPVIP Dev" --multisite --phpmyadmin --mu-plugins="~/vipdev/vip-go-mu-plugins" --client-code="~/vipdev/vip-go-skeleton" --wordpress="5.7.2"
For some of the environment services, you will have the following options to source them:
- image – This will fetch a publicly accessible docker image of that component that was prepared for this purpose. This is easier to set up, since it will be provided without too much of your interaction. However the drawback is that it is more difficult to update the code in such components and changes are not persisted in all cases (you can do that by changing the code directly in the running container).
- local – Providing a full path to the folder containing the given service source code. For example, a local clone of your repository, or a local clone of vip-go-mu-plugins. Changes to that code should be reflected in the running environment(s).
To start or stop the environment you would execute the following command:
vip --slug=example-site dev-env start vip --slug=example-site dev-env stop
To get information about the status and location of configuration files for existing local environments, use the
info subcommand with the
--slug name, or use
--all to get an info list of all existing local environments.
vip dev-env info --all
Stopping merely suspends a stack. Destroy cleans it up.
Environments can be destroyed using this command. The base command will make sure all the underlying docker containers and volumes are stopped and removed. Then the configuration files created by the
create subcommand will be removed as well.
vip --slug=example-site dev-env destroy
Note that locally cloned directories will not be affected.
--soft can be specified as an option, to only remove the docker containers and volumes, but leave the configuration intact, so it may be restarted later.
We provide support for a few useful commands to be executed directly on a running local environment. To separate the arguments for the vip process and the command to be executed, use
-- (two standard hyphens).
The help command’s example section lists a few useful examples:
vip dev-env exec --help
The most notable: there is an option to run
wp cli commands on the environment. For example, the following will list posts on the environment. Note that this runs the WP-CLI inside the environment and supports all CLI operations you are used to, including any custom commands that are enabled in code.
vip --slug=example-site dev-env exec -- wp post list
Commands executed this way run inside the containers as opposed to the host machine. Therefore they do not have direct access to the hosts. One implication of this is that paths to local files on the host machine might not work as expected.
You may import tables or an entire database export via the
import has also a support for media files import.
SQL import comes with
--search-replace support that can be used to change domains.
vip --slug=example-site dev-env import sql ./wordpress.sql --search-replace="example-site.com,example-site.lndo.site"
Depending on whether you’re importing one subsite, a multisite, or a single site, you will need to run additional search/replace commands and then flush the object cache before you can continue.
For example, after creating a subsite via wp-admin, and then importing all tables for that subsite, these commands should update the tables with the correct URLs. This example is for this website, with tables for subsite 2 beginning with
vip --slug=example-site dev-env exec -- wp search-replace example-subsite.example-site.com example-subsite.example-site.lndo.site --all-tables-with-prefix wp_2_* --dry-run vip --slug=example-site dev-env exec -- wp search-replace example-subsite.example-site.com example-subsite.example-site.lndo.site --all-tables-with-prefix wp_2_* vip --slug=example-site dev-env exec -- wp cache flush --url=http://example-subsite.example-site.lndo.site
Behind the scenes, we share the import file provided for SQL import with the container. Place the import file under the home directory of the current user.
After the SQL import, the command will clear the cache and add a super-admin user
These command arguments are typically prefaced by a double hyphen (
--). Not every argument has meaning for every subcommand.
Specifies the target environment name, helpful when multiple environments are defined.
Specifies the site title, which will appear in the site’s UI.
Specifies the client / customer code directory, typically your working copy of a GitHub repository.
Specifies the vip-go-mu-plugins code directory, if you’d like to clone the main repository for use in debugging or to contribute to the project. Submodules should be initialized with
git submodule update --init.
Include this with no attribute to indicate the environment is a multisite.
Use this to specify the version (e.g. “5.7.2”) of WordPress core to use.
Include this with no attribute to include a PHPMyAdmin instance in the environment stack.
Use this to specify a particular version of PHP (e.g. “7.4”)
A shorthand to reference all sites, useful with the info subcommand.
Modifies the destroy subcommand to be not fully destructive, leaves the named environment’s configuration in place for later use.