h5bp/server-configs-nginx: A Drop-In Nginx Config Baseline

What h5bp/server-configs-nginx Is Actually For

Most Nginx installs start from a distribution package that ships a minimal nginx.conf and a default server block. That gets you a working server. It does not get you expires headers on static assets, a MIME mapping table that covers modern font and media types, cross-domain access rules for fonts, or protection against serving dotfiles and system paths over HTTP. Those rules are individually short and collectively easy to get wrong, and they are the same on almost every site.

h5bp/server-configs-nginx exists to hold that shared layer. The README describes it as "a collection of configuration files 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 an engineer who already understands Nginx request processing and wants the boilerplate out of the way. If you have never written a server block, the repository links to the Nginx Beginners Guide and the request processing docs rather than teaching those itself.

Repository Layout and the Include Mechanism

The design is a set of directories that Nginx loads by glob, plus a library of snippets you include by path. The README gives this structure:

./
├── conf.d/
│   ├── default.conf
│   └── templates/
├── h5bp/
│   ├── basic.conf
│   ├── location/
│   └── .../
├── custom.d/
│   └── .../
├── mime.types
└── nginx.conf

conf.d/ holds server definitions. Any file in it is loaded automatically unless it is dot prefixed or does not end in .conf, which is how the repository implements site enable and disable: renaming a file with a leading dot takes it out of the config without deleting it. custom.d/ works the same way for custom nginx.conf configuration. mime.types maps file extensions to MIME types, and nginx.conf is the main file.

The h5bp/ tree is the interesting part. It splits into individual config snippets and combined files. basic.conf loads what the README calls a small subset of the rules, adding expires headers, allowing cross-domain fonts and protecting system files from web access, and it is described as the set recommended to always be defined. The location/ directory holds files that each contain one or more location directives, meant to be included in the server context or inside a nested location block. That is the whole architecture: no daemon, no generator, no templating engine beyond the example.com substitution described below.

Installing It Directly on Ubuntu or Any Nginx Host

There are two documented paths. The reference path has no install steps at all: download or check out the repository, read the snippets, and copy the parts you want into your existing configuration. The direct path replaces your Nginx config directory with the repository. The README shows the sequence for a host where Nginx config lives at /etc/nginx:

nginx -s stop
cd /etc
mv nginx nginx-previous
git clone https://github.com/h5bp/server-configs-nginx.git nginx
# install-specific edits
nginx

Stopping Nginx, moving the old directory aside and cloning into /etc/nginx means a failed start leaves you with a server that is down rather than one running the old config. The comment between the clone and the start is doing real work: before you run nginx, edit nginx.conf so that user, error_log, pid and access_log match your install. Those four keys are the ones the README singles out, and they are the ones most likely to differ between a package install and this repository.

Verify before you reload, not after. The README gives both forms:

nginx -t
nginx -t -c nginx.conf

The first tests the default config path, the second tests a specific file. Once the test passes, applying changes is a reload rather than a restart:

nginx -s reload

For individual sites, work inside conf.d. The templates/ folder holds a server template for secure and non-secure hosts, and the README's workflow copies it, rewrites the placeholder hostname, then enables it by removing the leading dot:

cd /etc/nginx/conf.d
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

After that, nginx -s reload picks up the new server block. To take a site offline without deleting its file, move it back to a dot-prefixed name and reload again.

Where the Snippet Approach Breaks Down

The repository is a config tree, not a configuration management tool. Replacing /etc/nginx with a git clone means your live configuration is a working copy of a public repository, and the README does not document a rollback path, a merge strategy for upstream changes, or how to reconcile local edits with a later release. The nginx-previous directory from the install sequence is the only recovery artifact mentioned, and nothing in the README tells you when it is safe to delete. If you have more than a handful of hosts, that gap is the reason to use the repository as a reference and keep your own templating layer on top.

Version support is broad but not unlimited. The README states support for Nginx v1.8.0 and above. It does not enumerate which directives in the snippets require which Nginx version, so on an older 1.8.x build you are testing rather than reading your way to confidence.

There is also a collision risk that the README does not address. conf.d/ ships a default.conf, and every non-dot .conf file in that directory loads automatically. If your distribution already defines a default server, or if you add your own site files without disabling the shipped default, you can end up with two server blocks competing for the same listen directive. The repository gives you the enable/disable-by-renaming convention; it does not tell you to apply it to default.conf.

The last boundary is scope. Nothing here configures TLS certificates, upstream load balancing, application proxying or rate limiting. Those are the parts of an Nginx config that are specific to your deployment, and the repository deliberately stays out of them. If that is what you came for, this is the wrong tool.

How It Compares to Writing Your Own Baseline

The obvious alternative is not another project. It is the nginx.conf and default server block that your distribution package installs, extended by hand. The difference in approach is maintenance ownership. A distribution default is written to be safe on any host and is updated when the package updates; it will not add expires headers for you, and its MIME table reflects what the packagers chose to ship. h5bp/server-configs-nginx is written to be a reviewed baseline that you adopt wholesale and then track yourself, with the h5bp/ snippets available individually when you only want part of it.

That distinction matters at upgrade time. Package updates to Nginx do not touch your config, so a hand-written baseline drifts silently as you add sites. A cloned repository drifts the other way: upstream changes arrive only when you pull them, and the README does not describe that process. The repository's own release history is the signal to watch, with 5.0.1 published on 2023-07-23, 5.0.0 on 2022-12-05 and 4.2.0 on 2022-02-24. The last push to the default branch was on 2026-06-20, so the tree is being touched, but the tagged releases are the stable points you would pin to.

Licence and the Cost of Keeping It Current

The code is MIT licensed, stated in the README and shipped as LICENSE.txt at the repository root. MIT is permissive: you can copy snippets into a proprietary configuration tree, modify them and ship them, provided the licence text travels with the code. If you vendor individual h5bp/ files into your own repository, keep the licence file alongside them. This is a description of the licence terms, not legal advice; if your organisation has a policy on third-party code, route it through that process.

Upgrade cost is the practical question. Because the repository is a config tree rather than a package, there is no dependency manager to tell you a new version exists. You either watch the releases page or pull the branch. The README's install sequence overwrites /etc/nginx, so a later upgrade means reapplying your install-specific edits to nginx.conf and re-checking any site files you wrote. The test/ directory at the repository root, combined with the Server CI workflow referenced by the badge in the README, indicates the project validates its own configuration; that is a reason to trust the snippets, not a substitute for running nginx -t on your host.

Editorial conclusion

Adopt h5bp/server-configs-nginx if you run Nginx 1.8.0 or newer and want a reviewed baseline for expires headers, MIME types and system-file protection instead of writing those rules yourself. Do not adopt it if you expect it to configure TLS, upstreams or application routing; the repository is a set of snippets and a directory layout, not a deployment system. Before replacing /etc/nginx, run nginx -t -c nginx.conf against a copy, confirm the user, error_log, pid and access_log values in nginx.conf match your install, and check whether conf.d/default.conf collides with your existing server blocks.

Frequently asked questions

Official sources

1. h5bp/server-configs-nginx on GitHub
2. Issues
3. License: MIT
4. README
5. Releases