Drush aliases set up

This page is out of date and needs reviewing.

Who is this guide for?

This guide is for developers setting up Drush aliases on new or existing projects.

Set up Drush aliases on a new or on existing D8 projects

There should already be a [project root]/drush directory. If there isn't then one needs to be created. Aliases will be defined in [project root]/drush/sites. From the git root, make the directories needed:

mkdir -p drush/sites

You will need two alias files stored in [project root]/drush/sites/:

  1. A remote.site.yml file
  2. A server.site.yml file

Boilerplates for these can be obtained with:

curl -o drush/sites/remote.site.yml https://gitlab.agile.coop/agile-public/lando/raw/master/d8/remote.site.yml;
curl -o drush/sites/server.site.yml https://gitlab.agile.coop/agile-public/lando/raw/master/d8/server.site.yml

File: remote.site.yml

The remote.site.yml file will contain the configuration for drush to understand how to connect to the sites on a remote server. This will look like the following example:

stage:
  host: projectname.org
  root: /var/www/stage.projectname.com/gitroot/web/
  uri: default
  user: ${env.USER}

prod:
  host: projectname.org
  root: /var/www/production.projectname.com/gitroot/web/
  uri: default
  user: ${env.USER}

Change the host and root directives to suit the server and site you are working with.

The value for the user key is making use of the global Lando environment variable called USER which we previously set in ~/.lando/config.yml. Without this, ssh based commands run from within a container are unaware of the host's user name and therefore cannot correctly access a remote server, even though keys are forwarded.

File: server.site.yml

The server.site.yml file is used for any commands that need to be issued on the server. For example, if you are ssh'd in to the remote server and want to clone the prod database to the stage site (drush sql-sync @server.prod @server.stage ) you can use this alias to do it.

The server.site.yml will look like the following example:

stage:
  root: /var/www/stage.projectname.com/gitroot/web/
  uri: default

prod:
  root: /var/www/production.projectname.com/gitroot/web/
  uri: default

Change the value for the root key to the correct path on the server.

Servers which are restricted by IP address

Some servers have a restriction to only allow users to ssh in if they are doing so from a specific IP address. To get around this restriction we usually use the gateway server and proxy our commands through it.

You can still run remote drush commands on servers locked down by IP address by adding some config to the container's .ssh/config file. This can easily and automatically be done by adding something like the following to the appserver config in the .lando.yml file (changing creativeml.ox.ac.uk to match whatever you have declared as the host in the remote.site.yml file):

services:
  appserver:
    run: >
      echo "Host projectname.com\n
      User $USER\n
      Hostname      www.projectname.com\n
      ProxyCommand  ssh $USER@gateway.agile.coop nc %h %p 2> /dev/null" >  ~/.ssh/config

This will allow you to run commands proxied through the gateway server.

Using Drush aliases

For information on how to use Drush aliases please read the Using Drush aliases documentation.

Last updated: