Easier Site Deployments on Pantheon with Terminus

Pantheon is a high-octane hosting company for Drupal and WordPress websites, and Terminus is their command line toolkit for interacting with the platform. It's basically a command-line version of their dashboard website (i.e their control panel). It's been around for quite a while, and I've had it installed for years, but only recently started actively using it. I have a couple clients of my own, and a few for whom I do subcontracting work, that use Pantheon, so I've had reason to get a little more proficient with Terminus lately.

If you're asking "why the frig would I want to use the command line when I can use a nice-looking web UI?", the answer for me is speed and configurability. With the Pantheon's dashboard, which is quite nice, you have to load each tab you're interested in, click the right buttons in the right order, and so forth. With Terminus, you can write a single command, or a series of commands in a basic shell script, that's easy to recall and run to do exactly the tasks you do often that the dashboard doesn't directly support. It's the same reason most savvy Drupal developers use Drush, and why WP-CLI is becoming increasingly popular in the WordPress world. Pantheon hosts both Drupal and WordPress sites, and most of its commands work no matter which you're using on any given site.

One really simple use case is deploying code from Dev to Test to Production, which is one task Pantheon newbies tend to find frustrating. The idea, of course, is to prevent dumb mistakes that can cause your site to blow up. If you run an even somewhat popular site, that's completely unacceptable, so I think enforcing that discipline through their workflow is a feature to be embraced, not an annoyance to cope with. That said, deploying is faster and more convenient with Terminus, and I appreciate that very much. Here's how I do it.

In order to use Terminus (after you've installed it of course), you need to log in, and the easiest way to do that on the command line is with Machine Tokens. You can also log in with your username and password when you start a Terminus session, but a machine token encapsulates your username and password in a single unit, so there's less to type, and they're revokable independent of your username and password, so leaving them in a script file doesn't feel as dangerous. So I recommend creating a Machine Token for your Pantheon account, which as of this writing needs to be done via the dashboard in a browser.

I have a little shell script called terminauth that logs me into a couple Pantheon accounts based on the arguments I pass it. terminauth by itself logs out of Pantheon so I always start fresh, then logs me into my default account that I use most. I can then invoke it later as terminauth account2 to log in as a second account.

Here's the function, which is written for my current favorite shell, fish (and is therefore Python, and relatively easy to read!):

function terminauth
    terminus auth logout
    if count $argv >/dev/null
        # have arguments - take some action
        switch $argv
            case account1
                # log in as account1
                terminus auth login --machine-token=1111111ZZZZZZZZZZZ
            case logout
                # just stay logged out
            case '*'
                # log in as default account
                terminus auth login --machine-token=999999999XXXXXXXXX
        # no arguments - log in as default account
        terminus auth login --machine-token=999999999XXXXXXXXX

Save that as terminauth in your ~/.config/fish/functions folder, and edit to taste. Even if you don't know Python, what the script is doing is probably clear enough to be translated to bash or your favorite shell.

Once you're logged in, you can use terminus sites list to see a list that looks something like this:

| Name            | ID       | Service Level | Framework | Own...
| site-one        | 12345678-| pro           | drupal    | 
| site-two        | 12345678-| pro           | drupal    | 
| site-three      | 12345678-| pro           | wordpress | 

The Name column contains the site names you'll want to use for most Terminus commands. Now that you have the site name, you can deploy your code from the Dev to Test environment with the site deploy command.

% terminus site deploy --site=SITENAME --env=test

Terminus will prompt you for a message to log with the deployment, which is especially nice when you're deploying a bunch of commits at once to help remember what they're all for. You can also leave it blank, and Terminus will use its default message (currently Deploy from Terminus 2.0).

If you want to pull your files and database from the live environment into the test environment so you can test with everything ready to go, add a couple options. sync-content pulls in the database and files, and cc will clear the caches on the site. On Drupal sites, there might still be particular caches you'll need to clear manually depending on what's in your updates, but it's nice to have.

% terminus site deploy --site=SITENAME --env=test --sync-content --cc

When it's time to push to live, just run the same command on the live environment. I often clear the cache here as well.

% terminus site deploy --site=SITENAME --env=live --cc

There's a lot more that Terminus can do, even in the simple case of deploying your site from environment to environment, so it's always a good idea to look at the help for each command. You can get help for each level of subcommands in Terminus. In other words, any of these will give you useful information:

% terminus help gives you help on Terminus generally, including all its main subcommands.

% terminus help site will list the help, subcommands, and options of the site subcommand.

% terminus help site deploy will do the same thing for the site deploy subcommand.

Note: the documentation for the site deploy subcommand might make it seem like you can skip test and go straight to live, but don't be fooled: the platform still enforces its workflow!

Pantheon is quite nice for running a high-traffic Drupal or WordPress site, and if you've never tried it, there's a free tier that lets you easily spin up a couple instances of Drupal, WordPress, or even Backdrop. It's totally worth looking at, and if you use Pantheon regularly, definitely give Terminus a try.

Comments are closed on this post to keep spammers at bay. If you want to chime in, please email or send a tweet.