WordPress.com VIP Platform
This document is for sites running on our WordPress.com VIP platform.
- Getting Started
- Optional JS & CSS Concatenation Configuration
- Default Usernames and Passwords
- Upgrading Quickstart
- Vagrant Primer
- Enabling and Activating a Custom Theme
- Loading Plugins
- Flushing Permalinks
- Importing Content
- Unit Testing
- Differences between Quickstart and WordPress.com
- Installation Tips
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.
- Tested with a host running Ubuntu 12.04
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.
git clone --recursive https://github.com/Automattic/vip-quickstart.git
- Use Zeroconf or set “10.86.73.80 vip.local” in your /etc/hosts file (path varies by platform)
- Change directory to the vip-quickstart directory: cd vip-quickstart
- Get a hot/cold drink, wait ~10-15 mins depending on your download bandwidth
- 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) #
- Add user with SSH key
- Install Puppet and Git
git clone --recursive https://github.com/Automattic/vip-quickstart.git /srv
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.
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”)
OS X #
Zeroconf is built-in to OS X and shouldn’t require any configuration.
If you have iTunes, you already have this. Otherwise, you need to install Bonjour.
sudo apt-get install avahi-dnsconfd
Optional JS & CSS Concatenation Configuration #
Default Usernames and Passwords #
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:
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:
Once the theme is in the correct directory, you can “Network Enable” it from this page:
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.
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-testsfrom within the VM.
To create unit tests for your plugin/theme #
- Navigate to your theme or plugin within the VM. (eg.
- Use WP CLI to the generate the plugin test files. Eg.
wp scaffold plugin-tests my-plugin
phpunitinside your theme or plugin directory.
- Start building your tests within the newly created
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 sshfrom the
vip-quickstartdirectory to login to the virtual machine. If neither work, try
vagrant statusto 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.phpshould 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.