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:
- WordPress core (tracking the most current version)
- /vip-go-mu-plugins/
- the codebase from a site’s repository.
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 [email protected]: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:
cd
into the /wp-content/ directory.- 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 [email protected] --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.