Best Practices for Pantheon Project Setup

Authored by

Pantheon has an amazing developer experience, including things like:

  • using Git for deployments (no SVN in sight)
  • having dev, test (staging), and live (production) environments for each site
  • being able to push a new feature branch to Pantheon and spin up a new multidev environment or testing
  • syncing database and files from production down to test and dev, automatically handling hostname changes
  • deploying code from dev to test to live just with a couple clicks in the Dashboard
  • using of Redis for object caching: no more Memcached 1MB bucket size limitation
  • providing a CLI tool for programmatically running the actions available in the Dashboard

And much more. See the Pantheon docs.

This post is all about putting down some best practices for setting up a site on Pantheon, using GitHub for development and peer review, integrating Travis CI for code quality checks, and doing automated pushes to the Pantheon dev environment when the checks pass. The Pantheon site configuration here has been implemented here for make.xwp.co.

There are lots of other possibilities for what can be done using Pantheon’s tools, for example we could use Travis CI to push a feature branch to Pantheon, create a new multidev environment for it via the Terminus, sync the test environment’s database to it, and then use PhantomJS to do visual comparisons between the multidev environment and the test environment. Or we could have Travis run a suite of acceptance tests against such a multidev environment and then report back on whether there have been any regressions.

Some of the steps below will require devops support. And  some of the links are specific to XWP, but they can be adapted for the needs of any organization.

Note: The following steps will need to be amended now that Pantheon has made their Quicksilver Hooks system available.

1. Create site on Pantheon

The first step is to create a site on Pantheon:

01-create-site

And start the site with WordPress Core:

02-start-with-wordpress-core

Note that selecting WordPress here will link the Pantheon with the pantheon-systems/WordPress repo on GitHub as the upstream repo. When Pantheon updates this repo with new security patches. When new commits are pushed to this repo, you’ll get notified to pull them via the Pantheon dashboard.

ProTip: Try minimize modifying any files that exist in this repo. Leave the readme.html intact and leave the Akismet plugin, Hello Dolly plugin, and all the bundled Twenty* themes in place. If you remove these or modify these, then Pantheon may fail to merge the upstream updates automatically, and you’ll have to do it manually via something like:

git remote add upstream https://github.com/pantheon-systems/WordPress.git
git checkout master
git pull -X mine upstream master
git checkout origin/master -- readme.html # any files that you modified
git diff --staged # sanity check
git commit
git push origin master

2. Enable the Redis Add-On

Redis is not enabled by default. You need to make sure it is enabled before merging in our customized upstream which has the WP Redis object cache enabled via a drop-in plugin. To enable Redis, just go to your site dashboard and and Settings > Add Ons > Redis:

02-redis-add

3. Create private repo on GitHub

Pantheon is now set up with their vanilla WordPress Core install. Sites on Pantheon are just Git repos which are clones/forks of their Core upstream repo on GitHub. In order to facilitate our development workflows, create a new private repo on GitHub (or better, have a client create this repo on their GitHub organization, and then fork it into the XWP organization to save on our private repo allowance). Having a repo on GitHub allows us to do pull requests for development and peer review, and it allows us to utilize Travis CI for automated code quality checks and deployments to Pantheon.

Creating a new repo:

03-github-repo-create

You’ll also probably want to create a new GitHub team, with write access:

04-github-pushers-team

And then add the desired team members to this team, and then associate the team with the repo you just created.

4. Clone Pantheon repo into GitHub

Once the GitHub repo has been created, you can then clone the Pantheon site Git repo and push it into GitHub. First obtain the SSH clone URL:

04-ssh-clone-url

Beware that copying this whole string will amend the Pantheon site name to the end of the string (e.g. “xwp-example”):

ssh://codeserver.dev.d012128e-3991-484c-bc6c-cf0e930d36e8@codeserver.dev.d012128e-3991-484c-bc6c-cf0e930d36e8.drush.in:2222/~/repository.git xwp-example

So on your machine (assuming you have Varying Vagrant Vagrants, VVV), you would clone it you your machine and push it to GitHub via:

cd ~/path/to/vvv/www;
git clone ssh://codeserver.dev.d012128e-3991-484c-bc6c-cf0e930d36e8@codeserver.dev.d012128e-3991-484c-bc6c-cf0e930d36e8.drush.in:2222/~/repository.git example.xwp.co;
cd example.xwp.co;
git remote rename origin pantheon;
git remote add origin https://github.com/xwp/example.xwp.co.git;
git push -uf origin master;

You’ll now the Pantheon site repo mirrored on GitHub, the GitHub repo is the origin remote, and the master branch on the GitHub clone is then set as the remote tracking branch. From now on you normally should just push commits to GitHub and not directly to Pantheon.

It’s also perhaps not a bad idea to encrypt the PANTHEON_UUID environment variable in the .travis.yml.

5. Merge our custom upstream

The Pantheon WordPress upstream isn’t configured for local development in VVV. To get started with that, you can merge our modifications to their upstream:

git pull https://github.com/xwp/pantheon-wordpress-upstream.git master

Once you’ve done this, assuming that your Pantheon site has the slug “actual” and it is located at “actual.com” then you can do a quick search/replace to correct the boilerplate values in our pantheon-wordpress-upstream fork (and given the site UUID as indicated above):

perl -pi -e s/example.com/actual.com/g private/* # Domain
perl -pi -e s/examplecom/actualcom/g private/* # DB creds
perl -pi -e s/example/actual/g private/* .travis.yml # Pantheon slug
perl -pi -e s/123e4567-e89b-12d3-a456-426655440000/d012128e-3991-484c-bc6c-cf0e930d36e8/g private/* .travis.yml

You may want to make some additional changes to these files before completing with a git-commit.

6. Connect Travis CI for code checks

Using a Travis CI Pro account, we can run checks (using wp-dev-lib), do builds, and do deployments from private repos.

To set this up, first go to our Travis CI Pro XWP profile on Travis and re-sync the repos, and then toggle the repo on:

05-travis-enable

Once you have done this, open the .dev-lib file in the root of your repo and make sure that the PATH_INCLUDES variable is reflecting the paths that contain your project’s non-vendor code:

export PATH_INCLUDES='
    wp-config.php
    private/
    wp-content/themes/example-*/
    wp-content/mu-plugins/example-*
    wp-content/plugins/example-*
'

Once this has been done (and you’ve committed and pushed to GitHub), you can now create feature branches on GitHub with pull requests into master, and those pull requests will get Travis builds that runs checks using PHP_CodeSniffer, PHPUnit, JSHint, JSCS, and more.

7. Connect Travis CI for Pantheon deploys

Having the Pantheon repo mirrored on GitHub is great for development and peer review, but it makes it a little annoying for deployments since you have to git push origin master and git push origin pantheon together each time. Well, Travis actually can actually do more than just code quality checks: Travis can also handle deployments. When code is pushed to master on GitHub, Travis will run a build and if the checks pass it can then push the commits to Pantheon automatically for deployment to the dev environment. This being the case, developers don’t even need to have access granted to the Pantheon dashboard for a given site: they only need to be granted push access to the GitHub repo, and their code will only get pushed to Pantheon once it passes the code quality checks.

When you enable Travis on a repo on GitHub, Travis will create an SSH key and add the public key to GitHub as a deploy key which allows Travis to push code to that GitHub repo. What we then need to do is add that same SSH key to a developer account on Pantheon so that Travis can push (and pull) code there.

Create a new Pantheon user account specific to a given site on Pantheon, and add this add this to the Pantheon site as a developer:

06-team-link

07-add-travis-user

Now, you need to create an SSH key pair for the site. Note that previously you could re-use the key that Travis created and access it via the travis CLI tool. Now that the default keys are generated as read-only, you have to generate the key pair locally and then add it it to GitHub as a deploy key with write access.

Next do the same thing for Pantheon. Login to Pantheon as this newly-created Pantheon user, and add the SSH public key to the user account:

08-ssh-key-add

Use the site domain as the comment to help identify which key is for which site.

That’s it. Now you can push a commit to GitHub, and when the build passes Travis will run this line in the .travis.yml file:

if [ $TRAVIS_BRANCH == 'master' ] && [ $TRAVIS_PULL_REQUEST == 'false' ]; then
    git fetch pantheon &&
    git merge -m "Merge changes from pantheon into github" pantheon/master &&    git push origin HEAD:master &&
    git push pantheon HEAD:master;
fi

You can see here that it will do a two-way sync between the repos. If there have been any changes to the Pantheon repo, it will merge those into the GitHub repo and push the merge back to GitHub and Pantheon.

8. Connect Slack

As a bonus, you should connect Slack to your project with the following integrations:

Follow the instructions in Slack. For Travis, make sure that you do not put secret keys directly into the .travis.yml; you will need to secure any sensitive data using encrypted environment variables.


If you find any problems with these instructions or suggestions to make them better, please improve them!

One thought on “Best Practices for Pantheon Project Setup”

Leave a Reply

Your email address will not be published. Required fields are marked *