nginx for Mere Mortals

nginx (say "engine-x") is the web server and reverse proxy that already sits in front of a large share of the world's websites — and, quite possibly, in front of something of yours. It serves files directly, and for everything else it stands at the door: taking requests, handing them to the app behind it, and relaying the answers back.

People meet nginx two ways. You install it yourself to put something on the web. Or you inherit it: already running, already in production, config written by someone who left. This guide serves both meetings. It teaches the config grammar, the handful of jobs nginx actually does all day, and — just as much — what its error messages mean when it stops doing them.

If you know this series' Caddy guide: Caddy is the newcomer that automates certificates and fits its config on an index card. nginx is the older industrial standard — more explicit, more assembly required, and already installed everywhere. This guide cedes the automatic-HTTPS crown to Caddy and teaches the machine you'll actually find running.

This guide assumes you can use a terminal and know what a web app on a port is. Everything nginx-specific — contexts, locations, upstreams — is explained from zero.

What this guide covers

What nginx is — web server, reverse proxy, and the master/worker shape, in plain terms
Installing and layout — the package, /etc/nginx, and the two layout traditions
The config grammar — directives, blocks, contexts, and how settings inherit
Testing and reloading — nginx -t as a way of life, and reload without downtime
Serving static files — root, index, try_files, and the alias trap
Location matching — the precedence order, proven with fixtures
Reverse proxying — putting nginx in front of your apps, headers included
Redirects — return versus rewrite, and the canonical-host pattern
TLS — an HTTPS server block with a self-signed certificate, made with openssl
Logs — what nginx writes, where, and how to read it
Rate limiting — limit_req, and the phase gotcha that silently disables it
Upstreams and failover — more than one backend, and what happens when one dies
Troubleshooting — symptom → fix, with the real error messages
Glossary — the terms, collected in one place

What it doesn't cover

Writing web applications (nginx serves them; it isn't one), the commercial NGINX Plus feature set, and production hardening checklists. Getting a public certificate is covered as far as a lab can take it — the issuance step itself is marked (documented), because it needs a public domain and DNS that a lab doesn't have.

How to use this guide

Everything was run for real with nginx 1.24.0 (Ubuntu package) on a loopback lab: a static site, a two-backend proxy pool, a self-signed HTTPS server, a rate limit that really trips, and several failures caused on purpose and read in the error log. The lab runs as its own instance with its own prefix, so it never touches the system nginx; the shipped files in examples/ are the lab's actual config and backend. Two things are honestly different in the lab and flagged where they belong: the lab's worker processes run as root because this build machine refuses the file-ownership change nginx performs for any other worker user (a sandbox quirk, explained in chapter 2), and a public Let's Encrypt certificate is described, not issued. criteria.md keeps the full verification ledger.

Part of the series

This guide is one of the For Mere Mortals guides: plain-language guides to the tools programmers and makers use.

Related guides:

License

The writing in this guide is licensed under CC BY 4.0. Code examples and lab scripts are licensed under the MIT License.