Setting up virtual hosts on OS X Leopard to Lion

Here is a definitive guide to setting up virtual hosts on OS X, the instructions work on all versions from Leopard to Lion/Mountain Lion.

If you have lots of sites to test, you might want to be able to type a url into the browser, and see the site directly. To do that you need to modify your Mac’s hosts file, and set up a Virtual Server.

Updated Feb 2012

Preparation

Decide upon the URL you want to use, I’m going for mark-kirby.dev in this example.

Decide where you want the files to go that will appear for this url, and place them there on your computer. I’m using /Users/username/Sites/mark-kirby for this example.

Start apache:

  1. Go to system preferences
  2. Select “sharing”
  3. Check the box “Web Sharing” – apache will start

2 – Edit the hosts file

Open the file

[bash]
/private/etc/hosts
[/bash]

Since this file is hidden, you will need to need to check the option “open hidden files” if your text editor has one, or use the terminal to open the file directly.

[bash]
mate /private/etc/hosts
[/bash]

Alternatively, you could:

  1. Open finder
  2. click on go
  3. select “Go to folder”
  4. enter in /private/etc/

You will see the following:

[bash]
##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting. Do not change this entry.
##
127.0.0.1 localhost
255.255.255.255 broadcasthost
::1 localhost
[/bash]

Underneath this, enter your local IP address (127.0.0.1) and the name of the site you want to set up, e.g.

[bash]
127.0.0.1 mark-kirby.dev
[/bash]

Save the file – you will have to authenticate – and now when ever you type http://mark-kirby.dev into a browser it will give you your local folders – EVEN if mark-kirby.dev is an actual website on the internet. Browsers always check the hosts file first.

Add the virtual host in apache

If you type mark-kirby.dev into your browser now, you will still see your default folders, you need do some more work.

Open the file

[bash]
/private/etc/apache2/extra/httpd-vhosts.conf
[/bash]

using the methods described above.

You will see this first –

[bash]
#
# Use name-based virtual hosting.
#
NameVirtualHost *:80
[/bash]

Don’t touch it!

Then you will see this –

[bash]
<VirtualHost *:80>
ServerAdmin webmaster@dummy-host.example.com
DocumentRoot "/usr/docs/dummy-host.example.com"
ServerName dummy-host.example.com
ServerAlias www.dummy-host.example.com
ErrorLog "/private/var/log/apache2/dummy-host.example.com-error_log"
CustomLog "/private/var/log/apache2/dummy-host.example.com-access_log" common
</VirtualHost>
[/bash]

First I’ll quickly explain what each line means:

So really, you only need DocumentRoot and ServerName if this is a test server only you will access.

Firstly comment out the examples – very important, don’t miss this step!

Then add a default entry so localhost will still take you to the root of your Sites folder:

[bash]
<VirtualHost *:80>
DocumentRoot "/Users/username/Sites"
ServerName localhost
</VirtualHost>
[/bash]

Finally, add your entry, e.g.

[bash]
<VirtualHost *:80>
DocumentRoot "/Users/username/Sites/mark-kirby"
ServerName mark-kirby.dev
</VirtualHost>
[/bash]

Save this, you’ll need to authenticate.

Set Permissions on your sites folder

Thanks to Jeremy Keiths solution – we can ensure permissions are set to allow all sites to be viewed without setting them on each one. This is great for our purposes, but would never be used on a live server.

Add this to your vhosts file:
[bash]
<Directory /Users/*/Sites/>
Options Indexes Includes FollowSymLinks SymLinksifOwnerMatch ExecCGI MultiViews
AllowOverride All
Order allow,deny
Allow from all
</Directory>
[/bash]

Activate virtual hosts in apache

If you haven’t done so, by default the file you just edited, won’t be enabled in Apache.

To change this open up another hidden file – /private/etc/apache2/httpd.conf

Find the line

[bash]
# Virtual hosts
#Include /private/etc/apache2/extra/httpd-vhosts.conf
[/bash]

And uncomment the include so it looks like this:

[bash]
# Virtual hosts
Include /private/etc/apache2/extra/httpd-vhosts.conf
[/bash]

Save the file – you may need to authenticate.

Restart Apache

This still won’t work, until you restart apache.

To restart apache:

  1. Go to system preferences
  2. Select “sharing”
  3. Uncheck the box “Web Sharing” – apache will stop
  4. Check it again – apache will start

or…

[bash]
sudo apachectl restart
[/bash]

Test your site – you should be in luck!

  • Tony Brown

    when I un-comment that line out the localhost doesn’t work anymore
    [ Include /private/etc/apache2/extra/httpd-vhosts.conf ]

  • Stephane

    Hi Tony,

    That was a beautiful and very helpful article. I’m no network admin and it was a breeze to follow. It exactly answered my issue as well.

    Kind Regards,