Configuring a Drupal multisite

by Gisle Hannemyr

This chapter explains how to configure a multisite based upon Drupal 8/9.

Table of contents

Introduction

Drupal allows you to run multiple websites from the same code base (multisite). A multisite allows you to share a single Drupal installation (including core, contributed modules, and themes) among several websites. Each site will have its own settings, users, content and files, and may have additional contributed modules and themes.

Who these notes are for

This note is general in scope, but its primary audience is the staff of Hannemyr Nye Medier AS for our internal training courses. It may also be of interest for a wider audience, including customers we train and support, and others that are interested in learning more about setting up a Drupal 8/9 multisite. These notes are not login protected, but the URL has only been given to a limited audience consisting of customers that we train and support, and a few others that has expressed interest in the project.

In the guidelines below, there are references to using the commands fixperms and instperms. These are proprietary tools provided by Hannemyr Nye Medier AS to its customers. They are not generally available.

The sites sub-directory

The sites sub-directory is where you configure multisites. By default, this directory contains one directory and four files. Only these two are going to be discussed in this chapter:

To add additional sites, you create additional sub-directories below the sites sub-directory in addition to the already existing default sub-directory. These sub-directories shall hold the settings.php, as well as the files directory specific for the site.

A file named sites.php, described below, sort out the mapping between a particular website and its configuration directory.

Three approaches

There are three different approaches to multisite:

All three approaches are set up using a similar strategy.

Assuming we want have a default site named example.org and want to create another site using the same code-base. This, for example, may be example.com (DNS-alias), sandbox.example.org (sub-domain), or example.org/sandbox (sub-site).

To sett up a multisite with the default site and at least one additional site, start by doing the following:

  1. First create the default site by installing Drupal (as described here).
  2. Create an additional database to hold the content the first additional site, or use a table prefix to distinguish the sites if it is to share the default database (see step #4 in the site install recipe).
  3. Create a new sub-directory in the sites directory to hold the new site's configuration. The name can be anything, but the following is recommended:
    • For a DNS-alias, name it to match the alias, e.g.: example.com.
    • For a sub-domain, name it to match the subdomain, e.g.: sandbox.example.org.
    • For a sub-site, name it to match the subsite path from default site, e.g.: sandbox.
  4. Copy default.settings.php default.services.yml from the default sub-directory into the newly created sub-directory. Then: Copy default.settings.php to settings.php and copy default.services.yml to services.yml.
  5. Make sure that both the configuration directory and settings.php is writable by the web-server user. You may do this running instperms (if available) in the directory you created in step #3 above.

What to do next depends on what approach to multisite you want. All three approaches are described below. The first two approaches (DNS alias or sub-domain) in the next section, and the sub-site approach in the following section.

DNS alias or sub-domain

  1. Set up your DNS for the second domain (e.g. sandbox.example.org or example.com) to point to the same IP as the default domain.

noteCreating virtual host configurations on your web-server does not magically cause DNS entries to be created for those host names. You must have the names you want to use in DNS, resolving to your IP address, or nobody will be able to see your DNS aliases or sub-domains.

Below is an example of how the DNS record may look if your primary domain is named example.org and is located at IP-address 198.51.100.12. You then may have additional A-records pointing to the same IP-address for any sub-domains or DNS aliases you want to use.

DNS record for primary host, sub-domain, and DNS alias
Hostname TTL Type IPv4 address
example.org 3600 A 198.51.100.12
sandbox.example.org 3600 A 198.51.100.12
example.com 3600 A 198.51.100.12

You should also be able to use CNAME records.

  1. Set up the second domain as an ServerAlias for the first in the Apache2 configuration file for the default vhost, or create a new vhost that has the same webroot as the default domain.

To create a multisite instance, you also need to make sure the DNS for that instance points to the same web root as the default domain. If you've set up a sub-domain, the simplest way to do this is to add it as a ServerAlias. This means putting something like this in the Apache vhost configuration:

<VirtualHost *>
  ServerName example.org
  ServerAlias www.example.org
  ServerAlias sandbox.example.org
  …
  DocumentRoot /var/www/example.com/htdocs/
  …
</VirtualHost *>

Alternatively, you may create a separate vhost for the multisite. This requires a separate entry, but allow you to tailor the web server settings for this particular multisite instance.

To finish the installation skip ahead to the section about pointing to configuration directory.

Sub-site

  1. Create a symbolic link in the webroot directory that makes sandbox (via the symbolic link) a sub-directory of the webroot directory.

In the example below, we first use the pwd command to make sure we're in the right place, then we create the symbolic link.

$ pwd
/var/www/example.org/web
$ ln -s . sandbox
  1. [Placeholder to make sure the next step is #8].

Point to configuration directory

The second website has its own configuration directory that is different from the configuration directory of the default website (which is always named “default”). The configuration directory contains the website's configuration files (i.e. settings.php and services.yml).

To make sure that requests are able to locate the correct configuration file and locate the correct database, we must map from the formatted address of the website to its cofiguration directory. This is done with a file named sites.php located in the sites directory.

  1. Copy sites/example.sites.php to sites/sites.php.
  2. Add an entry linking the formatted address of the website to its configuration directory to sites/sites.php as described below:

This file will contain an array named $sites. Its format, and how to use it to use it to define a set of aliases that map hostnames, ports, and pathnames to configuration directories in the sites directory is decsribed in a docblock at the top of file. Generally, for each array index, the key will be the formatted address the website will be accessed at (i.e.: port.domain.path), and the value will be what directory to look in for the configuration for the particular site (i.e. a DNS-alias, sub-domain or sub-site.)

The general format of each array entry is:

'port.domain.path' => 'config-directory'

For instance, to set up a sub-site with URL http://example.org/sandbox to the use the configuration direcory sandbox below sites, add the follwoing key and value.

$sites = [
  'example.org.sandbox' => 'sandbox',
];

Save the file after editing it.

noteIf there is an syntax error in the PHP in this file, the site will break and you will get the error message “The website encountered an unexpected error. Please try again later”. Be very careful when introducing this PHP-file into the site.

Each site may have the following three sub-directories in its configuration directory.

The last two is for holding modules and themes specific to the site. If you need them, you need to create them yourself. This will not be covered in this chapter.

Now you should be able to complete the installation:

  1. Point your browser to the base URL of your website (e.g.: http//example.com if it is a DNS-alias, http://sandbox.example.org, or http://example.org/sandbox/ if it is a sub-domain). Complete the site installation.

After completing the web based part of the installation, you will have another Drupal WCMS site at your web-server that may be managed as an independent WCMS. However, updates to the core and modules and themes placed in the all sub-directory will be shared between all sites.

  1. Secure the site.

For all three approaches you need to make sure each site's code base, configuration directory and settings.php is secure. Also make sure the files sub-directory is writable by the web server user. You may do this running fixperms (if available) in the site root.

Database updates

Updating the code base of a multisite does not run any database updates.

noteOne used to be able to visit the settings directory of each site run any database updates with this command: $ drush updb. You now need to provide the full path. For more information, see this DO forum post

Final word

[TBA]

Last update: 2021-04-30 [gh].