Skip to content

Backgrounds

How-to Guides

Technical References

Local development /

Set up VVV for VIP development

The following instructions are specific setting up VVV or Varying Vagrant Vagrants for local development. Instructions for setting up a local environment that are not application-specific are also available.

Prerequisites

The instructions below assume that you have already successfully completed the steps to install VVV on your local machine.

Add a new site and site settings

VVV’s documentation provides instructions for adding a new site to a local environment by editing the VVV config found at /config/config.yml.

This config can be edited to not only add a new site, but it can also provision the site with your application’s repository and the necessary VIP Go MU Plugins repository.

To do this, edit /config/config.yml in a file editor of your 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 corresponding slug of your application’s GitHub repository.

For example: If provisioning a new site with code from the repository at https://github.com/wpcomvip/vip-go-example, {site_name} would be replaced with the value vip-go-example.

  # 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: local
        DISALLOW_FILE_EDIT: true
        DISALLOW_FILE_MODS: true
        AUTOMATIC_UPDATER_DISABLED: true
        DOMAIN_CURRENT_SITE: "{site_name}.test"
      admin_user: "{admin_username}"
      admin_password: "{admin_password}"
      admin_email: "admin@{site_name}.test"

Replace the values for {admin_username} and {admin_password} with new values chosen by the developer setting up the local environment. This step is a security precaution to prevent default administrator user credentials from possibly being imported from a local development environment to a production environment. As an added security precaution, code in 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.

After edits to the /config/config.yml are complete, you will need to re-provision VVV by running the command vagrant provision or vagrant up --provision if VVV is not already running.

Test the new VVV site

Before working on the final VIP configurations, confirm that the site has been successfully created and the WordPress Admin can be accessed by logging in to {site_name}.test/wp-admin/ with the user credentials that were added in the /config/config.yml file. To test the install please do the following:

  • Confirm the “VIP” menu is found in the left-hand navigation panel of the admin. This indicates that the VIP Go MU Plugins successfully provisioned.
  • Check that the expected themes and plugins are listed on the themes and plugins dashboards. This indicates that your applications repository code was successfully provisioned.

Final VIP configurations

  1. Set up the object cache: In order to use object cache in a local environment, it is necessary to create a symbolic link to the file at /mu-plugins/drop-ins/object-cache/object-cache.php from the root of the /wp-content directory:
    • in the terminal, cd into the /wp-content directory.
    • Run the symlink command: ln -s /mu-plugins/drop-ins/object-cache/object-cache.php object-cache.php
  2. Include the VIP config file: As a final step, add the following code to the wp-config.php file directly above this line:
    /* That's all, stop editing! Happy blogging. */.
// Load 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' );
}

You can read more about the VIP config file and the object cache.

Using WP-CLI on VVV

Please see the VVV documentation for instructions on using WP-CLI from the virtual machine.

Last updated: November 04, 2021