BLT

Multisite

Note

Acquia will end support for BLT on December 31, 2024. For more information on how to replace your BLT implementation with updated functionality, see You don’t need BLT on Acquia Cloud.

Configuring a multisite instance on BLT involves two parts: the local configuration and the Cloud Platform configuration.

Local configuration

  1. Set up a single website on BLT, following the standard instructions, and ssh to the vm (vagrant ssh).

  2. Run blt recipes:multisite:init. It’s suggested to use an easy machine name (rather than a domain name) for your website for maximum compatibility with other BLT features.

    Running blt recipes:multisite:initperforms the following:

    • Sets up new a directory in your docroot/sites directory with the multisite name given with all the necessary files and subdirectories.

    • Sets up a new drush alias.

    • Sets up a new vhost in the box/config.yml file.

    • Sets up a new MySQL user in the box/config.yml file.

    Some manual configuration is still required using the following steps.

  3. Set the new website’s local database credentials in the docroot/sites/{newsite}/settings/local.settings.php file to ensure your new website connects to the correct database.

  4. Copy the example.sites.php file from Drupal core, rename it to sites.php, and add entries for your new website.

  5. If applicable, override any BLT settings in the docroot/sites/{newsite}/blt.yml file.

  6. Once you’ve completed the above and any relevant manual steps, exit out of your virtual machine environment and update with the new configuration using vagrant provision.

(Optional) local configuration steps

Add a multisite array

You have the option to explicitly define your multisites in blt/blt.yml by creating a multisites array. If you don’t manually define this variable, BLT will set it based on discovered multisite directories:

multisites:
  - default
  - example

At this point, you should have a functional multisite codebase you can install on Cloud Platform.

Override BLT variables

You may override BLT variables on a per-website basis by editing the blt.yml file in docroot/sites/{newsite}/. You may then run BLT with the site variable set at the command line to load the website’s properties.

For instance, if the drush aliases for your website in docroot/sites/mysite where @mysite.local and @mysite.test, you can define the aliases in docroot/sites/mysite/blt.yml as:

drush:
  aliases:
    local: mysite.local
    remote: mysite.test

Then, to refresh your local website, you can run: blt drupal:sync --site=mysite.

Behat configuration

If you want to use a Behat profile other than local.yaml for each website, you can override the configuration source file and profile values in docroot/sites/mysite/blt.yml:

behat:
  tags: mysite
  # When tests:behat:run target is executed, this Behat profile will be used.
  # @see tests/behat/example.local.yml for Behat profile definition.
  profile: mysite
  config: /app/tests/behat/mysite.behat.yml

Using the example configuration, a functional mysite.behat.yml file must exist at app/tests/behat/ and must include correct configuration for a mysite profile. Using tags and profiles enables more granular configuration of Behat suites, contexts, and extensions per multisite.

Running the following command would then trigger Behat to use the mysite configuration and profile: blt tets:behat:run --site=mysite.

Cloud Platform configuration

Start by following the About Drupal multisite installations to configure your codebase for Cloud Platform. These instructions should walk you through:

  1. Creating a new database in Cloud Platform.

  2. Adding the website-specific settings include to each website’s settings.php file. In the settings.php for your multisite, add the require statement for your multisite database credentials before the require statement for blt.settings.php, for example:

    if (file_exists('/var/www/site-php')) {
   require '/var/www/site-php/mysite/multisitename-settings.inc';
}

require DRUPAL_ROOT . "/../vendor/acquia/blt/settings/blt.settings.php";

Drush aliases

The default Drush website aliases provided by Acquia Cloud and Club aren’t currently multisite-aware. They will connect to the first (“default”) website / database on the subscription by default. You must create your own Drush aliases for each website.

Acquia recommends copying the aliases file provided by Cloud Platform or Club to create a separate aliases file for each website. Change the uri and parent keys for the aliases within each file to match the correct database or website.