“I have used Mike repeatedly over almost a decade. He produces high quality, creative work at great value and has produced clear, user-friendly websites for every business venture that I have been involved in. He works quickly and the only time he doesn’t do what you ask is when he comes up with a better idea than yours! I can wholeheartedly recommend Mike’s work.”

— Mike Rigby (The Original Carbon Company)

The objective of this article is to provide the missing background information that most Drupal multi-site tutorials miss out. It’s these nuggets of wisdom that make the difference between a multi-site installation that works and one that’s a right royal PITA to set up and get going. The article supplies the tricks and tips needed whether you’re:

  • On Windows or Linux
  • Using Drupal 6.x or Drupal 7.x
  • Wanting development and production setups
  • Using a shared database or individual ones

Before we discuss the advanced tweaks you might want to do, it’s worth taking a minute to understand how a basic Drupal multi-site installation works. Most of the confusion I’ve seen seems to stem from not really grokking what’s going on during the install. So, we’ll do a quick walkthrough of the major conceptual points of a simple two-site setup.

Supporting Multiple Sites

When you unpack the Drupal code you end up with a two major conceptual components; the Drupal codebase itself and a subfolder (and its children) called sites which is used to store the settings for your individual Drupal sites.

Although all your sites will use the same codebase, Drupal decides which of your sites to show based on the HTTP request that you give it through your browser. So, if you enter http://site1.com in your browser, Drupal will look for a folder called site1.com in its sites sub-folder and display the content as dictated by the contents of that folder. Likewise, if you have a folder within sites called site2.com and you enter http://site2.com in your browser, then Drupal will show the content for site2.com. In summary, create a folder for each site within the sites sub-folder of your Drupal installation. This is the basic mechanism by which multi sites are supported in Drupal but it can be tweaked in a number of ways.

In addition to this, you need to set things up so that requests from your browser for http://site1.com and http://site2.com both get routed to the IP address of the machine hosting your Drupal code. You also need to make sure your web server is routing those requests to the right folder. The exact details of how to do this vary wildly depending on your situation but it’s trivially easy to find out how to do this so I won’t repeat it here. Google is your friend.

Finally, you need to create the sites themselves. To do this you need to copy default.settings.php from the sites\default folder into each of your site folders (sites\site1.com and sites\site2.com in our example), rename it to settings.php and make sure both it and the site specific folder are writeable. The last step is to point your browser to http://site1.com to start the site installation. This process will make changes to your site specific settings.php including storing info about which database Drupal should use for storing the bulk of your settings and content. Repeat this for each of your sites. Oh, don’t forget to set the privs on settings.php back to read only.

That’s it. You’re all done. Note that we’re not setting up any themes or custom modules or views etc. This is just a basic bare-bones Drupal installation.

Overall, what’s happened here is that a single codebase is used by Drupal to translate incoming HTTP requests into pointers to the relevant site-specific subfolder of the main sites folder. The installer builds your site by writing the site-specific setup info into the settings.php file in those folders. These settings.php files, in turn, point Drupal to the relevant database when it’s building content for display.

Development and Production Setups

The above scenario assumes you’re installing straight onto a production server. In practice this is a bad idea and you’ll normally want to build your sites on a development server, usually localhost before you deploy to production and go live. How does Drupal support this situation?

When Drupal is looking for the relevant sites sub-folder, it doesn’t simply look for an exact match in the URL. If you take a look at the comments near the top of settings.php you’ll see the search order that Drupal uses to do this. Making use of this search order usually allows you to build a site in development and then send it to production with a minimal amount of changes.

In Drupal 6 this is the only option you’ve got but in Drupal 7 a new file has been introduced to the top level of the sites folder called example.sites.php. Copy this file to sites.php in the same folder and edit it. Down at the bottom are a couple of example site mappings. Edit these to suit your needs. So, in our example, with sites/site1.com and sites/site2.com sub-folders we would use the following:

$sites['site1'] = 'site1.com';
$sites['site1'] = 'site2.com';

Then, if you’re working on your development server you enter http://site1 in the browser (without the .com suffix) and Drupal will use the sites.php file to map this into a request for the folder sites/site1.com. On your production site, accessed through http://site1.com in the browser (with the .com suffix) Drupal will not use these mappings and will just go straight to the sites/site1.com folder automatically.

Sharing Databases

Some hosting services limit the number of databases you can create. Drupal allows you to share a single database between multiple sites.

Before you run the Drupal installer you need to create your database(s) yourself using something like cPanel or phpMyAdmin. If you want to dedicate a database to each Drupal site then just create databases called site1 and site2. If you want to share a single database between all your Drupal sites then create a database called drupal. Finally if you want to share a single database between all your Drupal sites as well as other stuff then just create a database called shared.

If you’re using either the drupal or the shared options then you’ll need to tell Drupal you’re using a shared database. You do this by specifying a table prefix on the Advanced Settings section of the database configuration page which you’ll encounter as part of the installation script. In our example we might use the prefixes site1_ and site2_.

What About sites/all and sites/default?

In addition to the site specific sub folders we created under the Drupal sites sub folder, you’ll probably also notice Drupal has its own sub folders here called sites/default and sites/all. The first of these is used by Drupal to store your site if it can’t fins a site specific folder like the ones we created. The second is used to store modules and themes that will be available to all your Drupal sites.

Further Reading