How Drupal Multisite Works under the Hood

A Drupal multisite is an installation which allows us to use one codebase to serve multiple websites. In this post, I will explain in detail how Drupal multisite works, what approaches can be taken to set up a multisite installation. I will also explain some of the settings that may be important for a multisite which are not applicable when we build just one website on Drupal.

The basics of a default Drupal multisite

A Drupal website comprises a few major things:

1. Drupal core
2. Contrib and custom modules
3. Theme
4. Database
5. Configuration

When a request from the browser is handled by Drupal, one of the first things Drupal does is bootstrapping the database and loading configuration. From the database and configuration the system knows:

• which from the available modules and themes are enabled,
• how everything is set up:
  • where are public and private files folders,
  • which blocks are where,
  • what content is available,
  • what is on the front page,
  • which menus are in which regions, what links are in which menus, 
  • pretty much everything else about how the website is configured. 

To connect to the database, Drupal reads the connection information which is held in the settings.php file (which typically sits in /sites/default folder).

Notice the default folder. It is called default because it is a fallback folder when no other folders are found. In a single Drupal install, typically no other folders are set up and most websites are run from the default folder.

In a multisite installation, however, we set up separate folders for separate websites.

For example:

• /sites/example-one.com
• /sites/example-two.com

If we create such folders, a new request will examine the base domain (base URL as Drupal calls it) and will try to match it to the correct folder. The order is as follows:

When a request with a base URL of www.example-one.com comes in, Drupal checks if there is:

1. A folder named /sites/www.example-one.com and looks for settings.php there.
2. If there is not, Drupal will check a higher-order domain folder - /sites/example-one.com in this case. 
3. If it does not find settings.php there, it will move to the /sites/default.

We achieved a multisite - many websites on one codebase

If we have 2 folders for 2 different domains, we can have 2 separate settings.php files which connect Drupal to two separate databases, which load separate configurations and use various enabled modules and themes.

In essence, we end up with 2 different websites, which have their own databases, content, files and configurations, even though they sit on one Drupal code.

If we add additional folders, we get additional websites without the need to duplicate code.

Drupal can run hundreds of websites from one installation like this.

Sites.php file helps to map domains for folders

To help with the mappings of base URLs to folders, Drupal offers a sites.php file which can be used to assign base URLs to correct folders.

In the /sites/ folder we are offered a file which is called example.sites.php. Change its name to sites.php and Drupal will use it. The configuration of mappings is quite simple:

$sites['an-old-domain-to-map.coom'] = 'example-one.com;

This file allows us to map several domains to one website if we need to and helps a lot with development because development environments typically have different URLs than production ones.

$sites['localhost.example'] = 'example.com';

Some dev teams use this feature also to keep the sites folder clearer when there are hundreds of websites with various domains sometimes in foreign languages. The dev team can have short clear folder names.

$sites['nom-de-domaine-de-marque-tres-long.fr
'] = 'brand-x-fr;

This is also sometimes useful if the domain for one of the websites changes.

Which website can use which modules

Typically, we are used to a situation where

• all modules are placed in the modules directory (or sites/all/modules in Drupal 7 and previous versions),
• all themes are placed in the themes directory (or sites/all/themes in Drupal 7 and previous versions).

If we have one website on the system, there is no need for any other configuration. We add only the modules we need.

In a multisite installation, however, there might be a need to specify which websites can use which modules or themes. In a large system with hundreds of websites and administrators, such restrictions might be crucial to only allow such functionalities on each website which work well together.

We can control this in 2 ways:

1. Via installation profiles

Each website on Drupal is built on an installation profile. Typically this is the standard or minimal profile which is shipped by Drupal out of the box. You chose between these when you install Drupal and you can see them in the /core/profiles folder. None of these 2 profiles has any modules or themes but a profile can provide these.

Drupal for example ships with a demo_umami profile which is a demo profile and includes both: a demo_umami_content module and an umami theme. If you install a standard installation, you will not have access to the umami theme from the admin panel for example.

If you have to control which websites have access to which themes or modules you place these in your custom installation profiles. Only the websites installed on a particular installation profile will be able to access and use what it provides.

What is cool is that profiles allow for inheritance. You can, for example, create one profile with drupal commerce modules and then 2 additional child profiles which will then be able to access the Drupal commerce modules.

While performing Drupal services for our clients we have implemented various scenarios with different levels of granularity. You could even create a child profile for each website to be able to have very granular control. This might however be a bit of an overkill.

2. Per website modules via the website folder

Modules and themes can be also added to the website folder. In our example, we could put them into:

• sites/example-one.com/modules
• sites/example-one.com/themes

Modules and themes placed in these directories will only be available to website example-one.com.

As a rule of thumb, you should probably avoid having too many modules here since it probably goes against the concept of a multisite to have completely different code for each website, but sometimes there is a need to add a few per-website tweaks or create for each a subtheme for a website which overrides a few things in a shared base theme.

Updating code once, running update 100 times

One of the great things about a multisite is reduced maintenance. If you have 100 websites on one system and a new version of Drupal comes out, you only have to update the code once instead of 100 times.

That said, remember that settings and databases are separate for all 100 websites. You do have to run the update.php script for each one separately!

Summary

Above I explained in detail how Drupal multisite works under the hood. In essence, it is a very simple and yet a powerful feature of Drupal which allows companies to reduce maintenance and technical debt and keep maintainers sane if they have to maintain many websites.