Ka of Isis is not optimized for this version of Internet Explorer
25 August, 2008 | Filed under “Apache on the Macintosh”
Note: This tutorial is for Apache HTTP Server Version 2.2.6 as installed with Mac OS X 10.5 (Leopard). It was last tested with version 10.5.4 of the operating system.
There comes a time when the sleeping indian must be awakened. For me it became necessary when I wanted my humble computer to second as a local web host for a content management system (CMS). Said computer is not always connected to the Internet so I need to simulate the normal situation where the CMS is installed on a remote server somewhere in the triple w jungle.
With Apache server software preinstalled on every Macintosh, it is mostly a matter of enabling the functionality to take advantage of it. Apple has even created a default site with an index.html file and an images folder on your system hard disk:
Users > user_short_name > Sites
It might be a good idea at this early stage to check if you are able to fire up the default Apache installation. If it does not work out of the box it will most certainly not work post modification, will it?
Go to System Preferences… and click on the Sharing icon. You enable Apache by checking Web Sharing (you may have to click the lock to make this change). A green light should go on and two web adresses should become visible, one for your computer’s website, one for your personal website. Try both of them. The first address should take you to a page with an Apache logo, the second to a page with a gradient background and the heading “Your website.”. You should also be able to reach the first page if you enter http://localhost/ or simply localhost in the address field of an empty browser window.
OK? Turn web sharing off and close the system preferences window.
Important: In your browser, clear history and empty cache to avoid ghosts of evil past. You do not want the browser to show old pages when you test up ahead. This cleanup procedure should be a routine you carry out every time web sharing is disabled.
You can read more about how to replace your personal site’s contents with your own – and how to let the rest of the world view your site (should you be so inclined) – in Finder’s help section:
Finder > Help > Mac Help > Sharing a website on your computer
So, why a tutorial?
Well, if you are anything like me – may the gods have mercy on your soul – you prefer to make your own decisions as to where files are stored on your hard disk(s). Me, I always partition the disks – a step which precedes the operating system installation. Each partition is dedicated to a particular task. The system, applications and utilities all go on one partition. Several partitions are used for film projects, builds for DVD creation, or musical compositions (and if you have ever stumbled upon the dreaded “dropped frames” message in Final Cut Pro, you will do your utmost to keep the video partition defragmented – easy to accomplish between projects with the Erase button in Disk Utility). Still other partitions are used for static content (logos, templates, archive images etc.), Windows installations where I test web sites with Internet Explorer, or the daily bread. Thus inclined, it only figures that I would crave a separate web server partition.
Note: In place of a dedicated partition you could alternatively use a slave disk or an externally connected FireWire disk.
Following this line of thought you should now prepare a directory for your local web sites (yes, you can have more than one). If your dedicated partition is named, say, Web, create a folder on the top level of Web and name the folder, say, ApacheSites. In this folder will ultimately go your different web sites. The full path is:
Web > ApacheSites
Note: You could drop each of your web site folders directly on the top level of Web, but with a parent folder, ApacheSites, you will later have a convenient place to store a file with user names and passwords for protected directories. I guess there will be more on that in a future tutorial.
For this walk through, create three new folders inside of ApacheSites and name them Cochise, Geronimo, and Victorio, respectively. Their paths are:
Web > ApacheSites > Cochise
Web > ApacheSites > Geronimo
Web > ApacheSites > Victorio
For testing later on, create three different, simple HTML index pages and save them thus:
Web > ApacheSites > Cochise > index.html
Web > ApacheSites > Geronimo > index.html
Web > ApacheSites > Victorio > index.html
How then to tweak Apache to recognize and serve such non-default locations?
On an earlier occasion I had been struggling with the implementation of Server Side Includes with Dreamweaver and in my quest I went looking for a file called httpd.conf. I had found several references to this document, so why not give it a try? Easy said, but where the heck was that file? Search to no avail. There simply was no file with that name on my hard disk. The words of David Ogilvy, the late advertising guru, were called to mind (and I site from memory here): “Telling pigs that truffles are delicious is fine and dandy, but it helps to also tell them that the fungus thrives in oak forests.”
It finally dawned on me that the evasive configuration file must be one of those hundreds of invisible files and folders hidden from prying eyes. The reason they are hidden is that they often contain stuff for the operating system and the casual user can cause havoc should he mess with them or delete them altogether.
Now, there are tools out there capable of making invisible X-files (sorry, I could not resist that one) visible. I have earlier, and successfully, used InVisibles with Mac OS X 10.4 (Tiger) and there are several other scripts and applications that come and go. A search at Versiontracker reveals (pun intended) many of them but they are not necessarily upgraded for your version of Mac OS X. The Terminal can be employed to show or hide invisible files and the commands involved can be polished and turned into scripts for Finder with Apple’s Automator application. But – in Finder you can actually get to the file in question by way of the keyboard shortcut shift-command-G or via Go > Go to Folder… and then typing out the path to the file. An example:
Go > Go to Folder… > /private/etc/apache2/
This approach is arguably the easiest one, but it requires that you know the path. Anyway, once revealed in Finder, the file can be opened with the proper tool.
Note: It is strongly recommended that you backup any file prior to modification. Should you nevertheless mess things up, please know that you can at least download a copy of the original httpd.conf from the Downloads section.
Throughout this tutorial you will perform slight modifications to configuration files. These files are plain text documents, so why not kill two birds with the same stone?
I have often wondered why the good people at Bare Bones Software compete with themselves by making so many features of their commercial product BBEdit available in the free-for-all TextWrangler. If it is not already in your arsenal, download this no strings attached, general purpose text editor, fire it up and choose:
File > Open Hidden…
With All Files enabled, go down the following path on your main harddisk/partition (in Figure 1 that is “X” on my system) and open the hosts file:
X > private > etc > hosts
Fig. 1. Searching for what is not there.
Buried in the Apache-documentation is the following piece of information: “If you want to maintain multiple domains/hostnames on your machine you can setup VirtualHost containers for them. Most configurations use only name-based virtual hosts so the server doesn’t need to worry about IP addresses.”
This is where your hosts file enters the stage.
The subject on virtual hosts has been exploited in detail by both Steve Stringer and David Powers. They approach the subject differently, though, and with slight variations in the code. Personally, I am no “sudo” wrestler so I tend to shy away from the Terminal and UNIX commands. Let us stick with TextWrangler and see if we can create hosts for our three sites.
For easy reference to the code in the file, make line numbers visible in TextWrangler:
View > Text Display > Show Line Numbers
The first thing you may have noticed with hosts open in TextWrangler, is the pencil icon with the red slash across it. This tells you that the file is locked for editing.
Fig. 2. Scary stuff.
But fear not; the document is modifiable. Click on the icon. When asked to mess with root, don an evil smile and hit him square in the <Unlock>.
Fig. 3. Even scarier stuff.
On to the fun part.
Line 11 in hosts is empty. Enter the following comment (and you tell Apache that it is a comment by preceding everything with a hash character):
# My local sites
On three additional lines (12, 13, and 14) enter references to three virtual hosts. In so doing, be smart and follow a naming convention which honours the three sites you have already prepared on the dedicated web server. Leave a space between the group of numbers and each name:
127.0.0.1 cochise
127.0.0.1 geronimo
127.0.0.1 victorio
In the future, whenever you want to add a new site, this is where you give it a name. For now, save the file (this requires administrator name and password) and close it.
With the naming of each site taken care of, it is (almost) time to tell Apache where they reside. This is done in a file called httpd-vhosts.conf. Apache, however, stores information in bits and pieces “all over the place”, so before you can configure the virtual hosts, you need to include httpd-vhosts.conf. This, as it turns out, is done in httpd.conf. So, open the latter:
X > private > etc > apache2 > httpd.conf
Uncomment line 461 to read:
Include /private/etc/apache2/extra/httpd-vhosts.conf
Save the change made to httpd.conf and close the document.
Now open httpd-vhosts.conf:
X > private > etc > apache2 > extra > httpd-vhosts.conf
Before you make any modifications to this document, please note the link to additional information in line 10. This is stressed by both Stringer and Powers and the former emphasized the following quote: “If you are adding virtual hosts to an existing web server, you must also create a <VirtualHost> block for the existing host. The ServerName and DocumentRoot included in this virtual host should be the same as the global ServerName and DocumentRoot. List this virtual host first in the configuration file so that it will act as the default host.”
Take a deep breath and replace the original lines 28 through 33 with the following two lines:
DocumentRoot "/Library/WebServer/Documents"
ServerName localhost
To add your “first” web site, replace the original lines 37 through 41 with the following two lines:
DocumentRoot "/Volumes/Web/ApacheSites/Cochise"
ServerName cochise
Note: The /Volumes reference should take Apache one step up and out of the main/default directory before it is sent headlong down into the Web directory and below.
In the same vein, add Geronimo and Victorio, and your modified httpd-vhosts.conf document should read (from line 27 and down):
<VirtualHost *:80>
DocumentRoot "/Library/WebServer/Documents"
ServerName localhost
</VirtualHost>
<VirtualHost *:80>
DocumentRoot "/Volumes/Web/ApacheSites/Cochise"
ServerName cochise
</VirtualHost>
<VirtualHost *:80>
DocumentRoot "/Volumes/Web/ApacheSites/Geronimo"
ServerName geronimo
</VirtualHost>
<VirtualHost *:80>
DocumentRoot "/Volumes/Web/ApacheSites/Victorio"
ServerName victorio
</VirtualHost>
Save the changes made to httpd-vhosts.conf and close the document.
Important: If you create a site (aka folder) on your web server and name it with spaces in the name, e.g., My new site, the standard reference to virtual hosts in httpd-vhosts.conf will not recognize the site. There are two possible solutions to this problem:
My_new_site or MyNewSite.httpd-vhosts.conf file:<VirtualHost *:80>
DocumentRoot "/Volumes/Web/ApacheSites/My new site/"
ServerName mynewsite
</VirtualHost>
You are ready for an intermediate test of Apache and your local web servers.
Repeat the description in Part 1 to activate web sharing. This time, however, do not follow the links in the Sharing window but close the window altogether. Then, in your browser, enter localhost. This should, as before, load the default Apache site. So far, so good.
If the World was a place without borders, you should have been able to load your Cochise site by entering the following address:
http://cochise/
But if you try that your browser will throw up the following message: “Forbidden. You don’t have permission to access / on this server.”
What is happening? Well, out of the box, Apache serves from the default directory but not from a higher directory. When you specify a site path beginning with /Volume in httpd-vhosts.conf, you are one step ahead of Apache. It is interesting at this point to visualize the problem. Hit shift-command-G in Finder and go to the folder /Volumes. In column view you will see a hidden folder – Volumes – on your main partition. This folder contains alias links to all of the mount points of volumes stored on your system (i.e., connected to it); this includes external FireWire drives, USB Flash memory sticks etc. The Finder hides the Volumes directory from view, but displays its contents at the computer level:
Fig. 4. Mount points of volumes.
All roads lead to Rome, the saying goes, and what follows is a proposed route to get Apache out of root (pun not intended). First off, open the following configuration file:
X > private > etc > apache2 > extra > httpd-userdir.conf
You will not make any changes to this file, only learn from line 15:
Include /private/etc/apache2/users/*.conf
In plain English this means that Apache will include (i.e., read and honour) every configuration file stored in its users folder. Go and have a look in that (hidden) folder now. If your short name for login is mary, the folder should contain the document mary.conf:
X > private > etc > apache2 > users > mary.conf
Incidentally, every time a new account is opened on your Macintosh, a corresponding user will be added to the Apache users directory. For instance, if you allow Kilroy to log in to a new account with a short user name of kilroy (he might have been there already, but that is another story altogether), a kilroy.conf file will be saved to the directory.
Close httpd-userdir.conf and in its place, open mary.conf. You will see a directory path:
/Users/mary/Sites/
Initially, with no modifications to a default installation of Apache on Leopard, this is the personal web site which will be served. More specifically, the index.html file in the Sites directory will be opened:
X > Users > mary > Sites > index.html
For Kilroy the path would be:
X > Users > kilroy > Sites > index.html
You could in fact change the Apache directories to /Users/mary/had/a/little/lamb/ and /Users/kilroy/was/here/, respectively, and deposit the index files in corresponding folders on your hard disk. But I digress. What you will do is add configuration files for your new web sites on that dedicated hard disk partition.
In Finder make a copy of mary.conf. Change Line 1 to read:
<Directory "/Volumes/Web/ApacheSites/Cochise/">
and temporarily save the file as cochise.conf. Once more change the first line, this time to:
<Directory "/Volumes/Web/ApacheSites/Geronimo/">
Save the file as geronimo.conf. Finally change the line to:
<Directory "/Volumes/Web/ApacheSites/Victorio/">
and save the file as, yes, victorio.conf. Close the file and drag copies of the three files to Apache’s users folder (you need to authenticate). Delete the temporary documents.
You are at the gates of Rome. One final test and you will be inside:
If web sharing is running, turn it off and then on again so that Apache can include your latest additions. In the browser, clear history and empty cache and do the localhost test as before. The page with the Apache logo loads. Now, redo the “cochise” test with:
http://cochise/
When your especially prepared index page successfully loads, you can breathe out; you know that the remaining two sites will also work:
http://geronimo/
http://victorio/
Know also that you can get away with just typing and entering cochise, geronimo or victorio. It could never be more easy. And did you wonder where the 127.0.0.1 came from? Try it as an address! Localhost, right? Or vice versa, actually.
To conclude, these are the steps necessary to add a site to a non-default server:
httpd.confhostshttpd-vhosts.confusers folder every time a site is added: A *.conf file where the asterisk should be replaced with the name of the configuration fileAnd: If you delete a site, delete all references to it as well.
The Apache Server documentation states that “The name ‘Apache’ was chosen from respect for the Native American Indian tribe of Apache … Secondarily, and more popularly (though incorrectly) accepted, it's a considered cute name which stuck. Apache is ‘A PAtCHy server’. It was based on some existing code and a series of ‘patch files’.”
Wired has it the other way around, however, and they tell the story of eight programmers who “found each other on the Net and began exchanging ideas, changes, and fixes”.
Ultimately, this is how legend is born – and it properly wraps up this small installment on how to tweak you local server software.
What’s next? PHP is what, and you can be up and running in a few steps.