Drupal, like many other CMS tools, is most often used to run entire websites. 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-site 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:

127.0.0.1        drupal.local

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:

<VirtualHost *:80>
    DocumentRoot "/Library/WebServer/Documents"
    ErrorLog "/private/var/log/apache2/error_log"
    CustomLog "/private/var/log/apache2/access_log" common
</VirtualHost>

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:

<VirtualHost *:80>
    ServerAdmin webmaster@drupal.local
    DocumentRoot "/Users/yourusername/Sites/drupal/6"
    ServerName drupal.local
    ServerAlias *.drupal.local
    ErrorLog "/private/var/log/apache2/drupal.local-error_log"
    CustomLog "/private/var/log/apache2/drupal.local-access_log" common
</VirtualHost>

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-site

Drupal 7 (or) Drupal 8 multisite 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/sites:
    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:

172.16.5.2        greekmythology.drupal.local
172.16.5.2        romanmythology.drupal.local

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.

Comments

Keith’s picture

In step 2 you refer to two httpd-vhosts.conf files: one in /private/etc/apache2/ and the other in /etc/apache2. Since you uncommented the former's Include directive, shouldn't it be edited, not the latter?

Also, in my main httpd-conf file, that Include directive is not commented out, so that instruction may be redundant.

tnanek’s picture

Both of /private/etc/apache2 and /etc/apache2 are in the same actual location on the hard drive, so editing one is the same as editing the other.

For those who are curious, the /etc folder is symbolically linked to /private/etc, which means everything inside those folders is always the same; basically when you go into the /etc folder, you're actually going to the /private/etc folder on the system, which is the actual location of the files.

sebas5384’s picture

Hi!

I had to make those steps every time a new project come, so, I made a little and simple script in PHP that do it all for me.
In can find the code here:

http://github.com/sebas5384/VirtualHost-Manager

and hey!, help me to make it better!

Cheers!,
Sebas.

psych0hans’s picture

Hi, I know this is a very noobish question, and thats's coz I am a noob... But what is the location of "/etc/hosts"? I have my drupal install in "/Users/yourusername/Sites/drupal" and I'm using mamp. But I can't find a folder called "etc" and the "apache2" folder has no "hosts" file... Please advise...

Creative Existence’s picture

Open BBEdit or TextWrangler (a free, cut-down version of BBEdit available from www.barebones.com). From the File menu, select Open Hidden. In the Open dialog box, select All Files from the Enable drop-down menu. Then navigate to Macintosh HD:private:etc:hosts, and click Open.

kricklin’s picture

If you've been utilizing MAMP to run PHP, MySQL and Apache on your development workstation and want to implement Apache VirtualHosts, this HowTo - with the following changes - worked for me:

  1. In Step 2, skip the instruction for un-commenting the “#Include...” statement, as MAMP doesn't use an httpd-vhosts.conf file.
  2. Also in Step 2, modify MAMP’s copy of the Apache VirtualHost blocks in HD/Applications/MAMP/conf/apache/httpd.conf, not OS X's copy located in the HD/private/etc/apache2 folder.
  3. In Step 4, when setting up a new site folder copy Drupal's sites/default/default.settings.php file to the new site folder, and then rename the file to "settings.php".

Notes:

  • MAMP and OS X install separate versions of Apache, as well as PHP and MySQL. Therefore, its important to modify the correct httpd.conf file for MAMP's copy of Apache to recognize VirtualHosts.
  • When installing a new instance of Drupal, I received a database error when using a copy of an existing settings.php file for the new site (I modified it to use the original $db_url). Copying the original default.settings.php file to the new site folder and then renaming it to "settings.php" provided an error free install.
  • My workstation is running OS X 10.6.5 and MAMP 1.9.
Sam Moore’s picture

Sincs MAMP's Apache likes to listen on port 8888 out of the box, you'll want to either change VirtualHost *:80 to VirtualHost *:8888, or just leave out the port altogether.
Alternatively, you can set MAMP's Apache to listen on port 80 (in the Preferences, go to the Apache tab).

kricklin’s picture

Hi -

When creating a new site for my mutisite MAMP setup, I received a "Drupal Already Installed" error when I attempted to install Drupal 6.19 to a new MySQL database. I'd created two other local multisites successfully, so I figured I did something wrong.

The steps I'd taken to get to this point were:

  1. Appended a new hostname - "newsite.drupal.local" to the bottom of the etc/hosts file.
  2. Duplicated one of my existing site folders and renamed it to match the new hostname.
  3. Copied the original default/default.settings.php to the "newsite.drupal.local" folder, and renamed it to "settings.php".
  4. Using my browser, navigated to and launched "newsite.drupal.local/install.php". Promptly received the "Drupal already installed..." error.

More than 2 hours (and a lot of hair-pulling) later, I was able to correct this problem by deleting the "newsite.drupal.local" folder I'd copied from my other multisite, then created a new folder with the exact, same name from scratch. I then copied to the new folder the original default/default.settings.php file and renamed it to "settings.php". When I attempted to run the installation again, it completed smoothly.

Notes - My guess is that by creating my newsite.drupal.local by COPYING another local site folder, the install.php found something I'd copied over that caused it to think that I was trying to re-install Drupal to an existing database.

arezendes’s picture

Just wanted to mention you can forgo this entire process if your elect to download the latest Acquia_Drupal DAMP Stack at http://acquia.com/downloads (version 7.4.4 as of 08/21/11). It has built in switching. I actually started to go down this path until I realized I didn't need to. Save yourself some time and check it out.

justindancer’s picture

Hi there,

I've followed the instructions for multisite and got a first site up and running on http://drupal.local/

I am now trying to add a second site to the same codebase, asscessible from http://drupal.local/private/

The drupal install instructions seems to indicates that this is possible, but for the life of me I cant figure out the necessary configuration. My server just throws a 404 not found error.

Any help would be appreciated!

Justin

rHOnDO’s picture

@Justin - A couple of pieces of the puzzle you may be missing if you are running Drupal 7.

1) You will need to set up an entry in your hosts file ('sudo vi /private/etc/hosts'). Add an entry for your new site:
127.0.0.1 private.drupal.local

2) Go to your Drupal install and verify you have a directory at '{drupal-core}/sites/private' and that it has a new 'settings.php' file copied from '/sites/default/default.settings.php'

3) Make a copy of the file '/sites/example.sites.php' renaming it to 'sites.php'

4) Read the instructions in 'sites.php' and create the required alias(es). Yours should look like:

$sites = array(
'private.drupal.local' => 'private',
);

5) You may have to restart Apache ('sudo apachectl restart') but then your new site should be accessible at:
http://private.drupal.local

Hope this helps.

rHO