About

Tool No. 62 of Pikkola

A server block is short, and its mistakes are quiet. A missing semicolon is loud, since nginx refuses the file, but an old protocol or a Host header left behind starts cleanly and breaks a password reset three weeks later. This page writes one block from a few choices, then reads any config back and names the lines worth changing.

What it does

What each preset writes

The three proxy presets differ in one line, the upstream: 127.0.0.1:3000 for Node, 8000 for Gunicorn, 8080 for Go. All three set Host, X-Real-IP, X-Forwarded-For and X-Forwarded-Proto, use HTTP/1.1 to the app so keepalive works, and close the read after sixty seconds.

The two build presets serve a directory. index.html is the index, an unknown path falls back to it, and a request for index.html itself is marked to expire at once, because a cached shell pins every visitor to the build they first loaded. Assets get a year, matched by extension, and a file that is not there answers 404 rather than the shell.

The WebSocket preset adds a map from $http_upgrade to a connection value, then sends Upgrade and Connection from that map instead of a fixed string. A fixed upgrade would hold an idle socket open for every ordinary request too, and the read timeout goes to an hour.

The redirect preset writes a second server that lists the old names and returns 301 with the path kept, so a link to a deep page lands on the same page under the new name.

Why the file is a whole nginx.conf

Two directives this page writes cannot live inside a server block: limit_req_zone and map belong to the http context. A server block on its own would fail to load with either one in it, and a reader would have to work out where to move them. So the file carries the http block too, with a comment at the top saying which lines belong there and which belong in conf.d.

What the switches add

SwitchLinesLeave it off when
TLSssl_protocols, session cache, the certificate pair, http2, a port 80 redirectSomething in front already ends TLS, or the host has no certificate yet
HSTSOne add_header with a two year max-ageThe domain is still being tried on plain http, since a browser remembers the header
gzipA level, a minimum length, vary, and the typesThe app compresses its own responses, which would double the work
BrotliThe same shape with brotli_typesThe nginx build has no ngx_brotli module
Rate limitA zone in http, limit_req in the location, 429 as the statusA crawler or a webhook has to be answered without a ceiling
Security headersCSP, nosniff, frame and referrer rulesThe app sends its own policy, since two would intersect
Static cacheexpires by extension, and index.html at onceThe site is proxied, so the app decides its own cache headers
SPA fallbacktry_files with index.html lastThe app serves real pages that should answer 404

How the linter reads

It tokenises the text: words, semicolons, braces, with comments dropped and quoted strings and ${variables} kept whole. Then it builds the tree nginx would build, and every finding carries the line of the token that caused it. A missing semicolon is found by the word that swallowed the next directive, which is why the report points one line above the line you would guess.

The thirty checks fall into six groups: braces and semicolons, TLS, the proxy, response headers, files and paths, and limits. A severity of fail means nginx refuses the file or serves traffic that a browser treats as broken. Warn means the file loads and the damage is quiet. Info is a line worth a second look.

What it cannot know: whether the file loads on your build of nginx, whether a module is present, what an included file contains, whether the upstream answers, or whether the certificate covers the name. nginx -t remains the test, and it runs on the host, not here.

What it deliberately does not do

Why it is free

A static page that computes in the browser costs almost nothing to serve, so there is no reason to charge for it. Pikkola builds small tools that do one job and keeps them free, with no account and no advertising.

Contact

A preset that should exist, a check that is wrong about a directive, a finding that is missing: hello@pikkola.com. Send the config you pasted and the line you disagree with.

Back to the studio