How to Setup Multisite on ACE with Acquia BLT (with optional Pipelines and Config Split)

    See more
    • Updated

    For instructions on how to setup multisite without BLT, please see How to add a new site to a multisite on Acquia Cloud Professional or Enterprise without Acquia BLT

    This setup assumes the use of

    • Vagrant on OSX
    • Drupal 8
    • Drush 10

    Run the initial command

    Acquia BLT provides a recipe for simplifying the process:

    blt recipes:multisite:init

    (see https://docs.acquia.com/blt/tech-architect/multisite/)

    • Enter machine name: Ex. site2
    • Enter the local domain: Ex. local.site2.com
    • Configure database creds
      • Db name: Ex. drupal_site2
      • Db user: Ex. drupal
      • Db password: Ex. drupal
      • Do not change the Db host: localhost and Port: 3306
    • Accept changes to config.yml file

    Default drush alias: @site2.local

    Set the stage

    drupal:
  db:
    database: DB name
    username: drupal
    password: drupal
    host: localhost
    port: 3306
    • Since you are updating this file, fix the drush.aliases if needed.
    local: self
remote: [sitename].[env]
    • Delete the local.settings.php from the settings folder for the multisite and then regenerate the local.settings.php file with the multisite’s DB connection info.
    use Drupal\Component\Assertion\Handle;

global $_acsf_site_name;
$db_name = 'drupal_DB_NAME';
if (isset($_acsf_site_name)) {
  $db_name .= '_' . $_acsf_site_name;
}

/**
 * Database configuration.
 */
$databases = [
  'default' =>
  [
    'default' =>
    [
      'database' => $db_name,
      'username' => 'drupal',
      'password' => 'drupal',
      'host' => 'localhost',
      'port' => '3306',
      'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
      'driver' => 'mysql',
      'prefix' => '',
    ],
  ],
];

     

    Fix the configuration for the Virtual Machine and install

    • blt blt:init:settings
    • Edit box/config.yml and fix the mysql_user.

      Original:
     name: username
   host: '%'
   password: userpasswd
   priv: 'dbname*:ALL'

          It should look like:       

    name: username
  host: '%'
  password: userpasswd
  priv: 'drupal%*:ALL'
    • Exit the Virtual machine and re-provision it. 
      • vagrant reload --provision
        ​​​​​​​vagrant ssh
    • Install the site locally. 
      • blt setup --site=site2
    • Make sure the site is working, from outside the vagrant (in the project folder) run: 
      • drush @site2.local uli

     

    General fixes to the configuration

    • Modify docroot/sites/sites.php to include the domains for the new multisite, including the domains that live in the Acquia Cloud: 
      $sites['local.site2.com'] = 'site2';
$sites['dev.site2.com'] = 'site2';
$sites['stage.site2.com'] = 'site2';
$sites['site2.com'] = 'site2';
    • Adjust the uri parameter in sites/[sitename]/local.drush.yml to match the site name.
    • In Acquia cloud, create the DBs and copy the configuration for PHP to your docroot/sites/site2/settings.php before the BLT settings file include. Assuming you named the DB drupal_site2 in the Acquia cloud, it should look like:
    if (file_exists('/var/www/site-php')) {
  require '/var/www/site-php/SubscriptionName/drupal_site2-settings.inc';
}
    • Note: If using BLT 11 and the site's name is the same as the new DB, this step is not required.

     

    Acquia Cloud drush aliases for the multisite

    • Update the site specific drush aliases file with Acquia cloud info. Edit drush/sites/[sitename].site.yml and make sure it looks like (if your Acquia docroot is myproject):
    local:
    root: /var/www/myproject/docroot
    uri: 'http://local.site2.com'
    host: local.site2.com
    options: { ac-env: test, ac-realm: prod, ac-site: myproject }

    paths: { drush-script: drush }
    user: vagrant
    ssh: { options: '-o PasswordAuthentication=no -i $HOME/.vagrant.d/insecure_private_key' }
dev:
    root: /var/www/html/myproject.dev/docroot
    uri: dev.site2.com
    host: [webserver].prod.hosting.acquia.com
    options: { ac-env: test, ac-realm: prod, ac-site: myproject }

    paths: { drush-script: drush }
    user: myproject.dev
    ssh: { options: '-p 22' }
prod:
    root: /var/www/html/myproject.prod/docroot
    uri: site2.com
    host: [webserver].prod.hosting.acquia.com
    options: { ac-env: test, ac-realm: prod, ac-site: myproject }

    paths: { drush-script: drush }
    user: myproject.prod
test:
    root: /var/www/html/myproject.test/docroot
    uri: stg.site2.com
    host: [webserver].prod.hosting.acquia.com
    options: { ac-env: test, ac-realm: prod, ac-site: myproject }

    paths: { drush-script: drush }
    user: myproject.test
ci:
    uri: 127.0.0.1
    host: 127.0.0.1
    • After this you may need to use the following inside the vagrant the local alias will work only from the host machine (Outside vagrant). 
       drush @self -l site2

     

    Pipelines

    If using pipelines, add or edit blt/ci.blt.yml and ensure it has the following:

    tests.run-server: true
tests.drupal.sudo-run-tests: false
project.local.hostname: 127.0.0.1:8888
drush.debug: false

     

    Setting up the Configuration Management

    Note: More information on config management:

    BLT assumes that multisites configurations are dependent on the default site in Drupal. This means that all the main configuration will exist in config/default and will be imported to every multisite, this is also true for the environment splits.

    The differences between sites will be handled by its own split.

    • Ensure config_split is enabled for the site: 
      • drush @site2.local en config_split
    • Create the folder for the new site: 
      • mkdir -p config/sites/site2

     

    Dependent configuration

    Dependent configuration is when all multisites import config from config/default, then import config afterward from its own config directory (config/sites/site2/).

    • Edit docroot/sites/site2/settings.php and add this line right above the blt.setting.php require at the bottom : 
      $config['config_split.config_split.site2']['status'] = TRUE;

      Do this for each site and change site2 = each individual site

    • Add or edit docroot/sites/site2/blt.yml (and for each site) and add/edit the following: 
      cm:
  # Possible values: core-only, config-split, features, none.
  strategy: config-split
  core:
    path: ../config
    key: sync
    dirs:
      sync:
        path: ${cm.core.path}/default
  features:
    no-overrides: true
    • Go to http://local.site2.com/admin/config/development/configuration/config-split/add and add this config:

               Status (Active): false
               label: site2
               folder: ../config/site2
               blacklist: {  }
               graylist: {  }
               graylist_dependents: true
               graylist_skip_equal: true
               weight: 0

    • Export the config to default: 
      • drush @site2.local cex
    • Test that everything is exported correctly, you should see a message indicating there are no changes. If the import keeps trying to add some config, export again and reimport till it is working: 
      • drush @site2.local cim

     

    Independent configuration

    Independent configuration is when each site has its entirely own set of configuration per site (config/sites/site2) and there is no shared config among the sites in config/default.

    • change the end of docroot/sites/site2/settings.php from:
    require DRUPAL_ROOT . "/../vendor/acquia/blt/settings/blt.settings.php";

    To:

    // Don't let BLT handle config management folder for the multisite.
$blt_override_config_directories = FALSE;

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

$config_directories = array();
$config_directories[CONFIG_SYNC_DIRECTORY] = '../config/[sitename]';
    • Add or edit docroot/sites/site2/blt.yml (and for each site) and add/edit the following: 
      cm:
  # Possible values: core-only, config-split, features, none.
  strategy: config-split
  core:
    path: ../config
    key: sync
    dirs:
      sync:
        path: ${cm.core.path}/site2
  features:
    no-overrides: true

       

    • Add the config splits for each environment:
      • Add the folders for each environment (ci,local,dev,stage, and prod): 
        • mkdir config/envs/[env]/site2
      • In the interface create splits for each environment they should look like

               active: false
               id: [env]
               label: [env]
               folder: ../config/envs/[env]/[sitename]

    • Export the config to the site: 
      • drush @site2.local cex
    • Test that everything is exported correctly, you should see a message indicating there are no changes. If the import keeps trying to add some config, export again and reimport till it is working: 
      • drush @site2.local cim

    ​​​​​​​

    Deploying the site to Acquia Cloud

    • Deploy code to Acquia cloud and switch it to your tag.
    • Get the DB started for a new multisite (only once) If starting from scratch but a different version of Drupal is installed, since we are assuming a brand new site you need to push the DB you created locally to the Acquia Cloud (also assuming your default env in Acquia Cloud is set to dev in blt.yml): 
      • drush @site2.local sql-sync @self @site2.dev
    • Switch the code to the same tag you deployed before so it can run the Config import for the new multisite.
    • Confirm that the site is working, run the next command and you should see the site working (given that the domain for dev can be resolved): 
      • drush @site2.dev uli

     

    Acquia Products

    Topics

    Related articles