Adapting to the Acquia Cloud API

As Drupal developers, we can all recall the first time we felt the soft caress of Drush on our terminal.

It’s a truly life-changing experience to discover the depth of interaction Drush creates outside of the Drupal UI. Soon after mastering the Drush API, a craving for something more is satisfied through a first encounter with remote aliases. Sparks fly as features are reverted remotely, databases are synced between environments and users are created on a dev site--all from a local bash environment.

At Elevated Third our Drupal development team has moved past the honeymoon phase with Drush, our one true love, and fallen into a daily routine of efficient CLI interaction with Drupal. Just when we thought the spark was gone, we discovered the Acquia Cloud API for Drush and the relationship felt new all over again. *Disclaimer: the Acquia Cloud API requires an Acquia hosting account, check out their site to see if they have something to suit your needs.*

To start, Acquia takes all of the setup time out of working with Drush aliases. When you log in to the Acquia Panel, SSH keys and remote aliases can be managed per hosting account (rather than per site), just visit the credentials page of your profile. There’s a section dedicated to Drush integration where you can download a tarball of all your Drush aliases and copy/paste a quick CLI command that will install everything required to your $HOME path.

Basically, all this command does is untar what you’ve just downloaded in your user’s home directory (assuming that’s what $HOME is on your system). You’ll notice a .acquia directory and some additions to your .drush directory if this executed correctly. Remote aliases should now exist on your local machine (in $HOME/.drush) for everything you have access to in your Acquia Cloud environment. On top of that, there should also be a file named acapi.drush.inc in $HOME/.drush, which contains all of the functions provided by the Acquia Cloud API. Take a few minutes to dig in and really get familiar with the new functions provided by this file, you can either check out the file iteself, the online reference or just run *drush help* and filter by what’s available through the Cloud API, like so:

 drush help --filter=acapi

With everything available through this API, you’ll be able to deploy code across environments, manage databases, purge a domain from the Varnish cache and even add/delete SSH keys, just about anything you’d want to do through the Acquia account UI. I won’t go through what the individual commands do because there are already plenty of great references, a few of which I mentioned above. However, I’d like to specifically call out one command that’s incredibly useful and required a couple config changes for us:

 drush acquia-update

When run, this will automatically refresh all of the Drush aliases on your local machine, which is fantastic. However, if you poke around in those aliases a little bit you’ll see that they very clearly warn against modification because any changes will be overwritten every time acquia-update runs. Prior to this setup, we were (and still are for non-Acquia sites) committing our remote aliases in a drush directory in the repo root. Up to this point, we kept all of our local aliases in $HOME/.drush/local.aliases.drushrc.php and referenced them from the aliases file that was committed as part of each repo to ensure the alias for every environment could be access with the *@site_name.env* syntax.

$aliases['local'] = array( 'parent' => '@local.kiosk', );

This created a problem with the new Acquia setup because those parent declarations would be overwritten every time *acquia-update* ran, therefore rendering *@site_name.local* useless. Turns out there’s a really simple solution to this, pointed out to me by Peter. Rather than keep all local aliases in local.aliases.drushrc.php, they can be stored in aliases.drushrc.php, which allows you to declare the full path of the alias as part of it’s definition. This is what my new aliases.drushrc.php looks like with one alias added:

array( 'sql-sync' => array( 'no-cache' => TRUE, ), ), ); 
$aliases['elevated_third.local'] = array ( 'root' => '/Users/nickswitzer/Sites/e3/docroot', 'uri' => 'http://e3.local', 'path-aliases' => array ( '%drush' => '/usr/local/share/drush', '%site' => 'sites/default/', '%files' => 'sites/default/files', '%dump' => '/Users/nickswitzer/tmp/e3-sql-sync.sql', ), ); 

What really works well about this setup is that it’s backwards compatible with our Drush configuration for non-Acquia hosted sites, but flexible enough to allow us to consistently configure Drush across remote and local environments regardless of the hosting platform we’re interacting with. There will always be more efficient ways to do things, which is why we continue to push our relationship with Drush. It allows us to optimize tasks that can be repetitive and slow through the Drupal UI and focus on delivering quality code and reliable deployments every time.