Understanding your VIP Go codebase

VIP Go platform specific

This document is for sites running on VIP Go.

Learn more

Overview #

On the VIP Go platform, the codebase essentially consists of core WordPress. In fact, the only modifications made are via a handful of mu-plugins that are available via GitHub. All other custom code will be your own and committed to your Git repository. When developing your site, it is vital that you use the same mu-plugins in your test environment.

↑ Top ↑

What can I put in my VIP Go repository? #

When we create you a new VIP Go site, we will provide a GitHub repository under the wpcomvip GitHub organization. The repository for each VIP Go site has the following directory structure:

  • plugins — for your plugins
  • themes — for your themes
  • client-mu-plugins — for always active, global plugins (similar to mu-plugins)
  • vip-config — for custom configuration changes, and additional sunrise.php code
  • languages – for your translations
  • private – for any files which must not be web accessible

Note that all of these directories are required and should not be removed.

Any directories included in your client repository on GitHub which are not included in the above list will not be mounted into your site, and so will not be web accessible.

The plugins and themes directories are mapped to wp-content/plugins/ and wp-content/themes/ and should be treated like any other WordPress install.

The vip-config directory contains a file named vip-config.php. This is where you put things you’d usually find in wp-config.php. Not all settings can be changed as we have optimized certain aspects of the WordPress install but it is handy if you need to define something like an API key or secret. Note that most of WordPress is not available when this file is loaded and code should be limited to pure PHP.

The languages directory is mapped to wp-content/languages, and should contain the .po and .mo files which specify the translated strings for your site.

The private directory is mapped to /private/, which is not web accessible; you might use this to store files you stream via PHP, e.g. a commercial plugin which you are charging for, and for which you need to check a purchase record before starting the download.

You can take a look at vip-skeleton to see an example of this structure.

You can read accessing your code to understand how to get access to your repository.

↑ Top ↑

VIP Go MU plugins #

The VIP Go MU (“Must Use”) plugins are deployed to all VIP Go WordPress applications. The MU plugins codebase provides VIP Go WordPress applications with integration to the VIP Go infrastructure, e.g. cache management, as well as various helper functions and performance enhancements commonly used by applications hosted on our platform.

Our MU plugins are open sourced, and you can follow the development on our GitHub repository here:

https://github.com/Automattic/vip-go-mu-plugins/

 

If you simply want a “built” copy of the code, avoiding the complexities of submodules, then the simplest way to get that is from our “built” repository:

https://github.com/Automattic/vip-go-mu-plugins-built/

Your local development environment must include a copy of our MU plugins.

↑ Top ↑

How does the code get deployed? #

Each VIP Go site or environment tracks a specific branch of your repository. For example, the production environment will track the master branch; if you have requested other sites they will each have a specific branch they are tracking.

If you have a child environment, the branch will always auto-deploy. For the production environment, the master branch will auto-deploy in the time leading up to and during the initial code review. Once the initial review has been completed, we will enable the GitHub Pull Request workflow, which is covered here.

↑ Top ↑

Plugins on VIP Go #

See our separate document on installing and activating plugins on VIP Go.

↑ Top ↑

sunrise.php #

See the separate document sunrise.php on VIP Go.

↑ Top ↑

How do I access my code? #

See Accessing your code.

↑ Top ↑

About themes on VIP Go #

Theme Naming

Themes in the VIP Go environment live in WP_CONTENT_DIR . '/themes/'. So if your organization is called Acme Kite Co., for example, your theme path might be /themes/acmekites/.

If you anticipate setting up multiple themes for your site or if you are a developer working on different themes for different sites, you might need a naming scheme that further distinguishes themes, e.g. /themes/acmekites-main/ and /themes/acmekites-seasonal/.

Child Themes #

Child theme-ing works the same in this case as child theming on self-hosted WordPress sites. Just add another theme to your Git repository at /themes.  Because the themes on WordPress.com aren’t available in the Git repository, they will need to be added before they can be used as parent themes.

↑ Top ↑

No required code in functions.php and no vip-init.php #

Unlike WordPress.com VIP, there is no required code in the theme’s functions.php file, nor do you need a vip-init.php file.

Use Underscores for a head start

The Underscores project will generate a starter theme that can be used to get a head start on your theme development. It includes lean, well-commented, modern, HTML5 templates, minimal CSS that’s ready for you to build on, and a variety of tools to help you work efficiently in customizing your theme

↑ Top ↑

Using /private #

The /private folder in your repo, if used, will provide access to files that are not web accessible, but can be accessed by your theme or plugins. We provide a constant, WPCOM_VIP_PRIVATE_DIR, which contains the path to the private folder, and you should always use this to access the /private folder.

For example, if you place a file at /private/sites.json you can access that within your theme with:

file_get_contents( WPCOM_VIP_PRIVATE_DIR . '/sites.json' );

Please note that this constant is only available inside theme or plugin code; using it in vip-config.php is too early and will not produce the desired behaviour.

No visitor will be able to access that file at any URL, unless deliberately exposed via the theme or a plugin.

Like all code directories on VIP Go, the /private directory is not writable by PHP so you cannot save uploaded files to it.

The /private folder is mapped to /private, in the root of the filesystem, on the VIP Go server.

↑ Top ↑

What versions of WordPress and Jetpack does VIP Go use? #

Your website will be running the latest stable version of WordPress and Jetpack at all times.

In advance of a major version update for WordPress core or Jetpack (e.g. from 4.1 to 4.2) to VIP Go, as the beta testing period begins, WordPress.com VIP will post to the VIP Lobby. The deployment of minor versions will not receive a Lobby post. Security updates will be deployed as soon as practicable, and will not receive a Lobby post.

We provide the facility to test beta and release candidates of Jetpack of Jetpack on VIP Go.

During the run up to a new version of WordPress, we invite our clients to run their non-production sites against trunk (here is the core WordPress project explanation of trunk and other SVN terms. If you’d like one or all of your non-production sites to track trunk, please get in touch. Sites tracking trunk will be updated to the latest trunk revision at least once a day, but we cannot guarantee the timing of this update.

↑ Top ↑

How do new versions of WordPress get released? #

As a new release is tagged on WordPress.org we will begin rolling it out to our customers. This is a rolling upgrade process and is normally completed within 48 hours of an official release. A small subset of sites are tested before the wider release to ensure stability. WordPress.com VIP continually monitors all VIP sites to ensure they are up and serving a reasonable response code, and this process continues as we roll out releases to our customers.

As a release approaches, you should test your site against WordPress core betas and release candidates as they are released, to ensure the upgrade process goes smoothly.

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.