Skip to content

Backgrounds

How-to Guides

Technical References

Local development

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:

VIP’s local development option (currently in beta) provisions all three required codebases and offers built-in options for local development, local debugging, and minor testing.

Other examples of local environment applications to choose from are:  Chassis, @wordpress/env, and Varying Vagrant Vagrants. If setting up a Varying Vagrant Vagrants (VVV) local development environment, refer to the instructions for setting up VVV for VIP.

Prerequisites

These instructions assume familiarity with command line tools on a macOS, Linux, or similar Operating System.

The /vip-go-mu-plugins/ repository uses SSH protocol for submodules. Because GitHub does not allow anonymous SSH connections, a GitHub account’s SSH key will need to be set up and used for interaction with the repository (cloning and submodule updates).

Alternatively, the built version of the mu-plugins repository can be used for local development. This repository does not contain submodules.

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 https://github.com/automattic/vip-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-go-mu-plugins

The VIP Platform uses a series of platform-specific plugins which are found in the vip-go-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.

Caution

Do not commit the locally created /mu-plugins/ directory to a VIP site’s repository.

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.php. In order for object-cache.php  to be activated in a local environment, symlink that file 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.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. */

// 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 );

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 your local environment and your VIP Platform environment.

Step 5: Create an admin user via 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 the 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. After logging in:

  • a “VIP” menu in the left-hand navigation panel of the /wp-admin/, indicates that the /vip-go-mu-plugins/ successfully provisioned.
  • the expected themes and plugins listed on the themes and plugins dashboards indicate that the site’s VIP GitHub repository code was successfully provisioned.

Last updated: September 13, 2021