Using multiple Apache virtual hosts on a development machine

The problem

When I first developing web applications I was only responsible for one site. My typical workflow was to have a checkout of the application in my document root and to just use http://localhost to debug it before I checked in my changes. As I started working on other projects, I would just go into my Apache configuration and change my document root to another directory. This got rather annoying after a while since I had to edit files and restart Apache every time I switched gears.

Then the light bulb clicked on: I knew how to configure virtual hosts to run multiple sites on web servers, why didn’t I just do the same thing on my local machine? Once this is accomplished, it becomes very painless to switch contexts between multiple applications. As an added bonus it also makes it very easy to install open source web applications on your local machine, do some hacking, and learn how they work. While this same thing is technically possible just by adding new folders to your document root, this can really confuse some web applications that are expecting to handle all of their URLs as directly relative to your base path.


The only prerequisite to this tutorial is that you have a relatively clean install of Apache on your local machine. You can use the default OS X install, or also also a vanilla copy installed via the Windows Apache installer. I am going to give instructions for a *NIX OS, but this setup also works fine in Windows.

Set up

  • First, you will want to locate your Apache configuration directory (containing http.conf). On OS X or most other flavors of UNIX it is /etc/apache2/, or Windows: C:/apache2/conf. Next, open your terminal and cd into the directory: $ cd /usr/local/apache2/conf

  • Add a “sites” subdirectory to your Apache configuration directory. This is the directory that will hold all of your virtual host configuration files. $ mkdir sites

  • Locate your httpd.conf file, open it up for editing $ nano httpd.conf

  • Now, we want to edit a couple of configuration settings. You may find variations of these already in the file that you can either delete or modify.
    NameVirtualHost *:80
    Include conf/sites

    The first line tells Apache to use name-based virtual hosts. This means that it will match virtual hosts based on the domain name of the request. The second line causes all files in the sites directory to be included when Apache reads in it’s configuration files. Note that this folder location is relative to your ServerRoot location which you will find elsewhere in httpd.conf if you search for it.

  • Next, you are going to go into your “sites” folder and create your first virtual host configuration file. It is helpful to name the files based on the domain that they reference (I am going to create http://local.andrew).
$ cd sites
$ nano local.andrew.conf

The basic file contents are

<VirtualHost *:80>
  ServerName local.andrew
  DocumentRoot /Users/andrew/Sites/somecoolsite
  <Directory /Users/andrew/Sites/somecoolsite>
    Options +FollowSymLinks
    AllowOverride All

This is fairly self explanatory. In the first line you set the domain that you want to use with the ServerName directive. The document root of your files (they can be anywhere on your computer) goes after the DocumentRoot directive. Finally, the Directory block is where you can put any settings that are specific to this host (e.g. Rewrite rules).

  • Next, you will need to create an entry in your host file to direct all traffic sent to your custom domain to your local machine. On any *NIX system the file is /etc/hosts, and on Windows it is C:\WINDOWS\system32\drivers\etc\hosts. The format is the same on all systems, just add a line like: local.andrew

  • You are all done setting up your first virtual host. Restart Apache (you will probably need to use a hard restart - apachectl restart - for your vhost settings to be applied), and direct your browser to whatever hostname you created. You should see your site right away!

Now that you have 1 host set up it is super easy to add more. Just copy your existing host file to a new name and edit the settings accordingly! This should greatly improve your workflow and help you be a more productive ninja developer.