How do I set up drush aliases for Code Enigma sites?

Drush is the command line tool for Drupal. We describe in a different FAQ how to use Drush on our servers, but another nice feature of Drush is the ability to create "remote aliases", that is to say control your Drupal website on another server from your local computer. In order to make use of Drush remote aliases, you must first install Drush on your computer. (You may also benefit from reading carefully the example aliases document in the Drush project.)

Once Drush is installed, create a new PHP file in one of the supported places for Drush to function for remote aliases, that is:

  • In any path set in $options['alias-path'] in drushrc.php, or (equivalently) any path passed in via --alias-path=... on the command line; or
  • In one of the default locations:
    • /etc/drush
    • $HOME/.drush

We recommend you name your Drush aliases according to the documentation around the GROUPNAME behaviour, as stated:

  • Put groups of aliases into files called GROUPNAME.aliases.drushrc.php 

So, for example, if you're using a Mac you would probably add a file called foo.aliases.drushrc.php in the directory ~/.drush (that is to say the `.drush` directory in your home directory, e.g. /Users/you/.drush) where foo is the name of your Code Enigma hosted project. You may have many environments and sites, you might want to group them, e.g. by sitename.aliases.drushrc.php if you have many sites on one (set of) Code Enigma server(s). Sticking with the foo example for now, and assuming three environments, your alias file contents should look like this:

<?php 
$aliases['master'] = array( 
  'parent' => '@parent', 
  'site' => 'foo', 
  'env' => 'master', 
  'root' => '/var/www/live.foo.master/www', 
  'remote-host' => 'foo-dev1.codeenigma.net', 
  'remote-user' => 'yourusername', 
  'os' => 'Linux', 
); 
$aliases['stage'] = array(
  'parent' => '@parent',
  'site' => 'foo',
  'env' => 'stage',
  'root' => '/var/www/live.foo.stage/www',
  'remote-host' => 'foo-dev1.codeenigma.net',
  'remote-user' => 'yourusername',
  'os' => 'Linux', 
); 
$aliases['prod'] = array(
  'parent' => '@parent',
  'site' => 'foo',
  'env' => 'prod',
  'root' => '/var/www/live.foo.prod/www',
  'remote-host' => 'foo-app1.codeenigma.net',
  'remote-user' => 'yourusername',
  'os' => 'Linux',
  'ssh-options' => '-o PasswordAuthentication=yes', 
);

 

Some important things to note:

  • aliases is a keyed PHP array, note the key name, for example 'prod', matches the 'env' line and also a part of the path under 'root', this is the Git branch name used to deploy that environment;
  • the site name 'foo' matches the middle part of the path under 'root' too, in this case that is the repository shortname, for example if you're using Github for your VCS and your repository is at https://github.com/myorganisation/foo then 'foo' is the correct value, if it were https://github.com/myorganisation/bar then you would use 'bar' under 'site' and also in the path under 'root';
  • 'remote-host' is your Code Enigma server name, notice the 'prod' one is different - this is usually the case, we always recommend different servers for dev versus live (or production, as we usually call it) so this value will vary between environments - often it will be three different servers for the three different environments;
  • 'remote-user' is your Code Enigma username, the same one you use to access ticketing, ownCloud, etc. and it needs to be set up to allow SSH access - if you're not sure, raise a ticket and ask;
  • you'll notice the final 'prod' entry has a line the others do not, 'ssh-options' - this is important, because live servers have an additional factor of authentication, provided by your YubiKey, and if you do not tell Drush to stop and let you enter your YubiKey password your login will fail. Note, you only need this line if the environment is on a server with YubiKey protection enabled.

That's it. Once this file is in place, open a terminal (or a Drush console, if you're using Acquia Dev Desktop on Windows) and type drush sa. You should see something like this:

@foo.master
@foo.stage
@foo.prod

And you can check they work by executing a command like this:

drush @foo.master status

This should return the status of your Drupal website on the server foo-dev1.codeenigma.net.