Apache with virtual hosts, PHP and SSI on Mac OS X 10.6

For me, an essential web development tool is Apache. Regardless of whether I’m working on something that will actually be deployed in an Apache environment or just prototyping something that will be built on some other platform, having Apache enabled and with support for virtual hosts, PHP, and SSI makes things so much easier.

All of these things come built-in with Mac OS X, which makes it a great web development platform. However, none of it is enabled by default, and there are some configuration changes I like to make. I find that when I set up a new Mac or explain to a colleague how to do it, I need to look up what to change and stuff like that. To make that a little bit easier I thought I’d write a post with step-by-step instructions for my own future reference.

Please note that most of these instructions involve working in a Terminal window and I have written this with people comfortable with that in mind.

Start the Apache web server

Like I said, Mac OS X includes Apache, but it isn’t enabled by default. This is perfectly understandable since the vast majority of Mac users aren’t likely to need it or even know what it is. It’s easy to enable it though:

  1. Go to “System Preferences > Sharing” and check “Web Sharing” or open a Terminal window and enter sudo apachectl start. If you go through the Terminal you will be asked to enter the root password, which is most likely your own password if you’re the only user on your Mac.
  2. There is no step 2. If you open http://localhost/ in a browser you should see a page with the text “It works!”.

So far, so good, but to use Apache for web development there are some changes you will likely want to make. Exactly what you want to change depends on your particular needs, but here is the setup I use.

Virtual hosts

Unless you will only ever be working on a single site, you need a way to have multiple sites available. A convenient way is to create local DNS entries and virtual hosts.

Local DNS entries

First of all you’ll need a way to enter local DNS entries – yoursite.dev, test.local or whatever you prefer. You can add as many entries as you need by editing the /etc/hosts file:

sudo nano /etc/hosts

If you have BBEdit or TextMate installed you can replace nano with bbedit or mate to edit the file there instead of in nano. It’s useful to be familiar with nano though, so consider giving it a chance.

Once you have the hosts file open, you need to add a new row for each domain:

127.0.0.1    test.local

Use the IP address 127.0.0.1 since that points to your local machine.

Once you’re done, save the file and open http://test.local/ in a web browser. You should see the “It works!” page again. This is because Apache loads the default site. There are no virtual hosts set up yet, so everything points to the root site.

Create a site directory

Set up a new site by going to the Sites folder in your home folder and creating a new site folder with a single page:

cd ~/Sites
mkdir test.local
cd test.local
echo "This is test.local" > index.html

The folder should now have a file called index.html that contains “This is test.local”.

Create a virtual host

To make Apache load the index.html file you need to create a virtual host pointing to the folder you created. There are different ways of creating virtual hosts, but I like to use the configuration file associated with my account. It has the same name as your user and is located in /etc/apache2/users/. So let’s edit it:

sudo nano /etc/apache2/users/username.conf

By default this file contains the following:

<Directory "/Users/username/Sites/">
    Options Indexes MultiViews
    AllowOverride None
    Order allow,deny
    Allow from all
</Directory>

To enable a virtual host for the folder you created earlier, edit the file to make it look like this (replacing “username” and “test.local” with your username and the name of your folder):

NameVirtualHost *:80

<Directory "/Users/username/Sites/">
    Options Indexes MultiViews Includes
    AllowOverride All
    Order allow,deny
    Allow from all
</Directory>

<VirtualHost *:80>
    ServerName test.local
    DocumentRoot /Users/username/Sites/test.local
</VirtualHost>

Now save the file. To make the changes take effect you need to restart Apache by entering this in the Terminal:

sudo apachectl graceful

You could go to “System Preferences > Sharing” and toggle “Web Sharing” off and on if you prefer, but I find that going through the Terminal is much quicker since I always have at least one window open anyway.

Once Apache has been restarted, going to http://test.local/ should show “This is test.local”. Success!

Repeat these steps for each site you want to set up.

If you have no need for anything but completely static files, you can stop reading here. I normally want both PHP and SSI enabled though, so let’s look at how to enable those as well.

Enable PHP

PHP is also included with Mac OS X, but is disabled by default. To enable it you need to edit Apache’s configuration file:

sudo nano /etc/apache2/httpd.conf

Find the line that begins with “LoadModule php5_module” and uncomment it by removing the “#” at the beginning.

Restart Apache and verify that PHP works by adding a new file to your test.local folder:

cd ~/Sites/test.local
echo "<?php phpinfo(); ?>" > index.php

Loading http://test.local/index.php should display a whole lot of info about your PHP installation.

Enable SSI

Another option you may want to enable is Server Side Includes (SSI). To do this you can either edit /etc/apache2/httpd.conf to make the change apply to all users of your computer, or you can add a couple of lines to /etc/apache2/users/username.conf. I recommend the latter since it keeps your settings separate from the main server settings and makes them more likely to survive OS upgrades.

If you edit /etc/apache2/httpd.conf, find the mime_module section and uncomment the following lines:

#AddType text/html .shtml
#AddOutputFilter INCLUDES .shtml

If you edit /etc/apache2/users/username.conf, add those lines to the Directory directive instead:

<Directory "/Users/username/Sites/">
    Options Indexes MultiViews Includes
    AllowOverride All
    Order allow,deny
    Allow from all

    AddType text/html .shtml
    AddOutputFilter INCLUDES .shtml
</Directory>

Restart Apache and you should now be able to use SSI to include files.

Enable PHP and SSI in .html files

I personally like to keep all file extensions as html but still have the server parse them for SSI and PHP instructions. For SSI, add .html to the lines that enable SSI:

AddType text/html .shtml .html
AddOutputFilter INCLUDES .shtml .html

For PHP, also add the following line:

AddType application/x-httpd-php .html

Provided that you have made the changes to your user configuration file, /etc/apache2/users/username.conf should now look something like this:

NameVirtualHost *:80

<Directory "/Users/username/Sites/">
    Options Indexes MultiViews Includes
    AllowOverride All
    Order allow,deny
    Allow from all

    AddType text/html .shtml .html
    AddOutputFilter INCLUDES .shtml .html

    AddType application/x-httpd-php .html
</Directory>

<VirtualHost *:80>
    ServerName test.local
    DocumentRoot /Users/username/Sites/test.local
</VirtualHost>

That’s about it. You should now have Apache up and running, with virtual hosts and parsing of SSI and PHP in .html files.

Posted on April 28, 2011 in Mac, Productivity

Comments are disabled for this post (read why), but if you have spotted an error or have additional info that you think should be in this post, feel free to contact me.