Last updated December 11, 2018

Drush commands are commonly run in the Drupal docroot, the directory where Drupal's files live. This is a relatively simple task on your local development environment. But if you're working on multiple sites and each of those sites has one or more remote environments that you connect to via SSH, workflows quickly become complicated. Creating and using Drush site aliases allow you to run Drush commands on any site, local or remote, that you have credentials to access, from any location on your computer that has access to a Drush executable.

By the end of this tutorial, you should understand how Drush site aliases work, how to create Drush site aliases, and how to use them in a Drush command.

Goal

Create a Drush site aliases file with credentials for a local and live instances of a site and use the alias to run a Drush command on both environments.

Prerequisites

  • Drupal site installed and running in 2 places, for example, on your local computer and a live hosted site. To learn how to install Drupal, see Chapter 3 of the Drupal 8 User Guide and to learn how to set up a local development site see 11.8. Making a Development Site, also in the Drupal 8 User Guide.
  • Drush is installed as a site dependency using Composer, so you will need Composer installed on your local machine if you haven't already.
  • This also assumes that you are using Composer to manage your Drupal site dependencies. See our Introduction to Composer for Drupal Users if needed.
  • Drush installed. (To install Drush as a site dependency (preferred) run composer require drush/drush, assuming you have already set up Composer to manage your project's dependencies.)
  • You will need to know the SSH credentials to connect to your remote (live) site if you want to set up a Drush site alias for it. To learn more about SSH, watch Using SSH and SCP.

How Drush connects to a site

When using Drush, you may have noticed that most tutorials first suggest using the cd command to change to the directory containing your Drupal site, i.e. the docroot, which could be named anything, but some common examples are web, docroot, public_html, or www. You execute the drush command within the Drupal docroot. The reason for this is that Drush uses several checks to determine how to connect to a Drupal site:

  • Is the current directory a Drupal docroot?
  • Is the current directory a subdirectory of the Drupal docroot?
  • ...and several more checks.

Many of these checks are easy to satisfy when working with a Drupal site on your laptop or local workstation. Often, you'll change to the Drupal docroot directory or a subdirectory naturally anyways. This reduces the need to use something like the --root switch to specify where the Drupal docroot is located.

The sitation becomes more complicated when trying to use Drush to manage a remote Drupal site. This can be a shared environment like a stage, test, or QA server, or the production site which serves traffic to end users. In that case, you need to specify a lot of additional information. Instead of taking a huge list of switches, we can configure Drush site aliases to instruct Drush how to connect to the remote site.

A Drush site alias, or its shorthand, alias, refers to a particular Drupal site. While the site can be local, often it's used to connect to a remote Drupal site via secure shell, or SSH.

What is a site alias?

An alias is a collection of options which is customarily used to define short names for local or remote Drupal site-installs. A site alias always refers to an environment, such as "dev", "qa", or "live". Drush considers dev the default environment.

A site alias comprises two elements: the site name (derived from the site alias file name) and the environment alias (the top-level keys of the array defined in the site alias file).

The site alias file

A Drush 9 site alias file has the following naming convention:

example.site.yml

The first part of the filename, in this case, example, identifies the site alias name. The .site.yml suffix identifies the file as a Drush site aliases file, as long as it is saved in a Drush-discoverable location (more on that below).

Inside example.site.yml, top-level YAML array keys identify the various environments for this site, for example, dev, staging, prod.

Once we have set up a Drush site alias file, we will be able use Drush to connect to a site and environment using its alias and run a Drush command on that site-environment, for exmaple:

drush @example.prod cache-rebuild

Which would run drush cache-rebuild on "example's" live site ("prod").

Drush-discoverable locations

Drush will search for alias files (example.site.yml) in the following locations:

  1. (Preferred) A example.site.yml file in /drush/sites in the Drupal docroot, e.g. PROJECTROOT/DRUPALROOT/drush/sites/example.site.yml.
  2. (Preferred) A example.site.yml file in /drush/sites one directory level above the Drupal docroot, e.g. PROJECTROOT/drush/sites/example.site.yml.
  3. In any path set in drush.alias-path (in the array drush with the key alias-path) in a drush.yml configuration file. This tells Drush where to find the site alias file(s), if they're not in a default discoverable location.
  4. In any path passed via the switch, --alias-path on the command line.

Note: Drush 9 will not search recursively in the above locations. Alias files should be placed directly in one of the listed locations.

Groups of aliases

If you would like to organize your site aliases into one or more groups, then create a directory in a site alias discoverable location with the name of the group. For example, let's say you manage several sites for a particular client. You could name the group after the client and then place the various site alias files within that directory. For example:

docroot # Drupal files and directories
  +-- drush
      +-- drush.yml # optional, see step 1 above
      +-- sites
          +-- icecream # Name of group
                +-- vanilla.site.yml # Drush site alias file
                +-- chocolate.site.yml # Drush site alias file
                +-- strawberry.site.yml # Drush site alias file

You could then target the site "vanilla" within the group "icecream" as follows:

drush @icecream.vanilla.dev

The built-in "self" alias

If you've used the Drupal Composer template, you may have noticed a file called self.site.yml in PROJECTROOT/drush/sites. Drush treats a self.site.yml file saved in either the project root's or docroot's drush/sites directory in a special manner. If your current working directory is the project or Drupal root, you can refer to your alias by just the environment key, for example:

cd PATH/TO/PROJECT
drush @live cache-rebuild

Assuming that the self.site.yml contained a key, live, with SSH credentials to a Drupal site, this command would rebuild the cache on that site instance.

The take-away here is that if you're using a shorthand alias with only the environment key, Drush will look for a self.site.yml in a Drush-discoverable location in the project or docroot for the environment key and connection credentials.

Convert a legacy alias file

The example.site.yml file naming convention and file type are both new to Drush 9. To convert legacy alias (*.aliases.drushrc.php) to YAML, run drush site:alias-convert. See drush site:alias-convert documentation for details and options.

Create a Drush alias file

Now that you're familiar with the concepts, let's walk through the process of creating a Drush alias file. This is a fairly generic walk-though. Use the information explained earlier in the tutorial to customize the file, its location, and its name to meet your use-case.

Create an empty file to use for Drush aliases

Create an empty Drush alias file (example.site.yml) in a Drush-discoverable location.

Example 1: drush/sites in the Drupal docroot.

docroot # Drupal files and directories
  +-- drush
      +-- drush.yml # optional, see step 1 above
      +-- sites
          +-- example.site.yml # Drush site alias file
... # Other Drupal files and directories

Example 2: drush/sites in the project root, one level above the Drupal docroot.

docroot # Drupal files and directories
drush
+-- drush.yml # optional, see step 1 above
+-- sites
    +-- example.site.yml # Drush site alias file
... # Other project files and directories

Add site information to alias file

You can add information about different instances or environments of your site in the example.site.yml file. For example, the following defines two aliases, prod and stage:

example.site.yml:

prod:
  host: prod.domain.com
  user: www-admin
  root: /path/to/drupal
  uri: http://www.example.com

stage:
  host: stage.domain.com
  user: www-admin
  root: /path/to/drupal
  uri: http://stage.example.com

Example derived from Drupal Composer project's drush/sites/self.site.yml.

The above defines two aliases, prod and stage, with the following information:

  • host: The hostname to use when connecting over SSH. Note that this can be different than the site's URI!
  • user: The remote username that can connect to the host over SSH
  • root: The path on the remote server to our site's docroot
  • uri: The URL of the site we're managing.

(Optional) Create a Drush configuration file

If you want to save your alias file in a location other than a default discoverable location, such as PROJECTROOT/drush/sites or DRUPALROOT/drush/sites, you will first need to set up a Drush configuration file and specify the directory location of the site alias file(s) in the drush.alias-path key of your drush.yml configuration file.

Follow the instructions in example.drush.yml under "Directories and Discovery" to create a drush.yml file in a Drush-discoverable location of your choice.

Drush site aliases documentation

You can get basic help and command examples for Drush 9 site aliases with the following command:

drush help site:alias

Or for more detailed documentation, use the Drush 9 command:

drush topic docs:aliases

Which information is also contained in example.site.yml hosted in the drush-ops/drush repository.

Recap

In this tutorial we learned what Drush site aliases are and how to add a site alias configuration file to our project or Drupal root's drush/sites directory. Our example site aliases file contained a collection of settings related to specific environments of our site, including the information required to connect to the site via SSH.

Further your understanding

  • Set up a site aliases file for a site you are currently working on.
  • Learn how to set up and use the config-pull subcommand to download configuration from a remote site. See Live vs. Local Configuration Management.

Additional resources