Restricting access to a site hosted on VIP Go

Many VIP Go clients have the requirement to control access to their site so only a specific group of users are able to access it. For launched production sites, your solution must be architected around anonymous users and authenticated users:

Anonymous users can be served with a login screen, a page with information on how to authenticate, or a simple denial notice, etc. This response should be served with an HTTP Status of 200, and you may choose to include information about how a user can authenticate to access the site fully. This response will be cached by the VIP Go page cache.

Authorized users must log in using a WordPress user account, and you can tailor the output to these users, vary the content for different users, etc. Logged in users bypass VIP Go page caching. If your organization has a Single Sign On system, then integrating this with your VIP Go site will smooth the log in experience for your users (see “Single Sign On (SSO)” below).

Requirements and Notes

Single Sign On (SSO)

Single Sign On systems provide a central log in system for all of your company’s services, they simplify life for your users by removing the need to configure separate usernames and passwords for each system each user needs to use. VIP Go allows integration with SSO systems to simplify authentication.

Your SSO integration must create local WordPress user accounts and use standard WordPress authentication cookies, in order to work correctly on the VIP Go platform. These accounts can be restricted such that they cannot user passwords to sign in and are required to authenticate via your SSO flow instead.

The VIP Support team will require access to your site, so you must allow users from inside our network to bypass your SSO integration and log in as usual with a username and password. Requests from inside our authenticated network can be identified by checking that the A8C_PROXIED_REQUEST constant is true (see “Checking for requests from inside Automattic’s network” below). If you have any questions about this, please contact us and we’ll be happy to help.

The WordPress REST API

Your site content can be accessed via the WordPress REST API, so if you need to constrain access to site content then your solution must take this into account.

As many VIP Go features utilise the WordPress REST API, we do not allow sites to disable this API completely. If you need to restrict access to your site via the WordPress REST API, you should force authentication for API endpoints.

Whitelisting access by IP address

If you need to restrict the display of certain content to authorized users, then those users must be logged in, this is to ensure that responses to these users are not cached. During the log in process (and on every subsequent request) you can hook into WordPress to reject the log in if the user is not on an authorized IP address.

In order for the VIP team to support your site our users must still be able to log in to your site, despite not being on your IP whitelist. Requests from inside our authenticated network can be identified by checking that the A8C_PROXIED_REQUEST constant is true (see “Checking for requests from inside Automattic’s network” below).

You must not add IP address restrictions for anonymous users in PHP code, and it is not possible for us to configure your site to restrict access to a limited range of IP addresses in our web server or caching layers. Implementing IP restrictions in PHP code will cause issues within the cached responses to your site; consider the following scenario:

  1. User A visits page 1, this user is from an “authorized IP address”
  2. The VIP Go site serves a tailored response to User A, showing them content only available to certain specific users
  3. The VIP Go page cache caches the response
  4. User B visits page 2, this user is not from an “authorized IP address”
  5. The VIP Go page cache responds to User B with the cached information, i.e. the content which was served to User A, content which was only intended to be available tocertain specific users

Restricting access to user uploaded files

Files which are uploaded to your VIP Go site media library are served by the VIP Go Files Service. It is not possible to control access to your uploaded files via authentication; i.e. it is not possible to restrict access to a file to logged in users only, nor to users from particular IP addresses.

You must not block xmlrpc.php

Various VIP Go platform services use the /xmlrpc.php endpoint, so this must not be blocked by any access restrictions you put into place. Access to the /xmlrpc.php endpoint is restricted to authorised requests only, so additional constraints are not necessary.

Checking for requests from inside Automattic’s network

The following code example shows how to check that the request is from a user inside Automattic’s network.

if ( defined( 'A8C_PROXIED_REQUEST' ) && true === A8C_PROXIED_REQUEST ) {
    // The request originates from WordPress.com VIP (Automattic)
}

Can I mark some entries as “no cache” to avoid issues with caching?

Anonymous user requests should always be cached, and you must not send “no cache” headers to anonymous users. If you want to show the user restricted content and not have this content cached the user should be logged in, logged in users bypass the VIP Go .

Is there a scaling issue with so many uncached users browsing my site?

Your site can scale to handle many thousands of logged in users with the help of our standard VIP Go guidelines for scaling websites. We are happy to talk through your particular use cases, please get in touch.

Basic Authentication for un-launched sites

Basic Authentication is the “pop up” prompt for a username and password which is displayed by your browser when you visit a site which is protected in this way.

While a site is under development, and for non-production sites, we can set up Basic Authentication for you. If you’d like us to do this, please contact us and we’ll be happy to do so.

It is not possible for launched production sites to use Basic Authentication, as this form of access control breaks various VIP Go platform services.

Setting up your Development Environment

Like all software development, you should develop and test your code in your local development environment before committing the code to WordPress.com VIP. This document will help you set up an environment to aid development of your WordPress.com VIP hosted site.

Please note: This document relates to the WordPress.com VIP platform. VIP Go related documentation can be found here.

Caveats

WordPress.com is a large web application that has been developed over the past 10+ years. Please note that the environment setup described here will not provide a 1:1 copy of your production environment. While we’ve tried to bridge various gaps, many features are very challenging to reproduce locally and environmental differences will exist. A non-exhaustive list of these differences can be found here.

We’re also happy to help guide and assist you with any concerns/issues you have with these differences.

Getting Started

  1. Install a local Multisite WordPress environment. We recommend Chassis or VVV.
    • Use Chassis if you want an environment that’s simple yet powerful. It’s a minimalist development setup that boots up fast and gets out of the way.
    • Use VVV if you want an environment that comes with lots of features, is highly extensible, and can run many different site configurations.
    • You can also roll your own setup (like something built on Docker).

    Note: Your environment should be be set up as a Multisite (Chassis has a config flag; VVV requires a custom site template; and custom setups can follow the Codex).

  2. Install VIP Plugins and Helpers to wp-content/themes/vip/plugins:
    svn co https://vip-svn.wordpress.com/plugins/ wp-content/themes/vip/plugins
    

    You should svn up daily to ensure you’re working with the latest code.

  3. Install VIP mu-plugins to wp-content/mu-plugins:
    git clone --recursive https://github.com/automattic/vip-wpcom-mu-plugins wp-content/mu-plugins
    

    You should git pull daily as well to ensure you’re working with the latest code.

    The readme covers other environment-specific things like concatenation and caching that you may want to set up as well.

  4. Install your theme to wp-content/themes/vip/{your-theme}. If you’re just starting out with VIP, please read through Anatomy of a VIP Theme to get an overview of what your theme should look like.

wp-content

When set up correctly, your wp-content directory should likely look something like:

wp-content/
    plugins/
    mu-plugins/
        0-local.php
        ...
    themes/
        vip/
            your-theme/
                plugins/
                    your-custom-plugin/
                        your-custom-plugin.php
                        ...
                functions.php
                style.css
                ...
            plugins/
                vip-init.php
                ...    

The Stack

As of March 13, 2017, we are using the following pieces of software across our stack:

  • Debian Wheezy
  • PHP 7.0
  • MariaDB 10.1
  • NGINX
  • Memcached

Note that the one most likely to impact your day-to-day work is the PHP version.

WordPress Updates

We are usually running the latest stable release of WordPress core on WordPress.com.

We try to provide adequate notice for releases of major versions on the platform. When a pending release is announced, we recommend switching over your local environment to use the beta tester plugin or a SVN checkout of trunk to make sure you’re running the latest version and can test for any issues before they are rolled out.

Content

You can use the built-in export/import functionality in WordPress to populate your local environment with test data. You can generate an export from your site’s Dashboard and then use either wp-cli or the Dashboard Importer to import the content. If you have issues exporting or importing, please get in touch and we’d be happy to help.

If you are just starting out and need some data to play with, check out the demo files that the Automattic Theme Team uses for building and testing new themes.

You can also use WP Options Importer to export/import options (like widgets, plugin settings, etc.).

Debugging

You should always have debugging enabled in your local environment help catch errors as you develop:

// In your wp-config.php
define( 'WP_DEBUG', true );
define( 'SAVEQUERIES', true );

// Optional
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', true );

// Learn more: https://developer.wordpress.org/themes/getting-started/setting-up-a-development-environment/#wp_debug

Development Tools

We also recommend the following plugins and tools:

Note that these tools are meant for development/debugging only and should not be included in your theme or pushed to production.

Staging Environments

For staging environments, the only difference would be to use a hosting provider of your choice for your WordPress environment (some examples include DigitalOcean, AWS, and so on).

Commit and Deploy Webhooks

As well as receiving e-mail notifications, you can set up repository-specific commit and deploy webhooks for your WordPress.com VIP code.

Set up

To tell WordPress.com which webhooks to ping, simply add a wpcom-meta.php to the root of your repo with something like this;


<?php
/**
 * Commit Webhook: https://incoming.my-webhook.com/commit
 * Deploy Webhook: https://incoming.my-webhook.com/deploy
 */

Committing that file is all you need to do to create the webhooks. If you have any difficulties, or need more information, don’t hesitate to open a ticket with us.

Note: Services, such as Slack, require data to be transformed into a standard format for their platform. So in this instance you would have to transform the data prior to passing it to Slack.

Commit Webhook

The commit webhook will provide the following data:

  • repo – The name of the repository.
  • theme – The name of the theme.
  • revision – The committed revision number.
  • committer – The WordPress.com username of the committer.

Deploy Webhook

The deploy webhook will provide the following data:

  • repo – The name of the repository.
  • theme – The name of the theme.
  • previous_revision – The previously deployed revision.
  • deployed_revision – The deployed revision number.
  • deployer – WordPress.com username of the person who deployed the revision.
  • revision_log – A log of commits between the previously deployed and newly deployed revisions.

Personalization

As the audience of your website grows, it becomes more challenging to publish content that is relevant to all readers. Personalization gives you the ability to profile each user’s behavior and capture their preferences, allowing you to display more relevant content and ultimately, keep your audience engaged.

What is personalization?

Personalization can mean different things to different people but it mainly involves providing your audience with a more customized and engaging experience. It could mean that you’re providing content that is more relevant to their geographic location or that you’re providing them more relevant content based on what they’ve viewed or liked in the past. Personalization could also mean that your users are able to share content with each other and follow people or topics that they are interested in.

Considerations

Before diving into using the most popular plugins for personalization, there are a few items that you would want to keep in mind, regardless of the type of personalization that you’re interested in. 

  • Sending data to the personalization vendor: If the personalization requires you to send them any data (user data, activity data, etc.),  you will have to include a javascript snippet in all of your pages. Be sure to choose a reliable third party vendor as slow response times on their end could affect your end-user experience.
  • Serving recommendations from the personalization vendor: As the recommendations for a specific type of user may change, the recommended list of content is typically sent dynamically from the personalization vendor’s systems. Some vendors store the user’s behavior in a cookie so that your users don’t have to rely on their service being online but make sure you understand what features of your site (if any) will be impacted if the service vendor’s systems go offline.
  • Limiting the user information that is shared: If you require users to sign in with their account, you have the added advantage of using their historical preferences to personalize. However, this would require you to share additional information with the personalization vendor. It is best to let your personalization vendor know just the username or a separate unique identifier for the user.
  • Supporting cross-channel interactions: If you want the flexibility to capture data from your users across various channels (social media, email, mobile apps, website, etc.), you will need a vendor that can unify data from all of these channels to a single user profile (typically based on the email address). Most personalization vendors that support cross-channel data gathering will also let you publish your recommendations through any of these channels.

Types of personalization

There are no limits to how you can personalize your content but the most popular options include:

Customer Identity & Access Management

Personalizations rely heavily on understanding who your customers are. A sophisticated customer identity and access management solution will help you identify your customers regardless of the device or channel they’re engaging from, allowing you to keep your message consistent across a diverse platform.

Janrain, a Featured Partner of VIP, provides a platform that combines your ability to acquire users across multiple digital and marketing channels. In addition to providing a Single Sign-On solution, they provide a hosted user database and provide integration for social sharing.

We have also had VIP clients use Gigya, another popular platform to securely manage and update user profiles, thereby giving you a great starting point to provide personal experiences.

Custom Social Network

If you have built a community, you may be looking to empower your users to share stories, like each other’s’ contributions and have a newsfeed of updates from the people or things that they follow.

The popular BuddyPress plugin built by the WordPress community provides a lot of social network features out of the box. It provides both private messaging and public sharing. However, the vision of some of our clients were better met by using a Featured Partner for custom development.

Predictive Marketing

You might have noticed that some sites have a ‘You might also like’ section, listing content related to what you have been reading. There is another variant of this personalization where content related to the current page is listed. These dynamically shortlisted links are more relevant to your users and have a higher click-through rate.

One of our featured partners: Sailthru, is the leading provider of personalized marketing communications. Their WordPress plugin makes it easy to provide personalized content through their Scout and Concierge modules. Scout provides content relevant to a page whereas Concierge provides content that is recommended for the specific user. Under the covers, both modules use predictive marketing algorithms to determine the best recommendations for your users.  We have had multiple VIP clients use Sailthru’s straightforward integration to personalize their content.

If you’re looking to add a simple ‘Related Posts’ section to your website, WordPress.com’s Related Posts feature may be all you need. It’s powered by the popular Jetpack addon, which uses ElasticSearch to analyze your content and understand its relevance to the rest of your website. You can finetune how the recommendations are displayed using the customization options.

Geo-specific content

As your audience grows, you might find it challenging to provide content that is engaging to your users regardless of where they’re from. WP.com Geo Uniques allows you to target distinct geographic markets with different content. You also have the option of defining custom location groups so that you can target groups smaller than countries.

Uploading video files

Your WordPress.com VIP site’s Media Library can be configured to accept video file types like these:

  • .mp4, .m4v (MPEG-4)
  • .mov (QuickTime)
  • .wmv (Windows Media Video)
  • .avi
  • .mpg
  • .ogv (Ogg)
  • .3gp (3GPP)
  • .3g2 (3GPP2)

To enable these file types on a VIP site, please open a support ticket.

Site Merges

As part of a migration either to WordPress.com VIP or between two WordPress.com VIP sites, you might need to perform a site merge. Doing so is potentially time-consuming and can produce issues that do not normally occur during a site migration.

What Is a Site Merge?

A site merge is any time you are migrating more than one WordPress site’s content into a single WordPress site. This could be:

  • Two (or more) sites you are intending to collapse into one new site in the course of a migration to WordPress.com VIP
  • One site on WordPress.com VIP you are closing and “folding” that content into a parent site on WordPress.com VIP

If you are migrating content and the sources come from more than one posts table, it’s a site merge.

What Makes Site Merges Different from Other Imports?

When you merge more than one WordPress site into a new or existing single site, you will almost definitely encounter post ID overlap in the two datasets. When the WordPress importer then pulls this data into the eventual target site, the post IDs will be necessarily changed as you cannot have more than one post with the same ID.

Because of this, any connections between posts or solutions that have been created to use post IDs as linking data will need to have that data reassigned or rewritten. Anything that uses post IDs will need to take this into consideration, including:

  • Parent/child relationships between posts
  • Featured image assignments for posts
  • Serialized post ID data stored in postmeta
  • Any post ID information used in shortcodes (e.g. the gallery shortcode)

While post IDs are usually the primary concern, this ID confusion can also apply to IDs in other tables, such as term and meta IDs.

Considerations

Compared to an import that is single-site to single-site, you’ll have additional things to consider before the import begins and as you create your timeline for the migration. Keep these things in mind as you work with the WordPress.com VIP team to create achievable and realistic target dates and expectations. Our advice is to keep things as simple as possible. The more complicated your merge, the more time you’ll need for troubleshooting and QA.

Timeline

  • What is your migration timeline?
    • Are you properly allotting enough time to both implement and QA post ID changes that might be necessary due to the merge?
  • How many posts and images are you importing overall?
    • The greater the number of changes, the longer the additional work for a merge will take to complete.
  • Where will you be staging your content? For WordPress.com VIP, it needs to be publicly accessible for us to download images.

Authors

  • Are you using Co-Authors-Plus on one or both sites?
  • Have you looked at author slugs and profiles between the two sites to see how much (if any) overlap you will have?
    • You may need to do bulk reassignment of guest author terms to unify the two sets of guest author profiles and attributions.
  • If you are merging from a site without Co-Authors-Plus to a site using it (or vice versa), how are you going to integrate that data and make sure your authorship attribution is properly carried forward?

Post Relationships and Custom Features

  • Are you utilizing any custom metadata relationships between posts that would encounter trouble if those post IDs were to change?
    • A good example of this is custom photo gallery implementations or even the built-in WordPress galleries feature, which depends on post IDs.
  • You will need a scripting plan to alter the post metadata as needed to match the new post ID assignments. Remember that you can use the _original_post_id meta key to determine which posts have changed and their original IDs.

Publishing Schedules and Site Activity

  • With what frequency are posts created on both sites? This will determine the merge timing and how much data will need to be brought forward using a large initial import followed by smaller delta imports. Content fixing will need to be done at each step and will change the timing available. It’s usually best to move as much as possible in the first migrations and then delta-import smaller chunks of content immediately prior to launch.

Quality Assurance

  • Migrations that involve merges will need additional time and effort dedicated to QA. Because these relationships can be altered, you’ll need to come up with a plan for determining a representative sample of posts or other content to check for consistency. It’s best to do this with the initial large import prior to launch to discover and flag and fix any potential data issues.

Who Should Perform the Merge, and When?

Site merges can and will be performed in different ways depending on the combination of source sites and target sites. Depending on the requirements of the site, it may make more sense for you to perform the merge before the site is moved to WordPress.com VIP at all.

The merge should happen completely prior to moving to WordPress.com VIP if:

  • You are merging more than one site to WordPress.com VIP and the merge can be completed prior to your launch on WordPress.com VIP, or
  • You are merging more than one site that is no longer active into a site that is also no longer active, whether it is on WordPress.com VIP already or not.

The merge should happen entirely on WordPress.com VIP if:

  • You are merging any site into a site that is already live on WordPress.com VIP.

There may be situations where a combination of the two situations is best. Please discuss the merge process with WordPress.com VIP Support for more details.

Starting the Site Merge Process

As with any import to WordPress.com VIP, please contact WordPress.com VIP Support as much in advance as possible so we are aware of and can schedule resources to assist you with the merge process. Make sure you inform us that the import is going to have merged content.

We request that you prepare a local development environment on which you can partially test the merge to look for potential problems and identify scripting needs you’ll need to address. We’ll happily provide you with partial exports for the sites you plan to merge so you can do a test run and identify problems before they occur during an actual import. Remember that imports to a live site are much more difficult to reverse; the more we can help you identify problems ahead of time, the more efficiently and error-free the eventual import and merge will be.

Making Site Merges Successful

We’ll need you and your developers to contribute code for many types of merges, usually in the form of wp-cli commands. When you contact us, we’ll send you a questionnaire to make sure we’re considering all of the factors necessary to ensure your merge is successful.

When you merge to a site on WordPress.com VIP, we’ll take care of:

  • Fixing featured images,
  • Remapping image URLs in post content,
  • Providing useful import origin meta to help you in fixing problems after the fact,
  • Fixing post parent/child relationships, and
  • Fixing duplicate Guest Authors in Co-Authors Plus that might have been created.

You and your development team will need to:

  • Identify any postmeta or shortcode usages in your site content that will be disrupted by a site merge,
  • Create and test any CLI scripts that will be needed to repair these relationships,
  • Commit any needed CLI scripts to your theme, inform us of them and their purpose, and provide us with instructions for executing them at the proper time,
  • Create any scripts needed for term mapping (or perform that prior to the import itself), and
  • Test any merges with sample data to identify potential issues prior to scheduling the site merge import(s).

If you have any questions, please don’t hesitate to contact WordPress.com VIP Support.

VIP Go Local Development

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 VVV-based local development environment. Other options may include: Chassis, Docker-WordPress, Laravel Valet, etc.

VVV for VIP Go Development

Note: These instructions assume a familiarity with command line tools an 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 GitHub readme.md. Complete setup per their instructions before continuing below.

Step 2: Add your site code

Find and remove the entire wp-content folder at {VVV FOLDER}/www/wordpress-default/public_html/wp-content. Replace {VVV FOLDER} with the path to your VVV folder (i.e. the folder you installed VVV into).

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/wordpress-default/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.

Step 3: Add the VIP Go MU plugins

Git clone the VIP Go MU plugins repo at wp-content/mu-plugins/; using the following command. Replace {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/wordpress-default/public_html/wp-content/mu-plugins/

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/wordpress-default/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.

Step 4: Include the VIP config file

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

if ( file_exists( __DIR__ . '/wp-content/vip-config/vip-config.php' ) ) {
    require_once( __DIR__ . '/wp-content/vip-config/vip-config.php' );
}

That’s it! Your development environment is ready to “Go” and you should see a “VIP” menu in wp-admin.

Disabling unused features and assets

WordPress.com comes with a bunch of useful features turned on by default, and most VIP sites make use of them every day. We also know that sites may want to disable some of these for various reasons, e.g. if you’re focused on performance and minimizing the number of assets loaded, you may want to disable any CSS/JS that would be loaded for features not in use.

We offer a number of helper functions to facilitate this:

  • wpcom_vip_disable_custom_customizer – disables the WordPress.com-specific Customizer and Custom Design
  • wpcom_vip_disable_devicepx_js – devicepx.js loads retina/HiDPI versions of certain files (Gravatars, etc) for devices that run at a higher resolution (such as smartphones). Using this function disables it.
  • wpcom_vip_disable_global_terms – remove your taxonomy from the global taxonomy array
  • wpcom_vip_disable_hovercards – if you are not using Gravatars and Blavatars and need to disable the loading of related Javascript and CSS resources
  • wpcom_vip_disable_likes – disables Likes for Posts and Custom Post Types. Sharing can also be disabled from the Dashboard (Settings > Sharing).
  • wpcom_vip_remove_opensearch – disables rendering of the OpenSearch description documents at /osd.xml and /opensearch.xml
  • wpcom_vip_disable_sharing – disables Sharing in Posts and Pages
  • wpcom_vip_disable_sharing_resources – disables the CSS/JS involved in Sharing functions, powering things like smart buttons and share counts displayed alongside the buttons.
  • wpcom_vip_remove_playlist_styles – disables enqueuing of wp-mediaelement.css which is necessary for sites using Playlist shortcode
  • wpcom_vip_remove_mp6_styles – disables enqueuing f mp6-hacks.css stylesheet which adds backward compatibility for legacy .mp6 body classes
  • wpcom_vip_load_geolocation_styles_only_when_needed – Conditionally dequeues Geo Location stylesheets in case they are not needed. IE.: post is not actually using Geo Location
  • wpcom_vip_remove_bbpress2_staff_css – disables enqueueing of wpcom-bbpress-premium-themes.css stylesheet

Check out all of the helper functions available.

Rolling Back / Reverting Changes to Your Theme Using Subversion

You can access your theme repository version history and, when necessary, quickly roll back your deployed theme to a previous state.

The Time Machine

Every time you commit a change to your theme to your VIP theme repository, Subversion remembers by creating a version. Each of these versions is assigned a unique number and certain other meta, namely: the username of the person who made the version, the date and time of the version, the number of lines of code changed in the version relative to the previous one and a commit message indicating the nature of the changes in the version.

You can inspect your theme’s version history on the command line using the svn log command (documentation: clitortoiseSVN.) Here’s some sample svn log output for Automattic’s test theme on VIP:

vip/test-theme$ svn log .
------------------------------------------------------------------------
r69251 | viper007bond | 2012-06-20 21:09:52 +0000 (Wed, 20 Jun 2012) | 1 line

Remove testing code
------------------------------------------------------------------------
r69209 | batmoo | 2012-06-20 13:59:49 +0000 (Wed, 20 Jun 2012) | 2 lines

auto-deploy: rm image in a subfolder
------------------------------------------------------------------------
r69197 | batmoo | 2012-06-20 13:40:55 +0000 (Wed, 20 Jun 2012) | 2 lines

Auto-deploy: testing a php + css commit
------------------------------------------------------------------------
r66930 | tottdev | 2012-05-27 11:19:52 +0000 (Sun, 27 May 2012) | 1 line

reverting error code

To inspect a commit in more detail (such as seeing the changes it introduced), svn provides the svn diff command (docs: clitortoiseSVN.) Here’s an example:

vip/test-theme$ svn diff -c 17546 .

Index: header.php
===================================================================
--- header.php	(revision 17545)
+++ header.php	(revision 17546)
@@ -6,7 +6,6 @@
 
  
 
-<meta name="generator" content="WordPress "/> 
 
 <link rel="stylesheet" href="?2" type="text/css" media="screen" />
 

The -c flag shows a change set resulting from a single revision, but there are many other options including -r n:m (show differences between revision n and m) and more — see the svn diff documentation for full details.

Reverting

If you need to roll back code you’ve committed it to the deploy queue, the quickest way to do this is to revert and commit the code yourself. Here’s how to prepare and push a roll-back:

1. Update your theme’s working copy to the latest revision (use

svn up your-theme

or tortoiseSVN.)

2. Use svn log to find out how far you’d like to roll back. Suppose your log reveals something like:

r4 -- change paint color
r3 -- introduce clunk engine
r2 -- modify blee tag
r1 -- add snorkle

3. Use svn merge to roll back the code to the revision before things went ‘wrong.’ For example, a typical cli command for this would be:

vip/my-theme$ svn merge -c -4 -c -3 .

This “un-does” the commits with version numbers 3 and 4, and rolls the code back to its previous state as of revision 2. As with svn diff, the merge command admits lots of different syntax combinations. You can read about some of those here and here. You can also roll back easily using clients like tortoiseSVN.

4. The merge you just performed has produced a changeset in your working copy. Commit your roll-back like any other change using svn commit.

Make sure that you include an explanatory commit message such as “roll-back of r3 and r4 due to JS error”. Your message should indicate which versions are being rolled back, and for what reason. This will help WordPress.com VIP deploy engineers quickly deploy your changeset.

Pure roll-backs usually require little or no review, and can be deployed almost immediately, so make sure your change only contains the roll-back, and nothing else.

In an emergency situation, you can open an urgent ticket requesting a deploy of your roll-back. Generally this is not necessary, however, and we request that you reserve urgent tickets for when your site is down or for other serious end-user issues.

Best practices:

1. Think in terms of “rolling back” code instead of reverting individual commits. It’s possible to revert things out of sequence. For instance in the previous example we could have reverted r3 but not r4. However, to do so ignores the possibility that something in r4 may depend on something in r3. In almost all cases, it’s safer to roll back all commits in sequence, especially if doing so quickly.

2. Data dependencies. Before a major roll-back it’s good to take a second to consider whether the underlying data has changed in a way that would cause problems with the old code. Have the content or options been modified in any way, including by CLI scripts? This is not usually an issue, but can be in certain cases.

3. Confusingly, subversion also features a command called svn revert whose purpose is not to take your code to a previous state, but only to un-do local un-committed modifications. Therefore we use the term “revert” both in the sense of “roll-back” and the sense of svn revert.

4. Finally, There is an extremely large number of Subversion clients which make all of this very easy. Cornerstone is a great (though somewhat expensive) client for OSX.

VIP Quickstart

Note: VIP Quickstart is deprecated as of March 13, 2017. Support for Quickstart will continue through April 21, 2017. For new environments, we recommend using Chassis or VVV as detailed in the Local Environment documentation.

VIP Quickstart is a local development environment for WordPress.com VIP developers. It provides developers with an environment that closely mirrors WordPress.com along with all the tools we recommend developers use.

VIP Quickstart should not be used to run a production site.

See also: The VIP Quickstart Github repository.

Requirements

Local

Public Server

  • Tested with a host running Ubuntu 12.04
  • Git
  • Puppet

Getting Started

Installing locally for local development (primary use-case)

The first time you run the installer will be the slowest. This is because it has to download the virtual machine image, Ubuntu package updates, wp-cli, the full checkout of WordPress trunk, and the full VIP Plugins repository.

  1. git clone --recursive https://github.com/Automattic/vip-quickstart.git
  2. Use Zeroconf or set “10.86.73.80 vip.local” in your /etc/hosts file (path varies by platform)
  3. Change directory to the vip-quickstart directory: cd vip-quickstart
  4. Run vagrant up
  5. Get a hot/cold drink, wait ~10-15 mins depending on your download bandwidth
  6. When the install completes, load http://vip.local in your browser, login with username: wordpress, password: wordpress

Have problems installing? See Installation Tips below

Installing on a publicly accessible host for content staging, qa, client preview, etc (secondary use-case)

  1. Add user with SSH key
  2. Install Puppet and Git
  3. git clone --recursive https://github.com/Automattic/vip-quickstart.git /srv
  4. sudo /srv/bin/vip-init --server [--domain=<domain>]

If you specify –domain this will set up the Quickstart environment as ready to serve requests at that domain. You are responsible for making sure that DNS for that domain points to the IP address of your server.

If you leave the domain argument off, you’ll be prompted to enter one during setup. If you don’t specify one then, “vip.dev” is used by default, and you can work with your local DNS/hosts setup to make sure that vip.dev points to the right place.

Since we turn off root logins and password logins via SSH, you’ll need to create another user and add an SSH key so you don’t get locked out of your server. ssh-copy-id is useful for copying ssh keys on Linux. There are similar tools for other platforms.

See also: Setting up Quickstart on Amazon Web Services.

Installing on Windows (minimally supported use case)

  • Note: When you run the Git installer, make sure to install Git to your system PATH as the VIP Quickstart installer requires it.

  • If you receive a File cannot be loaded because the execution of scripts is disabled on this system error. Make sure you’re using a PowerShell interface. Use tools -> options to manage your default shell. (Right click on the repository and choose “Open a shell here”)

Zeroconf

OS X

Zeroconf is built-in to OS X and shouldn’t require any configuration.

Windows

If you have iTunes, you already have this. Otherwise, you need to install Bonjour.

Ubuntu

sudo apt-get install avahi-dnsconfd

Optional JS & CSS Concatenation Configuration

  • QUICKSTART_DISABLE_CONCAT – CSS and Javascript concatention are turned off if this is true.

Default Usernames and Passwords

MySQL

  • root:(blank)

WordPress

  • wordpress:wordpress

Upgrading Quickstart

You can upgrade an installed environment with:

  • git pull
  • vagrant provision (assuming Quickstart is already running)

If you experience issues upgrading, you may delete it and start fresh. You can do so with: vagrant destroy; rm -rf vip-quickstart , re-install per above instructions and restore your site from version control and backups.

Vagrant Primer

The Vagrant CLI documentation will be useful for developers that haven’t used Vagrant before. Since VIP Quickstart is built on top of Vagrant, the Vagrant CLI commands will also work.

Some useful commands:

  • vagrant up – Start and provisions the VM
  • vagrant halt – Stops the VM
  • vagrant reload – Restarts and provisions the VM
  • vagrant provision – Provisions the VM, requires that the VM be running
  • vagrant status – Reports the state of the VM
  • vagrant ssh – Logs into the VM with ssh
  • vagrant destroy – Deletes the VM

Enabling and Activating a Custom Theme

In order to use a custom theme in VIP Quickstart, move a valid WordPress theme folder into this directory:

../vip-quickstart/www/wp-content/themes/vip/

Once the theme is in the correct directory, you can “Network Enable” it from this page:

http://vip.local/wp-admin/network/themes.php

From there you should be able to activate it on individual sites.

Loading Plugins

To approximate the admin interface on WordPress.com, Quickstart does not have a Plugins admin menu section. Instead, you can load plugins via your theme code (usually in functions.php).

Any plugin available in the VIP shared plugins repository can be loaded with a call to wpcom_vip_load_plugin. That function will work on Quickstart and WordPress.com. If a plugin is in the VIP plugins repository, you should not copy that plugin into your theme.

To load a plugin not in the VIP shared plugin repository, take a look at how to load plugins in different locations.

We advise against any logic that makes functionality exceptions for your development environment; development and production environments should be as close as possible to avoid unexpected production-specific issues.

Flushing Permalinks

The permalinks settings pages is not available in the admin area, but if rewrite rules need to be flushed or changed, this can be done in code. To flush rewrite rules, we recommend using the WP CLI command wp rewrite flush.

You can also use WP CLI to set the permalink structure and tag/category base using the wp rewrite structure command.

Importing Content

The best way to import content into a Quickstart site is to SSH into the Vagrant VM and use the (http://wp-cli.org/commands/import/) command. It’s helpful to first move the import files into the vip-quickstart directory.

phpMyAdmin

VIP Quickstart does not include a copy of phpMyAdmin, since we do not recommend using this tool for making changes to the MySQL database as a part of your development and testing work. Instead, use WordPress’s built-in functionality and API to query and manipulate data according to our best practices.

Unit Testing

VIP Quickstart comes with a checkout of the WordPress-Tests automated testing framework. You can use this to run the unit tests for WordPress itself or for any plugin or theme that has phpunit tests defined.

To run the WordPress unit tests

  • CD to /srv/www/wp-tests from within the VM.
  • Run phpunit

To create unit tests for your plugin/theme

  1. Navigate to your theme or plugin within the VM. (eg. /srv/www/wp-content/plugins/my-plugin)
  2. Use WP CLI to the generate the plugin test files. Eg. wp scaffold plugin-tests my-plugin
  3. Run phpunit inside your theme or plugin directory.
  4. Start building your tests within the newly created tests directory.

Differences between Quickstart and WordPress.com

While we created Quickstart to mirror the WordPress.com environment as closely as possible, there are some key differences to be aware of:

  • There’s currently no support for SSL on Quickstart.
  • If you install Quickstart on a VPS that’s publicly accessible, you can take advantage of Photon, which is similar to the CDN used on WordPress.com. If Quickstart is only local, you’ll be limited to the local Media Library.
  • Some toolbar modifications on WordPress.com are not yet present in Quickstart.
  • Database encoding on WordPress.com is latin1. On Quickstart, it’s utf8.
  • Protected embeds are not yet supported on Quickstart.
  • Filesystem access is not yet fully restricted in Quickstart as it is on WordPress.com.
  • There may be minor version differences in some libraries, such as jQuery.
  • When options are added or updated on WordPress.com, we delete the alloptions cache. This is not the case on Quickstart so, for instance, you may see `get_option()` return booleans that would return a string on WordPress.com. Always assume that `get_option()` will return a string.

If you’d like to help minimize these differences, you can view the list of compat issues on GitHub.

Installation Tips

Q: My installation completed, but I see an error “The SSH command responded with a non-zero exit status…”
A: That’s normal, try loading http://vip.local in your browser or try vagrant ssh from the vip-quickstart directory to login to the virtual machine. If neither work, try vagrant status to ensure the virtual machine is running.
Q: When I open http://vip.local in my browser I get a blank screen/500 error
A: Enabling WP_DEBUG in local-config.php should reveal the PHP error, xdebug is also installed and enabled
Q: Installation is failing on provisioning, and I’m not sure what more to do
A: You can run vagrant in debug mode to get more information, including error messages you wouldn’t normally see. To do this run this command:

vagrant up --provision --debug &> vagrant.log

Also make sure you have the latest version of virtualbox, vagrant, and the vagrant box being used. As a last resort, these commands will wipe everything clean and recreate everything:

vagrant destroy
vagrant box remove precise32
vagrant plugin install vagrant-hostsupdater
vagrant plugin install vagrant-triggers
vagrant plugin install vagrant-vbguest
vagrant up --provision

The vagrant hosts updater may require your hosts file to be writable. If provisioning fails or is interrupted, try this command:

vagrant reload --provision

This will resume provisioning without destroying the box

Q: I’m getting “Error establishing a database connection”
A: Provisioning may have been interrupted, try running this command several times to ensure it completes:

vagrant reload --provision
Q: Several VIP functions are not being found and giving fatal errors
A: These functions are loaded when `vip-init.php` is included. This file should be included at the top of the themes `functions.php`, and this will show as a blocker when the theme is scanned by VIP Scanner. Make sure to run VIP Scanner and clear all blockers, and include `vip-init.php` as a priority.

Ready to get started?

Tell us about your needs

Let us lead the way. We’ll help you select a top tier development partner. We’ll train your developers, operations, infrastructure, and editorial teams. We’ll coarchitect your deployment processes. We will provide live support for peak events. We’ll help your people avoid dark alleys and blind corners, and reduce wasted cycles.