A modular approach to Apache configuration

The traditional way to configure Apache is to take the httpd.conf file shipped with your distribution and start changing it to your local needs; for example, so that the DocumentRoot and ServerName are right. This is simple and attractive, until you have to upgrade.

The big problem with this approach is that httpd.conf has two sorts of settings; it mixes together settings that you want to customize, like DocumentRoot, with Apache internal things, like AddLanguage and AddCharset. With them all jumbled together, upgrading can be an exercise in annoyance in merging two sets of changes together.

After burning my fingers once too many times this way, I've switched to a different, more modular approach. The basic idea is that the only changes I make to httpd.conf are to comment out things that I need to change. Plus an 'Include hosts.d/*.conf' line at the end.

All of the actual changes and any new settings go into files in hosts.d. These range from global settings like additional AddType declarations to the configuration of a particular website, setting its DocumentRoot et al. These files tend to be very short, because Apache configuration is actually not all that complicated.

Upgrading is a snap: just take the new httpd.conf and comment out all the site specific stuff again (and add the hosts.d inclusion). When necessary, change the hosts.d files for new syntax or new options or the like.

Modularizing this way also clearly shows your important local settings: they're the ones you have in files in hosts.d. You can easily say 'stock, except for this'. You can modularize more finely; we have a hosts.d file for our pubcookie setup, which makes it easy to see which settings are pubcookie specific.

(And don't underestimate the use of having a single place to see all of the directories that a website uses.)

Sidebar: an alternative approach to upgrades

Now that I write this, it occurs to me that this is an ideal situation for a branching version control system, since what you want is more or less a three way merge between the old vendor httpd.conf, the new vendor httpd.conf, and your changes to the old vendor version. And the changes should almost always be non-conflicting, which makes merges simple.

I believe there are even standalone three way merge programs, so you could just save a copy of the stock vendor httpd.conf before you start editing it, instead of setting up a VCS environment.