HowTo: Configure your local workstation to serve multiple sites using Drupal's multisite configurations and Apache's VirtualHost

Drupal, like many other CMS tools, is most often used to run entire web sites. This means that, by default, Drupal expects path names to start from the root directory. If you're developing for multiple sites from a single desktop (or laptop/notebook) computer, it can be a real hassle to deal with changing base_urls paths for each installation of Drupal that you develop for. A much more elegant solution would be to treat your local workstation as a personal development server, with a unique non-routable host name, for each site you're working on.

To do this on Mac OS X, you need to do several things:

1. Choose and add an appropriate host name to your name-resolution service (most simply your /etc/hosts file).
2. Configure Apache virtual hosts to respond to requests for the host name you chose.
3. Install the local, development environment for the Drupal site you're working on, including all the normal steps needed to install Drupal, such as creating a MySQL database and user (see Installing Drupal in the Getting Started guide (or watch a Drupal installation videocast) for more information on this).
4. Create any multi-sites you need by adding another folder in the sites folder (along with a new settings.php file) and adding the corresponding host name to your name-resolution service.

Step 1: Add a new host name to your local machine

The easiest way to add a new host name to your local machine is to list it as an entry in your /etc/hosts file. Add the following line to your /etc/hosts file:

The .local top-level domain is reserved for local use and so will never conflict with an actual Internet site (such as your client's) that you may need to access.

You're now ready to set up an Apache virtual host that will answer to a Host HTTP header of "drupal.local".

Step 2: Add a new Apache virtual host

In Mac OS X versions prior to 10.5 ("Leopard"), Apple uses Apache version 1.3.x. From Mac OS X 10.5 Leopard onwards, Apple ships Apache 2.2.x. For our purposes, the only difference in the two versions is the location of their configuration files. The content we'll add to the configuration files will be the same. For Apache 1.3, configuration files are located in the /etc/httpd directory, whereas for Apache 2.x, configuration files are located in the /etc/apache2 directory.

For Mac OS X 10.5 Leopard and Apache 2.2.x, edit /etc/apache2/httpd.conf and uncomment the following line:

#Include /private/etc/apache2/extra/httpd-vhosts.conf

This will enable Apache's virtual hosts mechanism on your system.

Next, edit the /etc/apache2/extra/httpd-vhosts.conf file. By default, this file will contain two example VirtualHost blocks. The first block's directives need to exactly match the directives in the main /etc/apache2/httpd.conf file. For example, the first block could read as follows:

The second VirtualHost block will be those used for your other sites. Simply change the second example VirtualHost block or append the following at the end of the file, replacing references to "yourusername" with the appropriate details for your system, of course:

Note that the ServerAdmin line is optional, but handy. Also note that the DocumentRoot we've chosen ends with 6 simply because we're assuming you're working with Drupal 6—naturally, you'll want to change this to root of your Drupal install if it is different. Also make sure the filesystem path in the ErrorLog and CustomLog directives uses httpd instead of apache2 if you are using any Apache version prior to 2.

To be certain you've introduced no syntax errors or other problems into your Apache configurations, you can run httpd -S. If Apache reports that the syntax is okay, you can now restart Apache by turning "Web Sharing" off, then back on again in the Sharing System Preferences pane, or simply by typing sudo apachectl graceful in the Terminal.

Step 3: Install your Drupal site!

From here on out, it's standard Drupal set up instructions. Put a fresh copy of Drupal core into /Users/yourusername/Sites/drupal/6

Now visit http://drupal.local in your web browser and you should see the Drupal installation screen.

Step 4: Using Drupal multi-sites

Drupal multisites lets you run multiple installations of Drupal from the same codebase. Let's say you want to set up two new sites in addition to our vanilla Drupal site. We'll call them "Roman Mythology" and "Greek Mythology" and we'll give them easily identifiable hostnames: romanmythology and greekmythology, respectively.

1. Firstly, add these hostnames to your /etc/hosts file by appending the following two lines:
   
   127.0.0.1       greekmythology.drupal.local
127.0.0.1       romanmythology.drupal.local
2. Then, in your sites folder at /Users/yourusername/Sites/drupal/6:
   1. create 2 new folders whose names match the new hostnames you've just created. In this case, you would name the folders greekmythology.drupal.local and romanmythology.drupal.local.
   2. copy the settings.php file from Drupal's sites/default folder into each new folder you've just created.
   3. in each of the newly copied settings.php files, comment out or change the $db_url value back to its distribution default so that configuration line reads exactly like
      $db_url = 'mysql://username:password@localhost/databasename';.
      This will cause Drupal to prompt you to install a new instance.

To install the "greekmythology" site, visit http://greekmythology.drupal.local and to install the "romanmythology" site, visit http://romanmythology.drupal.local. Naturally, you'll need to install each site into its own database. (Although you can share a single database among multiple sites by using table prefix names to disambiguate different sites, this is not recommended for production instances.)

Tip: Use Virtualization software such as VMWare Fusion or Parallels Desktop to browser test this same codebase

Once this setup is working, you can increase your productivity by using a virtualization tool to test on different Operating Systems and browser combinations. For example, if you want to test the very same codebase on Internet Explorer 6 for Windows and you are using VMWare Fusion, simply install a VMWare Windows guest OS as normal. When it's done, modify the guest OS's hosts file just as you did for the Mac OS X host OS before, but instead of pointing the entry to 127.0.0.1, point it to the network address of the host.

By default, VMWare shares the host's network using a NAT-ed address in the 172.16.xxx.xxx IP address range. In Windows, you can find out the exact address by going to Start -> My Network Places -> View Network Connections -> Local Area Connection which will open the Local Area Connection Status window. Click the Support tab and note the IP address of the Default Gateway. If that address, for example, 172.16.5.2, then append the following lines at the bottom of the plain-text file located at C:\WINDOWS\system32\drivers\etc\hosts:

Now, when you type http://greekmythology.drupal.local in Internet Explorer's location bar, you'll be served the very same code you're working on.