I’ve been griping all too much about this Apache-config thing. Yes, it’s been a thorn in my side for some time, but that was all of my own doing. In my search to take the most systematic, educational approach to understanding what the configuration does, I deluded myself into believing I could grok the entire system. That may be feasible for smaller systems or more immediate coding challenges, but when applied to a massive open-source software project like Apache, it’s foolhardy at best.
The good news is that I realized this, which led me to scale back my expectations appropriately. That done, I was able to accomplish what I had originally set out to do without too much trouble. To recap, I needed to configure the server software such that if I opened a browser and navigated to, say, http://mysite.local/, I would see the website I was developing on my machine. Technically, the default setup does something like this, but I wanted my working site to stand apart from other files on my computer — the goal was to make it appear as if it were actually online. The best way to do this is by setting up it up as a virtual host. What’s a virtual host? I’m glad you asked.
In the traditional view of a network, there are two types of machines: Clients and Hosts. The Host plays the part of a server: it’s the computer that actually has a resource (such as website files) on its hard drive. The Client is the user: it sends a request to the Host (such as: give me the page at “http://austinlivetheatre.com/“) to which the latter replies (by sending the contents of the requested page). It bears noting that this network anatomy has become much more complex since its inception — we now have fun things like proxy servers or peer-to-peer software (in which any computer could be playing both roles) — but it’s accurate enough for now.
For our purposes, the major shortcoming with such a network is that a host can house only one website. That’s clearly not a good organizational plan: imagine if we needed a separate server for every website in existence (not counting any redundant machines you would want). Enter virtual hosting: the means by which you can keep several websites stored on a single server. Then if clientA requests websiteX while clientB requests websiteY, if they both exist on the same server, the host will be able to respond correctly to both users without mixing up the data. (There’s a fun thought: imagine if the internet were like old telephone lines, when you might occasionally overhear someone else’s conversation. Oh, the hijinks that would ensue…)
As it turns out, virtual hosts (vhosts for short) are pretty easy to set up. At least, they have been in the [M/W/L]AMP software I’ve been using. If you’re interested in creating such a setup yourself, here’s how it’s done.
Step 1: Edit your hosts file.
You know how each networked machine has an identifying IP address, right? Usually, when you type the URL of a website, your computer uses DNS (Domain Name System) servers to figure out the corresponding IP address for the website (thereby telling it which server to contact). When developing locally, you want to bypass this process so that your URL never makes it out to the web, but instead gets brought right back to your computer.
You can set up this type of shortcut in your computer’s hosts file. It’s a plaintext document that stores URLs and the IP address at which they should be found. On any Unix system (Macs included), it’s located at /etc/hosts; on Windows, it’s buried in C:\Windows\system32\drivers\etc\hosts. Open it up and append a line like this to the bottom of the file:
This tells your computer that “mysite.local” should always be found at the IP address 127.0.0.1 (aka. ‘localhost’ — the machine on which you’re working right now), so there’s no need to look it up in DNS. Note: the “.local” bit isn’t necessary; I just like to keep a semblance of a domain name. You can type in whatever you want: “mysite,” “bob,” “google.com” (though I don’t recommend that one).
Step 2: Configure Apache
Now that you’ve made your computer stare at its own navel, let’s make sure we can put something interesting there. I’ve learned this procedure varies on different systems, so bear with me.
Windows WAMP & Mac MAMP
I group these two together because they are almost identical in terms of setting up vhosts (shocking, I know). First, open up your Apache configuration file, httpd.conf, in your favorite text editor. You’ll find them in:
- MAMP: /Applications/MAMP/conf/apache/httd.conf
- WAMP: C:\Program Files\WAMP\apache\conf\httpd.conf
Ignore everything unless you’re as foolhardy as I once was. Instead, just focus on finding a line like this one:
# Virtual hosts # Include /Applications/MAMP/conf/apache/extra/httpd-vhosts.conf
Uncomment the “Include” directive (just remove the ‘#’ character from the front of the line). This tells Apache to adhere to the configuration directives in the indicated file. With that done, go ahead and open that file: extra/httpd-vhosts.conf. In it, you will find a couple of example VirtualHost block directives. Go ahead and copy one (or edit it directly), so that it applies to your project. Here’s roughly what it should look like:
<VirtualHost *:80> ServerName mysite.local ServerAdmin firstname.lastname@example.org DocumentRoot "/Users/username/sitename" ErrorLog "logs/mysite.local-error_log" CustomLog "logs/mysite-access_log" common </VirtualHost>
You can read more about the individual directives in the Apache VHost Documentation, but for quick review:
- <VirtualHost *:80>: This opens the block, indicating that all following directives apply only to this vhost. To my knowledge, any Apache directive can be placed in this block, and it would affect only this one site. The “*:80” notation indicates that requests for this vhost will be coming in on port 80 (where HTTP traffic is usually received)
- ServerName: this is how Apache identifies the vhost. Make sure what you put here is identical to what you saved in your hosts file.
- ServerAdmin: This should be the email address (or a URL) for the server’s administrator. That’s you. This is included in error messages when something goes wrong.
- DocumentRoot: This is the path to the folder in which your site is stored. If your DocumentRoot is “/Users/username/sitename/”, then a request for “http://mysite.local/foobar.html ” will retrieve the file “/Users/username/sitename/foobar.html”
- ErrorLog: the location of the error log for this vhost. Whenever something goes wrong, the error will be documented here. Take note that by default, this path is relative (it doesn’t start with “/” or “C:/”) so the log will be in the Apache application folder.
- CustomLog: You may or may not get this, based on which Apache modules are already installed, but the idea is the same as for ErrorLog.
Make whatever updates you need, and save all those files.
Wait, seriously? You’re a Linux hacker and are coming to me for help? Ha; poor sod. Well, ok, I’ll do my best… but I recommend you start with this Slicehost article on Apache config files to get an idea of what you’re looking at, first.
I’ll assume you’ve successfully installed apache2 and can get it to run. To set up virtual hosting, have a look at all your config files in “/etc/apache2.” What should interest you here are the contents of sites/available/ and sites/enabled/. The former contains a separate config file for each vhost you want to be able to run; the latter contains all the vhosts currently running. Note that the contents of sites/enabled/ are actually just symlinks (symbolic links — shortcuts, essentially) into sites/available/, not duplicate files. Right now, both directories probably contain no more than a default example.
Go ahead and cd into sites/avaiable/. Make a copy of default (name it something useful, like the name of your site for instance). Now open it up and start customizing those directives. You’ll be faced with more initial options than the Mac & Windows users, but the important ones are the same: ServerName and DocumentRoot. Most others involve extra settings for specific directories within your system.
Once you’re satisfied and you want to enable the new vhost, run the command:
$> sudo a2ensite sitename
This will enable the site by creating the appropriate symlink in sites/enabled/. There is, of course, a corresponding command “a2dissite” to disable it.
Step 3: Restart Apache
On all systems, Apache reads its configuration files only when it starts up, so won’t notice any changes you make while it’s running. Restart it, however, and it’ll take into account any new directives you’ve added.
With all this done, you should be able to load http://mysite.local/ in a browser and see your very own site starting back at you. Well done, lads & lasses! Your new vhost is all set up.