VIP Go local development

VIP Go platform specific

This document is for sites running on VIP Go.

Learn more

Overview #

Because developing sites for VIP Go is different than developing for WordPress.com hosted VIP sites, you need a different development environment.

Your VIP Go site runs three codebases: WordPress core (tracking the most current version), the VIP Go mu-plugins, and the codebase from your specific site repo. Because of this, a variety of WordPress local development environments can be suitably configured for VIP Go development purposes.

Here we describe using a Varying Vagrant Vagrants (VVV) based local development environment. Other options may include: Chassis, Docker-WP, Laravel Valet, etc.

↑ Top ↑

VVV for VIP Go Development #

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

Prerequisite: all git operations referenced in this guide assume you have an ssh keypair registered with GitHub and are using ssh (vs. https) protocols. Using https protocols may lead to unexpected errors and is not supported.

Step 1: Setting up VVV #

The basic instructions for installing VVV are in their documentation. Complete setup per their instructions before continuing below.

↑ Top ↑

Step 2: Adding your site code #

Follow the instructions to add a new site, and reprovision vagrant. Then, find and remove the entire wp-content folder at {VVV FOLDER}/www/{site name}/public_html/wp-content. Replace {VVV FOLDER} with the path to your VVV folder (i.e. the folder you installed VVV into), and {site name} with the name of your site.

Git clone your VIP Go site repo in place of it, using the following command. Replace {CLONE URL} with the GitHub clone URL for your VIP Go GitHub repository.

git clone {CLONE URL} {VVV FOLDER}/www/{site name}/public_html/wp-content

Note: VIP Go sites must use the wp-content folder structure from https://github.com/automattic/vip-skeleton. If you do not yet have a VIP Go site repo hosted with us, please use this vip-skeleton repo for the “CLONE URL” above and place your codebase (theme & plugins) within it for testing. Once your VIP Go site repo has been provisioned, you’ll most likely use that repo instead.

↑ Top ↑

Step 3: Adding the VIP Go MU plugins #

Vip Go uses a series of platform-specific plugins which are found in the  vip-go-mu-plugins repository on GitHub.  To replicate the VIP Go environment git clone this repo into wp-content/mu-plugins/. You will want to make sure the contents of the repo are in the root of mu-plugins and not a folder such as vip-go-mu-plugins which is the default. You may use the following command replacing {VVV FOLDER} with the path to your VVV folder (i.e., the folder you installed VVV into).

git clone git@github.com:Automattic/vip-go-mu-plugins.git --recursive {VVV FOLDER}/www/{site name}/public_html/wp-content/mu-plugins/

Note: the vip-go-mu-plugins repository is using SSH protocol for submodules, and as GitHub does not allow anonymous SSH connections, you’ll have to set up an SSH key for your GitHub account and use it for interaction with the repository (cloning and submodule updates).

Periodically pull changes down from this repository to ensure you have the latest code… we suggest checking for and pulling changes before the start of development on any given day:

$ cd {VVV FOLDER}/www/{site name}/public_html/wp-content/mu-plugins/
$ git pull origin master
$ git submodule update --init --recursive

Note: Do not commit the mu-plugins/ directory to your VIP Go site’s repository.

The object-cache.php code that’s used in production can be found in drop-ins/object-cache/object-cache.php. Be sure to copy or symlink that to the root of wp-content in order for it to be activated in your local environment. If you have multiple sites using the same repo, be sure to set WP_CACHE_KEY_SALT for each site to avoid cache key collisions.

↑ Top ↑

Step 4: Updating your wp-config file #

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

Include 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' );
}

Account for file permissions and auto-updates:

The local environment will replicate the file permissions behaviour on VIP Go found in mu-plugins/a8c-files.php only allowing files to be uploaded to tmp and uploads. The following constants should also be added to replicate the file setup on VIP Go. This prevents plugins and themes from being uploaded or updated from WP-Admin matching the Go environment.

define( 'DISALLOW_FILE_EDIT', true );
define( 'DISALLOW_FILE_MODS', true );
define( 'AUTOMATIC_UPDATER_DISABLED', true );

↑ Top ↑

Step 5: Creating an admin user via WP-CLI #

SSH into the VVV virtual machine and use WP-CLI to create a new user account with the administrator role. Use the new admin user account to access WP Admin and delete the default admin user account.

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

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 using the admin username and display the notice: Logins are restricted for that user. Please try a different user account.

↑ Top ↑

Step 6: Finishing up #

Your development environment is ready to “Go”.  Navigate to site-name.test/wp-admin in your browser and log in and you should see a “VIP” menu in wp-admin.

↑ Top ↑

Using the site’s content in local development #

VIP includes VaultPress access with each VIP site, to give clients the ability to self-service the download of hourly SQL database backups. VaultPress is accessible from each site’s WordPress dashboard, under the Jetpack menu. For multisite environments, each site is stored separately in VaultPress. Note that only wp_-prefixed tables are included in these backups.

This backup can then be imported into a local development environment using WP CLI. The jetpack_optionsrow needs to be removed before importing into a local or staging environment, to avoid creating Jetpack conflicts with the production site.

Although VaultPress on VIP Go offers SQL backups only, the media library for each site is redundantly backed up and secure. Please open a ticket to request a copy of the media library.

Ready to get started?

Drop us a note.

No matter where you are in the planning process, we’re happy to help, and we’re actual humans here on the other side of the form. 👋 We’re here to discuss your challenges and plans, evaluate your existing resources or a potential partner, or even make some initial recommendations. And, of course, we’re here to help any time you’re in the market for some robust WordPress awesomeness.