Skip to content

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:

Prerequisites

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.

Caution

Do not commit the locally created /mu-plugins/ directory to a VIP application’s wpcomvip GitHub 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-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.

Last updated: December 23, 2023

Relevant to

  • WordPress