by Chadwick Wood
November 5th, 2007
I'd like to share how I go about hosting development versions of websites on my Apple laptop (it's a 12" Powerbook G4). These instructions should work for anyone running OS X 10.3 and up (probably even earlier versions, as well). I'm talking about the regular OS X, not OS X Server.
The goal for these instructions is to be able to run a local version of a website, under a domain name of your choosing. Incredibly useful for development.
OS X comes with a distribution of the Apache web server, which is what we'll be using here. The first thing to do is to make sure Apache is running, which is really easy.
Just open your System Preferences (under the Apple menu) and select "Sharing" under "Internet & Network". Under the first tab there, "Services", you'll see a list of services you can have running on your computer. The one you want to turn on is "Personal Web Sharing". So, click the checkbox if it's not already checked. Voila, you're now running a web server.
By default, the web server on your mac uses /Library/WebServer/Documents as the root directory for the website it hosts at your IP address. In other words, if you put an HTML file named index.html inside this directory, then visit your IP address in a browser, you'll see that HTML file served up.
However, you want to be able to host multiple sites, because you have so many projects going on! So, you'll need one directory per website. For now you're just going to create one site, but this process can be repeated as many times as you want. Create a directory (let's call it "mysite") inside of /Library/WebServer/Documents. Inside that directory, put a file called index.html that has some HTML in it that you want to see. Ok, so now you've got a web page for testing, and you know where your site's files will be located.
Now you need to tell Apache about this website you're creating. Specifically, where that site's files are, and what its (development) domain name is.
First, you'll create a directory to hold your virtual host's configuration file. This can be wherever you want it to be. For me, I like to keep as many of the website-related files as possible in one place. Create a directory named "VirtualHosts" inside of /Library/WebServer/Documents. You can put all of your future virtual hosts' config files in this same directory.
Now you've created the directory, so it's time to create the virtual host configuration file inside of that directory. As a convention, I name a config file after the directory that holds that website's files, with a .conf suffix. So, start up your text editor of choice, and create a file named mysite.conf inside the directory you just created. The contents look like this:
DocumentRoot /Library/WebServer/Documents/mysite
ServerName www.mysite.dev
The first and last lines are just to specify to Apache that you're creating a virtual host. The middle lines are what you need to configure. The "DocumentRoot" line tells Apache where the files for the website are. The "ServerName" line tells Apache what the domain name for the site is. This domain name can be whatever you want, but to avoid clashing with real domain names out there on the web, I always use a made up top-level domain. In this case, .dev (seems appropriate to me). Again, this domain name is just for development. When your site goes live on the web, it'll have a different name (like www.mysite.com!).
One of the last steps in this part of the process is to tell Apache to read your virtual host config file. To do this, you'll need to edit Apache's main config file, which resides at /etc/httpd and is named httpd.conf. This file is owned by the root user, so you'll need to sudo in order to edit it. Also I highly recommend you make a copy of httpd.conf before you edit it, just in case you make a mistake (it happens to the best of us). For now, I'm going to assume you know how emacs, or vi, or some command line text editor here. Once you've opened httpd.conf, add the following line at the end of the file:
Include /Library/WebServer/Documents/VirtualHosts/*.conf
That is going to tell Apache to include all of the .conf files in your VirtualHosts folder when in starts up. So, whenever you add more virtual host config files to that folder in the future, all you need to do is restart Apache, and it will read them. Speaking of which, save httpd.conf, and then we need to restart Apache so that it sets up our virtual host. You can do this a couple of different ways. For one, you could go back to the "Sharing" screen in System Preferences and stop, then start Personal Web Sharing. But the much slicker and faster way to do it is from the command line:
sudo apachectl graceful
You'll need to enter your root password. apachectl is a command-line tool for manipulating the Apache web server. In this case, we're telling it to gracefully restart itself. If you get an error when you run that command, it means you made a mistake, either in your httpd.conf file, or one of your virtual host config files. If things get hairy, you can always replace httpd.conf with that copy of the file you made before you changed it. Right?
Ok, you've made the virtual host... now we want to visit www.mysite.dev!
Maybe you just went to www.mysite.dev in your browser. If so, you probably got an error page. That's because your computer doesn't know how to find www.mysite.dev, yet. It asked some DNS server where www.mysite.dev is, and the server told it "never heard of it". To avoid this, you need to edit your hosts file. It's named "hosts" and lives in /etc. Again, this is a root-owned file, so you'll need to sudo in order to edit it. So, open up /etc/hosts and add the following line at the end:
127.0.0.1 www.mysite.dev
Your computer uses the hosts file to match up domain names with IP addresses. You can read more about that here, if you want. Save the file. Our last step is to tell your computer to re-read the hosts file you just edited. One last command in Terminal:
sudo lookupd -flushcache
Ok, now open up your web browser of choice and visit www.mysite.dev. There it is! Keep in mind, only your computer knows about www.mysite.dev. So, this is just for your own testing purposes during development. If you want to share your work with someone else, you'll need to do some more work which I'm not covering here, or you'll need to put your work out on the web somewhere. But for local development purposes, this works great.