Skip to content

Backgrounds

How-to Guides

Technical References

Local development /

Set up a VIP Go local development site

Pro Tip

A new, easy to use VIP local development solution is in beta. It allows developers to set up and tear down local environments quickly. We encourage you to test it out; feedback is welcome!

Note

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

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.

A local working environment is an important tool for your testing and development workflow. You can create a local dev environment that is nearly identical to your VIP Go environment by provisioning your local environment with three GitHub codebases:

  • WordPress core (tracking the most current version)
  • vip-go-mu-plugins
  • the codebase from your site repo.

Which application you choose to use for your local WordPress environment is up to you. Some options are:  Chassis, @wordpress/env, and Varying Vagrant Vagrants. You will find specific instructions for Varying Vagrant Vagrants (VVV) below.

Provisioning a local development environment

Step 1: Add your site’s codebase

Once your local WordPress environment app of choice is installed and running, find and remove the entire wp-content directory.

git clone your VIP Go site repo in place of it, using the following command, replacing {CLONE URL} with the GitHub clone URL for your VIP Go GitHub repository, and replacing {local_file_path} with the correct file path on your local environment to your WordPress install.

git clone {CLONE URL} {local_file_path}/wp-content

VIP Go sites must use the wp-content folder structure as seen in 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 will most likely use that repo instead.

Step 2: Add 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 can accomplish that with the following command by replacing {local_file_path} with the correct file path on your local environment to your WordPress install.

git clone git@github.com:Automattic/vip-go-mu-plugins.git --recursive {local_file_path}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.

Alternatively, you can use the build-generated mu-plugins repository for local development. This repository does not contain submodules.

Caution

Do not commit the mu-plugins/ directory to your VIP Go 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. 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.

Step 4: Update your wp-config file

You will be adding code to your 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 your local environment will prevent themes and plugins from being uploaded or updated via the wp-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 Go environment.

Step 5: Create an admin user via WP-CLI

Your local environment application should already have WP-CLI installed, but documentation is available if you need to install it yourself.

Using WP-CLI, create a new user account with the administrator role in order to access your local wp-admin.

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

Once you have successfully create a new user account for yourself and logged 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 using 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 your browser. After logging in you should see

  • a “VIP” menu in the left-hand navigation panel of the wp-admin, indicating that the vip-go-mu-plugins successfully provisioned.
  • your site’s themes and plugins listed on the themes and plugins dashboards indicating that your site’s VIP GitHub repo code successfully provisioned.

VVV for VIP Go development

Windows-specific VVV set up instructions are also available.

Step 1: Setting up VVV

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

Step 2: Add a new site and site settings

VVV’s documentation provides general instructions for adding a new site to your local environment by editing your config/config.yml file.

However, your config/config.yml file can be edited to not only create a new site, but you can also add settings that specify your new site to be provisioned by your VIP GitHub repo and the necessary vip-go-mu-plugins repo.

Open your config/config.yml file in your editor of choice. Add a new site in the sites: section of the file by copying and pasting the example below and replacing {site name} with the name of your VIP Go GitHub repository.

For example: github.com/wpcomvip/sitename.

# Replace {site name} with your GitHub repo slug
  {site name}:
    repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template.git
    hosts:
      - {site name}.test
    folders:
      # VIP Site repo
      public_html/wp-content/:
        git:
          repo: https://github.com/wpcomvip/{site name}.git
          overwrite_on_clone: true
      # VIP Go MU Plugins
      public_html/wp-content/mu-plugins:
        git:
          repo: https://github.com/Automattic/vip-go-mu-plugins.git
          overwrite_on_clone: true
          hard_reset: true
          pull: true
      custom:
        wp_type: subdirectory
        wpconfig_constants:
          WP_ALLOW_MULTISITE: true
          MULTISITE: true
          SUBDOMAIN_INSTALL: false
          PATH_CURRENT_SITE: "/"
          SITE_ID_CURRENT_SITE: 1
          BLOG_ID_CURRENT_SITE: 1
          WP_DEBUG: true
          WP_DEBUG_LOG: true
          WP_DEBUG_DISPLAY: true
          SCRIPT_DEBUG: true
          VIP_GO_APP_ENVIRONMENT: true
          DISALLOW_FILE_EDIT: true
          DISALLOW_FILE_MODS: true
          AUTOMATIC_UPDATER_DISABLED: true
          # CHANGE THESE:
          DOMAIN_CURRENT_SITE: "{site name}.test"
        admin_user: "<your_admin_account>"
        admin_password: "<your_admin_password>"
        admin_email: "admin@{site name}.test"

Then, replace the values for admin_user and admin_password with values of your choosing. 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.

When this is complete, reprovision VVV by running the command vagrant provision.

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).

Step 3: Set up object-cache.php

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.

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

Using a 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 will need to be removed before importing into a local or staging environment, to avoid creating Jetpack conflicts with the production site. You can also update your local wp-config.php file to put Jetpack into offline development mode or online staging mode.

Media library

For most local develop environments, it is helpful to be able to load the media files from your production environment to accompany your content. Rather than downloading extremely large media backups, we recommend that you use an available stage file proxy plugin. This plugin mirrors the files from your production media library to your local environment on-the-fly, bypassing the need to download a giant uploads directory.

On VIP Go, your media library is backed up securely and redundantly for each site using a system separate from VaultPress. If you require a complete export of your media library, you can request a copy by opening a ticket with us.

Last updated: July 14, 2021