Mac local web-dev, step 1 – taming the Apaches

Apache configuration is via text files; well-documented and XML-ish, but still a bit of a black art (to me).  So, since I know I’m ham-fingered, and since I also know I’ve messed it up in the past, lets insulate myself from that sort of thing by stuffing /etc/apache2 into source-control.

1. Check http://localhost works – you should see a default apache “there’s nothing here yet!” page
2. Set up svn repo (I’m using webfaction.com – if you’re following this step by step, you could too, or use Assembla.com or xp-dev.com – be careful of storing credentials in public places, though, obviously!)
3. Create trunk in it
4. Checkout {repo}/trunk locally to {wc} – {wc} should be somewhere pretty permanent, we’re going to symlink to it later
5. Copy /etc/apache2 to {wc}/apache2; add everything, commit.
6. Stop apache – sudo apachectl stop
7. sudo mv /etc/apache2 /etc/apache2.untamed
8. Symlink: sudo ln -s /path/to/wc/apache2 /etc/apache2
9. Start apache – sudo apachectl start
10. Check http://localhost does the same as before – it should.

So.  Now, we ought to have apache2 set up on the Mac.  Now, I want to be able to develop against a local top-level-domain like foo.dev.  This part is shamelessly cribbed, but it’s useful to have this sort of thing in the same place…

1. Edit /etc/apache2/httpd.conf:
   1. Search for the log_module_config section, and:

      LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon
      CustomLog /private/var/log/apache2/access_log vcommon

   2. Still in the log_module_config section, comment out:

      #CustomLog /private/var/log/apache2/access_log common

   3. Near the end, uncomment the line:

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

2. Edit /etc/apache2/extra/httpd-vhosts.conf so it looks like:

   #
   # Use name-based virtual hosting.
   #
   NameVirtualHost *:80
    
   #
   # Mass Virtual Host configuration as taken from the Apache web documentation
   #
    
       # get the server name from the Host: header
       UseCanonicalName Off
    
       # include the server name in the filenames used to satisfy requests
       VirtualDocumentRoot "/Library/WebServer/Documents/%0"
       VirtualScriptAlias "/Library/WebServer/Documents/%0/cgi-bin"

3. sudo apachectl restart
4. Now, edit /etc/hosts and add something like:

   127.0.0.1 foo.local

5. Add a file index.txt to /Library/WebServer/Documents/foo.local
6. Hit http://foo.local/index.txt in a browser – you should see the contents of your file.
7. Commit config changes to source-control ;-)

So; we’ve now got the ability to set up a local staging site just by editing /etc/hosts.  Our virtual-host roots live in /Library/WebServer/Documents/{name} – you can change that if you like, but it’s fine for my own purposes.

Next, I want server-side includes (since this is the most common way for me to do small sites, at the moment).

1. Edit /etc/apache2/httpd.conf – add (or uncomment) lines to the mime_module section like:

   AddType text/html .shtml
   AddOutputFilter INCLUDES .shtml

2. Also edit the dir_module section to add index.shtml (and index.php, while we’re at it) to the DirectoryIndex line:

   DirectoryIndex index.html index.shtml index.php

3. Edit /etc/apache2/extra/httpd-vhosts.conf and add (at the bottom):

   	Options +Includes

4. sudo apachectl restart
5. Create index.shtml inside of your foo.local directory, and put the following inside of it:

   <!--include virtual="index.txt"-->

6. Hit http://foo.local/index.shtml and you should see the contents of your index.txt file.
7. Commit config to source control

You might find it useful (I did) to symlink /Library/WebServer/Documents to ~/Sites (move the existing Sites out the way) for convenience’s sake.

At this point, we should have Apache2 with server-side includes set up, as well as the ability to set up a new development site pretty much on a whim with a single edit to /etc/hosts. Not bad. Next post, I’ll run through MySQL and PHP (I’m on the clock, here ;-) ).