h5bp/server-configs-apache: Apache boilerplate configs for performance and security headers

What h5bp/server-configs-apache actually ships

This is not an application and not a module. It is a set of Apache configuration snippets, plus a complete sample httpd.conf, a vhosts directory with templates, and a dist/.htaccess file that the package.json lists under "files". The README describes the goal plainly: configuration snippets that can help your server improve the website's performance and security, while also ensuring that resources are served with the correct content-type and are accessible, if needed, even cross-domain.

The audience is anyone who administers Apache directly. That includes people with root on a VPS or dedicated box, and people on shared hosting who only get a document root. The README splits those two cases explicitly: if you have access to the main server configuration file, usually called httpd.conf, you should configure Apache this way, because using .htaccess files slows down Apache. If you do not have that access, which the README calls quite common with hosting services, the .htaccess path is the fallback.

The repository layout reflects that split. The h5bp/ directory holds individual config snippets and combined files; basic.conf is described as loading a small subset of the rules to add expires headers, allow cross-domain fonts and protect system files from web access, and the README calls those rules the ones recommended to always be defined. The vhosts/ directory holds server definitions, and every file there with a .conf extension is loaded automatically unless it is dot-prefixed. The templates/ subfolder contains a VirtualHost template for secure and non-secure hosts, meant to be copied into vhosts/ with all example.com occurrences changed.

The mechanism: snippets you include, not a daemon

There is no runtime. Apache reads the config files at startup or reload, and the snippets are plain directives that take effect at that point. The data flow is: your httpd.conf (or a vhost file) uses an Include line to pull in h5bp/basic.conf or an individual snippet, Apache parses the resulting directive tree, and each request is then matched against those directives in the normal order.

That is why module availability matters so much here. The README lists nine modules that must be enabled for the configurations to have any effect: autoindex_module, deflate_module, expires_module, filter_module, headers_module, include_module, mime_module, rewrite_module and setenvif_module, each with its source file name such as mod_headers.c. A Header directive in a snippet does nothing if headers_module is not loaded. The README states this directly: some configurations won't have any effect if the appropriate modules aren't enabled.

The vhosts/ directory is loaded wholesale, which is a design choice worth noticing. Except if they are dot prefixed or non .conf extension, all files in this folder are loaded automatically. That means a half-finished vhost file left with a .conf extension will be parsed on the next reload. The README's own workflow works around this: you create .actual-hostname.conf with a leading dot, run sed to replace example.com, and only then move it to actual-hostname.conf to enable it. The dot prefix is the off switch.

Installing and enabling modules on Debian-style Apache

The README's standalone instructions target any distribution where apt-get was used to install Apache. The first step is enabling the modules the snippets depend on, in one command, and entering your password when prompted.

sudo a2enmod setenvif headers deflate filter expires rewrite include

After that, the README restarts Apache so the new configuration takes effect:

sudo /etc/init.d/apache2 restart

If you are on MAMP, WampServer or XAMPP, there is no shell step. MAMP PRO exposes an Apache tab where the modules must be checked; WampServer has an Apache section with a modules list, and the README notes it restarts the Apache service automatically after you enable a module. For manual installs, the README gives the config paths: /Applications/MAMP/conf/apache/httpd.conf, /Applications/XAMPP/etc/httpd.conf and C:\apache\conf\httpd.conf. You uncomment the required modules there and reset the stack.

To use the repository directly rather than as a reference, the README shows a clone-and-copy sequence that stops Apache first, keeps a backup of the existing apache2 directory, and then copies the repository contents over it:

apache2ctl stop
git clone https://github.com/h5bp/server-configs-apache.git /tmp/h5bp-apache
cd /usr/local
cp -r apache2 apache2-previous
cp -r /tmp/h5bp-apache/* apache2
# install-specific edits
apache2ctl start

The install-specific edits comment is doing real work. The README separately tells you to check ServerRoot, User, Group, ErrorLog, CustomLog and TypesConfig in httpd.conf, and to make sure the path for the mime.types file is valid. Copying the repository's httpd.conf over a working one without adjusting those values is the obvious way to break a server.

Validating a config change before it takes down the site

Apache gives you a syntax check, and the README puts it first in its own workflow. To verify the config:

apache2 -t

To verify a config with a custom file, the README gives the -f form:

apache2 -t -f httpd.conf

Only after that does it reload:

apache2ctl reload

This ordering is the part of the README worth following literally. A reload with a broken directive tree can leave the server refusing to start on the next full restart, and the -t check is the cheap way to catch a typo or a directive from a module you did not enable. Note that -t validates syntax, not intent: it will not tell you that you enabled expires headers on a path where you did not want them, or that a Header directive is being overridden later in the vhost. Those you confirm by inspecting response headers after the reload.

Managing vhosts with the templates folder

The README's site workflow is three commands. From the vhosts directory, you copy the template, rewrite the hostname, and then rename the file to drop the leading dot:

cd /usr/local/apache2/vhosts
cp templates/example.com.conf .actual-hostname.conf
sed -i 's/example.com/actual-hostname/g' .actual-hostname.conf
mv .actual-hostname.conf actual-hostname.conf

The dot-prefixed intermediate file is not loaded, so you can prepare a vhost and edit it without Apache picking it up mid-edit. The mv is the moment it goes live on the next reload. If you use this pattern, remember that the sed only substitutes the literal string example.com, so any other placeholder the template carries has to be handled by hand. The README does not document a rollback for a vhost that turns out to be wrong; the practical recovery is to rename the file back to its dot-prefixed form and reload, which is consistent with the loading rule but is not spelled out in the README.

Where this repository is the wrong tool

The clearest limitation is that the snippets are only as current as the last push, which was on 2022-12-05. The latest release listed is 6.0.0, dated the same day. Nothing in the repository moves on its own, and the README does not promise any update cadence. If your concern is a directive that changed behaviour in a later Apache release, or a new security header you want to set, this repository will not have anticipated it. You are adopting a snapshot and taking over maintenance of it.

Second, the .htaccess path is explicitly a compromise. The README states that using .htaccess files slows down Apache and points at the Apache documentation's own section on when to avoid them. If you have httpd.conf access, the repository's own recommendation is to use it. Choosing dist/.htaccess is choosing convenience over the faster path, and the README is honest about that trade.

Third, the module dependency list cuts both ways. Nine modules must be loaded for the full set to work. On a hardened or minimal Apache build, enabling rewrite_module or include_module may be exactly what your security policy forbids. The README does not offer a reduced variant for that case beyond pointing at individual snippets and basic.conf, so you would be selecting files by hand and checking each one's module requirements yourself.

Finally, there is a test/ directory and a .github/ directory in the repository, but the README does not describe what the tests cover or how to run them. If you want to know whether a snippet behaves as documented on your Apache version, the repository does not hand you a way to find out from its own documentation.

How it differs from writing your own httpd.conf

The realistic alternative is not another project. It is starting from your distribution's default httpd.conf and adding directives as you need them. The difference is in what you inherit. A distribution default is tuned to keep the server running and secure by default, and it changes when your package manager updates it. This repository is a curated set aimed at web-serving concerns: expires headers, deflate, correct MIME types, cross-domain font access and blocking web access to system files. It does not update with your package manager, and it does not adapt to your distribution's paths.

A second alternative is a configuration management tool that templates your Apache config from your own inventory. That gives you per-host variation and version control of your own directives, at the cost of writing every rule yourself. The h5bp snippets are the starting content you would otherwise have to research and write; the management tool is the delivery mechanism. The two are not mutually exclusive, and copying h5bp/basic.conf into a template is a reasonable way to use both.

The distinction that matters most: this repository is a set of files you copy once, not a dependency you upgrade. There is no package manager entry that pulls in new rules. The package.json exists mainly to publish dist/.htaccess, and its "files" array contains exactly that one path.

Licence, maintenance and what an upgrade would cost

The licence is MIT, stated in package.json and in LICENSE.txt at the repository root. MIT is permissive: you can copy the snippets into your own configuration, modify them, and ship them inside a product, provided you keep the copyright and permission notice. That matters here because the intended use is copying files into your server tree, which is exactly the kind of redistribution the licence permits. This is a description of the licence text, not legal advice; if you are embedding the configs in a commercial distribution, read LICENSE.txt and your own counsel's view.

The maintenance picture is simple and worth stating plainly. The last push was on 2022-12-05, and the latest release is 6.0.0 from the same date. The repository is not archived, so it remains readable and forkable, but nothing in the repository indicates ongoing development. Treat the snippets as a fixed baseline you own once copied. An upgrade, if a future release ever appears, would mean diffing your edited copies against the new files, because you will have made install-specific edits that the repository cannot know about. The README's copy sequence even creates apache2-previous as a backup, which is a hint about how the maintainers expect you to treat the directory: as something you replace wholesale and then re-edit.

Editorial conclusion

Adopt it if you run Apache and want a reviewed starting point for expires headers, deflate, MIME types and protected dotfiles, either by copying h5bp/basic.conf into httpd.conf or by dropping dist/.htaccess into a document root. Do not adopt it if you expect upstream to track new Apache directives: the last push was on 2022-12-05 and the latest release is 6.0.0 from the same date. Before wiring it in, run apache2 -t against your edited config, confirm the modules listed in the README are enabled (setenvif, headers, deflate, filter, expires, rewrite, include), and check whether your vhost already sets ExpiresDefault or Header directives that the snippets would duplicate.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes