Streamlining Multi-Site Drupal With Custom Drush Aliases

Running several Drupal sites from a single codebase is a familiar pattern among Australian agencies, university departments, and government portals. Whether you are maintaining separate brand sites for retail clients in Sydney and Melbourne, or managing a network of franchise pages for a chain that operates from Perth to Brisbane, the multi-site architecture keeps the core tidy. The moment you add command-line maintenance to that picture, however, the workflow can become painful without a proper aliasing strategy.

Drush aliases provide short, memorable handles that point to each individual site in the network. They let you run drush @sydney.prod status or drush @brisbane.local updatedb from any directory, replacing long --uri and --root combinations. Once you take the time to author a clean set of custom aliases, daily tasks like clearing caches, running database updates, and pulling down logs feel almost frictionless, regardless of how many Drupal installations are sharing your codebase.

Understanding Drush Aliases in Multi-Site Architecture

A Drush alias is a configuration entry that maps a short string such as @client-prod or @franchise-qld to a specific site within a Drupal installation. In multi-site setups, each subdirectory under sites/ represents a separate website that shares the same core, contributed modules, and themes. Aliases give those directories memorable identifiers, and they can store connection details for remote servers, SSH credentials, and database options in a single file.

The biggest advantage is portability. A developer based in Adelaide working from a café can run the exact same command a colleague in Hobart uses on their workstation, and both will hit the right environment. Aliases also reduce the risk of typos in long path arguments, which is particularly valuable when you are operating against a production cluster that cannot afford a misconfigured request.

Anatomy of an Alias File and File Discovery

Drush reads aliases from drush/sites/ inside your project and from ~/.drush/ in the user's home directory. Files must end in site.yml and contain structured YAML entries. The discovery order matters: project-level files override user-level files, which lets individual teams ship defaults while individual contributors override them locally without touching the shared history.

A typical alias entry looks like this in YAML:

prod:
  uri: https://example.com.au
  host: web1.example.com.au
  user: deploy
  root: /var/www/html/example
  paths:
    drush: /var/www/html/example/vendor/drush/drush/drush

The fields include the public-facing URI, the SSH host and username, the absolute path to the document root on that host, and the path to the Drush binary if it differs from the default. Optional keys cover database connections, command-specific overrides, and path aliases for files and private directories.

Field	Purpose	Required For
uri	Sets the site URL Drush passes to Drupal	Local and remote
host	SSH target for remote execution	Remote aliases
user	SSH username used during remote calls	Remote aliases
root	Absolute filesystem path to the Drupal root	All aliases
paths.drush	Path to the Drush binary on the remote host	Remote aliases
db-url	Direct database connection string	Optional but common
command-specific	Overrides for rsync, sql, and other subcommands	Optional

When you save the file, you can confirm the configuration with drush site:alias @example and verify that Drush recognises the new alias. Files placed in the project repository ensure that every team member sees the same shorthand, while personal tweaks go into ~/.drush/ so they never leak into shared history.

Configuring Local Aliases for Shared Drupal Codebases

For a local development environment, the simplest alias points to a directory under sites/ on the developer's machine. Suppose the agency in Melbourne has a single checkout of Drupal core that serves six client sites; each site lives under web/sites/client1.com.au, web/sites/client2.com.au, and so on. A local aliases file in drush/sites/local.site.yml might define @melbourne.client1, @melbourne.client2, and similar entries with no host key, just uri and root.

It is also worth adding group aliases that act as wildcards. A group entry lists multiple child aliases under a single key, so commands like drush @melbourne.local status will iterate through every site in the group. This is useful when you are running security updates and want to clear each cache store individually, or when running database updates across a network of marketing sites without typing each alias by hand.

Connecting Remote Environments Across Australian Regions

Remote aliases add host, user, and root fields that Drush uses to open an SSH session before issuing commands. Many Australian agencies host primary infrastructure in Sydney with a failover in Melbourne, and the alias file can describe both. Staging environments often live on separate hosts entirely, so each stage should have its own entry, for instance @sydney.staging and @sydney.prod, to prevent accidental commands against the wrong tier.

Because data sovereignty matters under the Australian Privacy Principles, your aliases can be configured to keep dumps within regional boundaries. You can set the paths.drupal and db-url keys explicitly so that database snapshots stay on the local file system of the remote host rather than being streamed to the operator's laptop in another city. Combined with SSH keys and an IdentityFile reference, this reduces the risk of customer data crossing borders unnecessarily during routine maintenance.

When you are working with managed hosting providers such as Digital Pacific, VentraIP, or Panthur, the host value is usually a shared IP or hostname, and the root path follows the provider's standard layout. Always check whether the host uses www-data or a custom PHP user, and align your paths.php and paths.drush keys accordingly so commands like drush @sydney.prod cache:rebuild complete on the first attempt.

Working With Aliases in Day-to-Day Commands

Once the aliases are in place, the command surface becomes remarkably uniform. You will likely find yourself reaching for a small core of commands over and over: drush @alias status, drush @alias updatedb, drush @alias config:import, and drush @alias sql:dump --result-file=.... Each of these respects the alias transparently and prints consistent output regardless of whether the target is local or remote.

There are a few pattern-specific tricks worth memorising. The --target flag on commands such as sql:sync selects which site in a group should be the source or destination, which is helpful when you are copying a single franchise site from production back to a developer's laptop in Adelaide. The drush site:alias --format=json output can be piped into shell scripts for batch operations, and the drush watchdog:show @alias command works the same way as the local version but reads logs from the remote server.

Alias Management Practices for Distributed Teams

For a team spread across Australian capital cities, alias files need a clear home and a clear review process. Most teams commit them to the project repository under drush/sites/, with environment-specific files named according to a convention such as prod.site.yml, staging.site.yml, and local.site.yml. Sensitive values like SSH users and database passwords belong in environment variables or a secrets manager, not in the committed YAML, so consider referencing vault:// paths or shell expansions inside the alias file.

When onboarding a new developer, sharing the alias file along with the SSH config and a short README is usually enough to get them productive in a few hours. A few practical rules keep things tidy:

Naming and structure choices:

• Commit shared alias templates, but never commit credentials; use placeholders or environment lookups.
• Name aliases by site and environment, for example @client-com-prod and @client-com-stage.
• Group sites that share maintenance windows so batch commands stay predictable.

Review and documentation habits:

• Document any provider-specific quirks, such as custom Drush paths, PHP versions, or file ownership, directly in the alias file as comments.
• Re-validate aliases after each deployment or infrastructure change.
• Run a weekly sanity script that lints the YAML and tests SSH reachability from a host inside Australia to keep the latency low.

Maintaining aliases also means periodic housekeeping. Each time you upgrade Drush or move a site to a new host, the corresponding alias file needs an update. A lightweight script in the repository can confirm each host responds to a quick SSH handshake and warn about any aliases whose root path no longer matches the actual deployment layout.

Troubleshooting and Maintaining Custom Aliases

The most common issue developers in Australia encounter is a host key warning or a path mismatch after a server migration. When drush @sydney.prod status returns ssh: Could not resolve hostname, the first thing to check is whether the host value still resolves from your network, especially if you are working from a coffee shop on the NBN and the DNS resolver used by your VPN differs from the one used by your local ISP. The second thing is the root path: many managed hosts reorganise the document root between platform upgrades, and a stale path will silently fail.

Another frequent problem is a PHP version mismatch. If the remote host runs PHP 8.3 but the local alias file still points at a Drush binary that expects 8.1, you will see obscure errors. Adding paths.php and a php-version key clarifies the situation, and Drush will switch interpreters automatically. Always verify aliases after a site rename or a domain change, since the uri field often gets overlooked, which then breaks link generation and trusted host patterns.

A good habit is to keep the project README and the alias file in sync. When the alias for @brisbane.prod changes its root, the README example should change too, otherwise new contributors will follow outdated instructions. Treat the alias configuration as part of the deployment pipeline, version it alongside the codebase, and review it whenever the infrastructure changes. Once the file is in good shape, you will rarely think about it again, and that is exactly the goal of a well-built multi-site Drupal setup.