You are about to be made very happy. Apache ships with OSX! This should be quite simple.
(note: you will need admin rights to your machine for this)

The simple…

Open your browser (oh, you already have) and go to:


That breaks for now, of course. So let’s fix that.

Open Terminal and enter the following (admin pw needed):

Now, try your browser again. Reload. Bingo. You are done. Well, putting content in is a bit challenging, but your web server is running.


Let’s make this a bit easier to work with…

Open finder and hit CMD-Shift-G (go to) and enter:

In there you will see httpd.conf, open that in an editor.

This is your configuration file for Apache — system wide. It has all kinds of goodies in there, and is extremely-well documented. For now, we are only concerned with a few items. First, let’s look at the “root directory” of your web server.

You will see a line like this:

That means, once we get things started “localhost” will load files from this location. I’d say leave it alone (for now) as all other typical installs look like this. Any research you do will mention this, so you are less likely to be confused.

Usually the next block will define basic settings for any “directory”

Then right after that you will see the specific definition for the “/Library/WebServer/Documents” directory (your root). It is very commented up so you can see what each thing does. It should be all set up fine, but I want you to know where things are defined.

It’s worth noting the last time I built this I ended up using the below as my definition.

Now for something you do have to change (or likely want to). First, let’s create a directory in your home folder.

Back to Terminal and enter the following:

What we are setting up is a simple place to host your own files. This will end up as a “user directory”; you know those http://domain/~username urls we used to see when Yahoo ran the web… Well, in any case, we’re setting that up for any quick tests you may want.

Now back to your text editor. We are looking for the line that looks like this:

Yours may not have the hash in the front (which means it is not used, or commented out). We want to remove the hash if there is one and save the file (admin password will be needed here).

If you saved, you will want to “reload” Apache. Back to Terminal and enter:

Now, back to the browser and load your personal website. You will have to enter your own username here


And COOL! Now you have a website. Anything you put in your “Sites” folder will be visible. Let’s do something about that for now.

Note: It is entirely likely that you will get a permission error at this point.

Do you see this?

Do you see this?



This is because Apache checks the entire path for proper privileges all the way up to root. So if you have your /Sites folder located at something like:


Each of those directories will have to have the correct permissions for Apache to serve information from.

You need to add both read and execute permissions to these directories. I usually start with my root folder and refresh the browser between each change to see if it was enough. So something like this: (note: you need to do this as root, thus the sudo)

Back to Terminal (since it’s open) and enter this:

Now, reload your personal site again and you should see you have a personal webpage too. You are truly ROXOR!


But what about dynamic content?

Okay, we have arrived at the super-cool. And you can do this in many ways if you’re comfortable with all the stuff I’ve explained so far. Basically, we don’t want to always have to put all of our source content into some static location (Sites). That sucks, we want the web server to work for us, where our code already is!

The Apache way

You can, of course, edit your httpd.conf file and add Virtual Directories. This is the best way if you want to be able to recreate your environment. That means all the “rules” are in files not on the file system itself. This requires the extra step of editing the conf file for any changes, but then you just have a file to back up and restore.

To do this look in the httpd.conf file for “alias_module”. It is a section that has examples to help you out. These are simple. To add a new one I usually enter something like:

Then bounce Apache. Simple.

Let’s get symbolic

There is another way to do this. Since we set up our server above (options block) to follow symlinks we can create symbolic links in the root folder of the web server.

Back to Terminal and enter all of this (password required at the end). Copy the whole block and paste it into terminal and hit enter.

Now head to your browser and go to:


Awesome. Lesson concluded. But let me explain that. We want to be able to put “pointers” to the directories of our source code into the “document root” of the web server (remember that’s in /Library/WebServer/Documents/). When we point at the root localhost web server and one of those directory names it simply follows the pointer to the location you set up.

These pointers are called Symbolic Links if you want to learn more about them. In Finder if you look at the “/Library/WebServer/Documents/” directory it will look like an alias (shortcut). It’s not. Without going into it, if you have new virtual directories you want to map I’d say just drop to Terminal and cd into the root directory and create a link (ln). For quicker reference here is what you would do:

That’s it!


Localhost no happy

So, in some cases (read when proxy settings are involved) you will need to add “localhost” to the list of domains NOT to look up. This setting can be found in Network Settings on the Mac.

Apple Menu / System Prefs / Network

Then select either WiFi or Ethernet adapter and click the “Advanced” button. Within the dialog that appears you will see “Proxies” and in that panel a “Bypass proxy settings…” text area can be found. Adding “localhost” in there makes sure that the machine always looks locally for that address.

Uh, auto-start?

Oh yeah, so Apache and OSX really like each other. They know how to respect one another. So if you “start” Apache it will actually stay in that state even between reboots. Once you “stop” it it will no longer auto-start. Awesome. Thanks Apple.

But just in case, here are your commands:

Congrats on becoming a guru.



Alright, so sometimes you will get a forbidden message when dealing with these links. Why is that exactly? Well, it has to do with how *nix checks access when Apache asks for data.

The simple answer is that you need a+x (executable to all) access all the way down the path (as far as I can determine). It’s easy to fix, but harder to identify. Pretty much I ls -lart starting at the top of the link’s path. So if the link points to

I usually start at ~/code and run this command

This will add the execution flag to that directory only. I then reload the browser to see if it took, and move to the next directory in the path if not.


Apache Directory Listings

So, you want the directory listings to be less 90’s nasty? Look no further. This one is easy.

First I will assume you have directory listing enabled on your server (or some folder). Great. Next we want to edit the httpd-autoindex.conf file found in the /etc folder. This defines your directory listings stuff. I’m going to make this one simple, but there is a lot you can do in here.

First find the “IndexOptions” line and paste this one in its place:

Also, at the bottom of the file drop this:

To be fair it can be anywhere, but it’s visible at the bottom.

And finally I like to remove the “readme” rule from the IndexIgnore. This is a list of items that will not show up when a directory is indexed.

Then, to complete the transformation download directoryListing and save it in your DocumentRoot (as defined in your main config file, referenced above). That will apply the new styles. And you’re off!


Notes for a later time:


Added to hpptd.conf file for icons to show in directory listing (no idea why it dropped)

Added for person projects virtual directory