oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button

Apache Web Serving with Jaguar

by Kevin Hemenway coauthor of Mac OS X Hacks

Editor's note: Most people know that Mac OS X ships with a built-in Apache web server, but don't realize that it's easy to configure and run. In fact, you can host a web site in minutes, after completing just a few simple steps. But that doesn't mean that Mac OS X is a lightweight in this category. It's not. In fact, you can drill down and get very serious with this state-of-the-art serving software.

In this first installment of a (revised for Jaguar) multi-part series, Kevin Hemenway shows you how to start serving web pages directly from your Mac. In the articles that follow, he'll show you the techniques that system administrators use for maintaining robust web sites. As you read Kevin's tutorials, you'll learn the functions of some of those mysterious folders deep within your Mac OS X hard drive, and will soon become your own OS X sysadmin.

You stare at the screen, fingers twitching nervously. You've been telling the rest of the world how great Mac OS X is, basking in the sheer enjoyment of upgrading your Classic applications to jelly-powered delights. After much spouting, your boss has finally given you a chance to prove your saliva-laced rantings. The task is quite simple: "build the GatesMcFarlaneCo (see sidebar) intranet with features up the wazoo."

A rather stupid joke within a joke. McFarlane Toys is often considered the "one to beat" in action figures, and thus the loose association with Bill Gates. The combination of the two names resembles "Gates McFadden," who played Beverly Crusher on Star Trek: The Next Generation. Wil Wheaton, who played her TV son, Wesley Crusher, announced that he'd be reprising his role with a cameo appearance in the final Star Trek: TNG movie (the scene was eventually cut). Wesley Crusher is often regarded as the most-despised Star Trek: TNG character, and that's where we make full circle back to Bill Gates. Glad you wondered?

Once again, it's time to convince the herd about Mac superiority. What better way to begin than to use a well-respected web server that's proven its mettle time and time again?

Introducing Apache to the Mac Faithful

Apache is regarded as the most popular web server available today. With its incredible portability and support for anything you'd ever want to do, Apple wisely decided to ship Apache with its Unix-based operating system. With this web-serving powerhouse at your fingertips, I'll explain how you can impress your boss and solidify your love for Mac OS X, all at the same time.

Getting Started with Apache and Jaguar

The easiest way to begin Apache web serving is via your Mac OS X System Preferences. Click your Apple Menu, choose "System Preferences," and then select "Sharing." Within the Sharing preference panel you'll see a number of options, only one of which is of immediate value. See that "Personal Web Sharing" service? Simply select it and then click the "Start" button to fire up the built-in Apache web server.

Screen shot.
Apple has cleverly disguised the Apache web server as the "Personal Web Sharing" service in the "Sharing" System Preference.

By default, the Apache server has been configured to serve your personal web pages from a directory based on your Mac OS X "short" user name. (You can find your short user name in the "Users" preference panel. Click on "Edit User.") If your short user name is "morbus," for example, you can access your personal web site by opening any web browser on the local network and typing

That (also known as localhost) is pretty special--every computer has one. Both names represent the computer itself; by going to in a web browser, you are accessing the local Apache web server you activated in the "Sharing" preference panel.

But, how do make your web pages available to folks on the World Wide Web?

The answer is found back in your "Sharing" preference panel. Go there, click the "Personal Web Sharing" service, and note the IP address or hostname listed at the bottom of the window. Using that IP address or hostname is how outsiders can access your Apache server. If you see, visitors could access to view your personal web site (the exact IP/hostname you see will be specific to your Internet connection). In a future article, I'll discuss how to limit outside access to only those you deem worthy.

Note: In some cases, you may not be able to view your own web page when you access it via your IP or hostname (as above). This could occur for a number of reasons:

  • Your Internet provider deliberatively restricts access to port 80, the web-serving port. They often do this to prevent users from "running their own server," a common restriction listed in their Terms of Service. The quickest solution is to change the port Apache binds to, but we won't be explaining how to do that in this series--check the Apache documentation for tips.

  • Your Internet provider or network has a firewall or routing issue that blocks or restricts access to your internal web server (or entire computer). Since step-by-step solutions to this differ depending on your specific configuration, we won't be getting into them--talk to your network administrator.

  • Depending on your configuration and browser, you may not be able to browse your own web site, even though other outside users can see it fine. This seems to occur most often when using Internet Explorer, but it'll affect only local users (i.e., you)--your visitors would still be able to see your site, regardless of their browser or OS. Oftentimes, viewing your site via IP or hostname works fine in other OS X browsers, such as Safari or Mozilla.

Your Personal Web Space

If you went to your personal web site now, you'd see a generic introduction written by Apple describing Apache and how to use "Personal Web Sharing." We'll soon be deleting this page, but be sure to give it a read, because it contains some helpful bits of information.

Much in the same way your personal web site is based on your user name, so is the location of your web space in the Mac OS X file system. Continuing our assumption of the "morbus" user name, our current web space lives at /Users/morbus/Sites/.

If you browse there now, you'll see the introductory file (index.html), as well as an images/ subdirectory. Delete (or back up) everything, and use a text editor (such as BBEdit) to create a new index.html file with the following contents:

 <h1>Gleefully Served by Jaguar!</h1>

Upon saving, reload, and you'll see your rather bland, boring home page. This certainly isn't very impressive--downright pathetic, actually. You can't use server-side includes, can't install CGI programs to your Sites directory, and can't use PHP or mod_perl. Plus, your intranet is wide open to the Internet. Not so good, bub.

Related Reading

Mac OS X Hacks
100 Industrial-Strength Tips & Tricks
By Rael Dornfest, Kevin Hemenway

Turning on the Magic

What we've done so far won't impress anyone. We have no features and an ugly web site address filled with tildes and unprofessional user names. We've got a long way to go before we can feel good about showing off our masterful Mac OS X box.

Our first step is to give the site a prettier URL. Above, we placed our index.html file into our own user directory (such as /Users/morbus/Sites/)--now, we'll place a copy into Apache's DocumentRoot. The DocumentRoot is the default server (not user) location from which Apache will serve documents. For Mac OS X, this is located in the /Library/Webserver/Documents/ directory. This directory also has a default introductory file--to see it, visit (or http://localhost/) within your preferred web browser.

Localization or "Content Negotiation"

If you browse to /Library/Webserver/Documents/, you'll inadvertently run across another nice feature of Apache: content negotiation. Depending on your visitor, Apache can serve up international versions of your site--for example, index.html.en for English speakers, or French ( and German ( versions. Apache for OS X comes with over 25 translated versions of the default index.html file.

You can take advantage of this feature on your own pages. When you're creating the GatesMcFarlaneCo intranet in your native language, you can translate your pages into other languages and add the two-letter language encoding ("de" for German", "fr" for French, "es" for Spanish, etc.) to the file name. Any time international employees of GatesMcFarlaneCo access your intranet, they'll automatically be served the page that's in their native tongue (assuming their web browser correctly identifies their native language).

For now, back up or delete all of the files you see in /Library/Webserver/Documents/ and copy over the index.html file we created a few steps ago. If you return to, you'll see our "Gleefully Served" page.

What's Next?

This is a good point to catch your breath and play with what I've outlined here. You might want to build some nicer HTML pages to serve as your test site. In the next installment of this series, I'll tackle CGI access for your Apache server. Until then, enjoy!

Kevin Hemenway is the coauthor of Mac OS X Hacks, author of Spidering Hacks, and the alter ego of the pervasively strange Morbus Iff, creator of, which bills itself as "content for the discontented."

Return to Mac DevCenter.