Set up a third-party local development app

VIP recommends setting up a local development environment with the VIP Local Development Environment feature built into VIP-CLI. The steps outlined here are a separate and alternative method for setting up a local environment for applications such as Chassis or @wordpress/env.

A local working development environment that is nearly identical to a VIP Platform environment can be created by provisioning a local environment application with three GitHub codebases:

• WordPress core (tracking the most current version)
• VIP MU plugins
• An application’s wpcomvip GitHub repository.

Step 1: Add the site’s codebase

Once a local WordPress environment application is installed and running, locate and remove the entire /wp-content/ directory.

git clone the VIP site repo in place of it, using the following command, replacing {CLONE URL} with the GitHub clone URL for the site’s VIP Platform GitHub repository, and replacing {local_file_path} with the correct file path on the local environment to the WordPress install.

git clone {CLONE URL} {local_file_path}/wp-content

VIP Platform sites must use the /wp-content/ directory structure as seen in the WordPress codebase skeleton. For sites that do not yet have a GitHub repository hosted by the VIP Platform, use the vip-skeleton repository for the {CLONE URL} above and place the codebase (theme & plugins) within it for testing.

Step 2: Add VIP MU plugins

The VIP Platform uses a series of platform-specific plugins which are found in the VIP MU plugins repository on GitHub.  To replicate the VIP Platform environment, git clone this repo into /wp-content/mu-plugins/. Ensure that the contents of the repository are in the root of /mu-plugins/ and not a directory such as /vip-go-mu-plugins/, which is the default.

The following command structure will accomplish the provisioning of the /mu-plugins/ directory by replacing {local_file_path} with the correct file path on the local environment to the WordPress install.

git clone git@github.com:Automattic/vip-go-mu-plugins.git --recursive {local_file_path}wp-content/mu-plugins/

It is recommended to pull changes down from this repository before the start of development on any given day to ensure that the latest code is provisioned.

Step 3: Set up the object cache

The object-cache.php code that’s used in production can be found in /drop-ins/object-cache/object-cache-stable.php. In order for object-cache.php to be activated in a local environment, create a symlink to the root of the /wp-content/ directory:

1. cd into the /wp-content/ directory.
2. Run the symlink command:

ln -s mu-plugins/drop-ins/object-cache/object-cache-stable.php object-cache.php

Step 4: Update wp-config.php

Add the following code to the wp-config.php file just above this line:
/* That's all, stop editing! Happy blogging. */

// Load early dependencies
if ( file_exists( __DIR__ . '/wp-content/mu-plugins/000-pre-vip-config/requires.php' ) ) {
    require_once __DIR__ . '/wp-content/mu-plugins/000-pre-vip-config/requires.php';
}
// Loading the VIP config file
if ( file_exists( __DIR__ . '/wp-content/vip-config/vip-config.php' ) ) {
    require_once __DIR__ . '/wp-content/vip-config/vip-config.php';
}

// Defining constant settings for file permissions and auto-updates
define( 'DISALLOW_FILE_EDIT', true );
define( 'DISALLOW_FILE_MODS', true );
define( 'AUTOMATIC_UPDATER_DISABLED', true );

VIP_GO_APP_ENVIRONMENT may also need to be defined as local in wp-config.php (not in vip-config.php).

000-pre-vip-config/requires.php includes some of the functionality that has to be available early, like VIP_Request_Block and our custom error handler.

Adding the above code to a local environment will prevent themes and plugins from being uploaded or updated via the WordPress Admin. The mu-plugins/a8c-files.php plugin will enforce files to be uploaded only to the /tmp/ and /uploads/ directories. Both of these settings are important for replicating the file permissions and auto-update configurations between a local environment and a VIP Platform environment.

Step 5: Create an admin user with WP-CLI

The local environment application should already have WP-CLI installed, but documentation is available if installation is needed.

Using WP-CLI, create a new user account with the administrator role in order to access the local WordPress Admin.

wp user create exampleusername user@example.com --role=administrator

Once a new user account has successfully been created and used to log in, delete the default admin user account. This step is a security precaution to avoid default administrator user credentials from a local development environment being present in a production environment. The /vip-go-mu-plugins/ will block login attempts made by an “admin” username and display the notice: Logins are restricted for that user. Please try a different user account.

Step 6: Finishing up

Navigate to site-name.test/wp-admin/ in the browser and log in. In the WordPress Admin dashboard:

• A “VIP” menu in the left-hand navigation panel of the /wp-admin/ indicates that the /vip-go-mu-plugins/ have been successfully provisioned.
• The expected themes and plugins listed on the Themes and Plugins screens indicate that the site’s wpcomvip GitHub repository code was successfully provisioned.