Drush Alias files for shared hosts

Wed, 07/22/2015 - 05:13

Once you have Drush up and running on your host, you will want to create an aliases file so you can use it properly and easily.  An aliases file simply defines an alias for the site to which you want to connect, so Drush knows the paths and database settings necessary to bootstrap the site.

Creating the aliases file

The first thing to do is to create the aliases file or copy and edit and existing file on your local environment.  There are multiple places where the file could be located so Drush can find it (these are listed in the default aliases.drushrc.php file):

  1. In any path set in $options['alias-path'] in drushrc.php,
           or (equivalently) any path passed in via --alias-path=...
           on the command line.

  2. In one of the default locations:

    • /etc/drush

    • $HOME/.drush (recommended)

    • The sites/all/drush folder for the current Drupal site

  3.  Inside the sites folder of any bootstrapped Drupal site,
     or any local Drupal site indicated by an alias used as
     a parameter to a command

It is good practice to name the aliases file according to the site to which it applies, so something like mysite.aliases.drushrc.php would be good (it does need to follow the convention of ALIASNAME.aliases.drushrc.php.)  The aliases file should then define an alias for each of your environments (local, dev, staging, and production) so that it looks something like this:

<?php
/**
 * Alias file, to be placed in your ~/.drush directory or the aliases
 * directory of your local Drush home. Once it's in place, clear drush cache:
 *
 * drush cc drush
 *
 * To see all your available aliases:
 *
 * drush sa
 *
 * See http://helpdesk.getpantheon.com/customer/portal/articles/411388 for details.
 */

// A Small Orange aliases:
$aliases['dev-site'] = array(
    'uri' => 'dev.domain.com',
    'root' => '/home/username/public_html/dev',
    'remote-host' => 'domain.com',
    'remote-user' => 'username',    'path-aliases' => array(
      '%drush' => '/home/lowgravi/.composer/vendor/bin',
    ),
);

$aliases['stg-site'] = array(
    'uri' => 'staging.domain.com',
    'root' => '/home/username/public_html/staging',
    'remote-host' => 'domain.com',
    'remote-user' => 'username',
    'path-aliases' => array(
      '%drush' => '/home/lowgravi/.composer/vendor/bin',
    ),
);

$aliases['prod-site'] = array(
    'uri' => 'www.domain.com',
    'root' => '/home/username/public_html',
    'remote-host' => 'domain.com',
    'remote-user' => 'username',
    'path-aliases' => array(
      '%drush' => '/home/lowgravi/.composer/vendor/bin',
    ),
);

// Local data
$aliases['loc-site'] = array(
  'root' => '/var/www/d7.mysite',
  'path-aliases' => array(
    '%dump-dir' => '/home/username/drush-sql-dumps',
  ),
);

A few notes about the above code:

  • The alias (e.g. dev-site) can be anything, so pick something that is relavant to your site (it does need to be unique across all of your aliases files.)
  • The URI should be modified to suit your site.
  • The root is the location of the code for that environment
  • The remote host is the host on the server, and can be the same for dev, staging, and production.
  • Remote user is the name the host provided you when you created your account.
  • %drush defines the location of Drush on the remote server.  This shouldn't be necessary, but I was unable to get it to work otherwise.
  • %dump-dir is used for local database dumps when syncing the database.  If you don't have this directory on your development machine yet, you should create it and give drush permission to write to it.

Once you have edited the aliases file, you'll need to clear the drush cache to it can pick up the new aliases:

drush cc drush

You can then verify if the aliases are being noticed by Drush by entering

drush sa

(This will print every alias that Drush knows about on your system.)  If you created a file specifically for your site (i.e. mysite.aliases.drushrc.php) then the aliases will probably be namespaced as mysite.dev-site, mysite.stg-site, etc.  This is good for when you have multiple sites with the same alias (you could just use 'dev' for an alias) but if they are unique, you can also just use dev-site, omitting the namespace.

To check whether Drush can bootstrap the site, you can check its status:

drush @loc-site status

(It should tell you if the bootstrap was successful.)  You can also check the status on the remote sites as well (your settings.php files will need to be in place first, so Drush can get the appropriate database settings.)

Tags
hosting
drupal
drush