Configuring a multisite instance on BLT involves two parts: the local configuration and the Cloud Platform configuration.
Local configuration
- Set up a single website on BLT, following the standard instructions, and ssh to the vm (
vagrant ssh
). 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:init
performs 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 thebox/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.
- Sets up new a directory in your
- 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. - Copy the
example.sites.php
file from Drupal core, rename it tosites.php
, and add entries for your new website. - If applicable, override any BLT settings in the
docroot/sites/{newsite}/blt.yml
file. - 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:
- Creating a new database in Cloud Platform.
Adding the website-specific settings include to each website’s
settings.php
file. In thesettings.php
for your multisite, add therequire
statement for your multisite database credentials before therequire
statement forblt.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.