Configuring a Drupal multisite

by Gisle Hannemyr

This chapter explains how to configure a multisite based upon Drupal 7.

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 setting, 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 7 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.

Locating the settings

The sites sub-directory is where you configure multisites. By default, this directory contains three files:

To add additional sites, you create additional sub-directories below the sites sub-directory that parallel the already existing default sub-directory. These sub-directories shall hold the settings.php, as well as files, modules and themes specific for the additional site.

When loading a site, Drupal search for the appropriate configuration directory in the sites sub-directory based upon the website's URL taking into account host-name, port number, and path. For example, giving the following URL: http://www.example.org:8080/testsite/beta/, Drupal will search for the directory below sites holding the configuration file and site specific files in the following order:

This search order is the key to Drupal's multisite feature. By setting up a directory with the a name that will be found during this search, one or more alternative sites may be configured on the same web-server.

Three approaches

There are three different approaches to multisite:

All three options 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. By means of example, this may be example.com (DNS-alias), sandbox.example.org (sub-domain), or example.org/sandbox (sub-site).

Then do as follows:

  1. First create the default site (as described above).
  2. Create an additional database to hold the content the first multisite, or use a table prefix to distinguish the sites if it is to share the default database (see step 3 in the site install recipe).
  3. Create a new sub-directory in the default site sites sub-directory to hold the new site's configuration.
    • For a DNS-alias, name it: example.com.
    • For a sub-domain, name it: sandbox.example.org.
    • For a sub-site, name it: org.sandbox.
  4. Copy default.settings.php from the default sub-directory into the newly created sub-directory.
  5. Copy default.settings.php to settings.php.
  6. 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.

Each site may have the following three sub-directories in its configuration sub-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.

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) are the next section, and the sub-site approach in the following.

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.
  2. Set up the second domain as an alias for the first, or create a vhost that has the same webroot as the default domain.
  3. Point your browser to the base URL of your website ( http://sandbox.example.org or http//example.com) and complete the site installation.

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.

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 securing the site.

Sub-site

  1. Create a symbolic link in the webroot directory that makes org.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/html
$ ln -s . sandbox
  1. Point the browser to this sub-site (i.e. http://example.org/sandbox/) and 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.

Securing 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. To make this happen, visit the settings directory of each site and use drush to run any database updates:

$ drush updb

For more about updating the code base, see the section about Updating extensions.

Final word

[TBA]

Last update: 2020-08-09 [gh].