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-go-mu-plugins/
- the codebase from a site’s repository.
Prerequisites
- 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).
- The built version of the mu-plugins repository does not contain submodules and can also be used for local development.
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-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:
cd
into the /wp-content/ directory.- 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 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: April 03, 2023