A reliable nginx server block for a small static site comes down to four auditable choices: one exact domain, an absolute document root, a cache window, and a deliberate fallback. The Nginx Config Generator enforces those choices by rejecting anything that looks like a directive, a wildcard, or a path that mixes in whitespace, semicolons, braces, or shell-style variables. The output listens on IPv4 and IPv6 port 80, selects a single server_name, and stays local in the browser. Because the block is small and bounded, most deploy-time failures are not about syntax; they are about inputs and assumptions: paths that do not exist on the server, an expires header that outlasts a content change, SPA fallback enabled on a plain content site, or HTTPS tucked into a block that never carried certificate details. Treat the generator as a starter fragment, then review every directive against the installed nginx modules and the live deployment paths before you reload.
Inputs the generator actually validates
The tool builds one bounded HTTP server block from four required fields and a small set of optional controls. Looking at the product contract rather than guessing behavior, the checks are explicit.
- Domain. One exact host. Schemes, wildcard prefixes, alternate www entries, and regex forms are not added because each of those changes which virtual host answers and which certificate applies.
- Document root. An absolute POSIX path built from bounded safe characters. Semicolons, braces, whitespace, and shell-like syntax are rejected so user input cannot create extra directives.
- Cache duration. An integer between 1 and 365 days. Anything outside that range, or non-numeric input, is rejected.
- Fallback. A deliberate choice between a static 404 and an SPA fallback that ends in /index.html.
Optional inputs toggle gzip with the standard filter plus Vary: Accept-Encoding, list CSS, JavaScript, JSON, and SVG types, and depend on a small fixed extension list for the asset location covering CSS, JavaScript, common images, icons, and WOFF2 fonts. The generated output stays local to the browser and does not request the target server, so the path, ownership, and read permissions still have to be verified on the host itself.
Common mistakes that break deployment
Small static sites fail in predictable ways once the generator hands the file back. The pattern is almost always one of these.
- Treating SPA fallback as a default. Returning the home shell with status 200 for missing resources hides broken URLs, confuses monitoring, and damages error semantics. Enable SPA fallback only when client-side routing really does need to receive unknown application paths.
- Long cache durations on non-versioned assets. Visitors will keep stale files after a deployment. Fingerprint or version long-lived CSS, JavaScript, images, icons, and WOFF2 fonts before picking a high expires value.
- Trusting nginx -t as proof the site works. A passing syntax test covers directives and file references. It says nothing about permissions, DNS, application routing, certificate behavior, or response shape. A separate review of representative requests is still required.
- Asking the generator for HTTPS. Certificate paths, renewal tooling, supported protocols, redirects, proxy or CDN topology, and HSTS policy all depend on the live deployment. The block deliberately excludes TLS so it cannot invent dangerous certificate locations. Configure HTTPS through the hosting platform or a reviewed server procedure, then test HTTP-to-HTTPS behavior separately.
- Packing server_name with alternates. More than one exact name, or an implicit www redirect, changes which virtual host resolves. If several names should serve or redirect, design that behavior explicitly instead of expecting the generator to infer ownership.
- Pasting paths with shell tokens or trailing punctuation. Anything that looks like injection is rejected, but a path that is technically valid and still wrong on the host will pass validation and then fail at request time.
Most of these mistakes look invisible in the generated text and only surface under real requests. For a deeper pass on what makes a generated block survive live traffic, the walkthrough on getting an nginx config that actually works covers the same deployment pipeline from a different angle.
How to generate a deployable block
The generator is most useful when you follow a fixed review loop. Use these steps every time, especially before touching production.
- Enter one exact domain, an absolute document root, a cache duration between 1 and 365 days, and choose static 404 or SPA fallback deliberately based on whether the site uses client-side routing.
- Generate the block and review every directive against the installed nginx modules, the actual deployment paths, and the cache strategy for fingerprinted assets.
- Back up the active configuration, record the active include chain, and place the reviewed file in the correct context inside your nginx installation.
- Run nginx -t against the full configuration. Treat a passing test as confirmation of syntax and references only.
- Request representative paths: the home page, a deep static asset, a missing URL on a non-SPA site, an SPA path on a fallback-enabled site, and at least one gzip-eligible asset to confirm headers.
- Reload rather than abruptly stopping the service when the platform procedure supports it, keep a recovery shell open, and confirm error logs after reload.
- If the syntax test fails, do not reload. If requests fail after reload, restore the backup and inspect the error logs before trying again.
Directives the generator omits on purpose
The generated fragment is small on purpose. It does not include PHP, FastCGI, reverse proxying, WebSockets, uploads, authentication, rate limits, custom error pages, MIME include paths, logging, or security headers. Each of those depends on a specific application topology and cannot be inferred from a domain name alone. If you need any of them, add only the lines required by the actual architecture, verified against the core module documentation and the relevant module pages. Adding directives the generator did not emit is normal; adding directives you do not understand is the most common path to a broken reload.
| Scenario | Fallback choice | What real requests should show |
|---|---|---|
| Plain static content site | Static 404 fallback | Missing URLs return real 404 with the documented page rather than the home shell |
| Single-page app with client-side routing | SPA fallback to /index.html | Unknown application paths reach the SPA bootstrap with status 200, deep links resolve after hydration |
| Static site with fingerprinted assets only | Static 404 fallback, long expires | Hashed CSS and JS cache for the selected window, plain HTML does not, content updates after redeploy |
| Static site served behind a CDN or ingress | Not a generator use case | Configure the CDN or ingress instead; the generator is for a small static origin |
For gzip, the standard filter is enabled and adds Vary: Accept-Encoding for CSS, JavaScript, JSON, and SVG. HTML is handled by nginx gzip behavior without needing to appear in gzip_types. Compression can still create side-channel concerns for secrets reflected into compressed responses, and precompressed assets need different configuration. The gzip module documentation at nginx.org is the reference whenever the default list is not enough for the asset mix you actually serve.
Pre-deployment checklist
Before any reload, run a short checklist that matches the generator's limits. Save the current configuration and record the active include chain. Place the reviewed file in the correct context, then run nginx -t against the full configuration. Successful output only proves the parser is happy. Make sure the document root exists on the host with correct ownership and read permissions, that DNS for the chosen server_name resolves to the right interface, and that at least one static asset returns the expected expires and Cache-Control headers. Add server-side HTTPS configuration through the platform or a reviewed procedure, then test HTTP-to-HTTPS behavior on its own.
If the syntax test fails, do not reload. If a reload succeeds but representative requests fail, restore the backup and inspect error logs. Permanent cache and routing mistakes can affect visitors even when nginx stays online. Use the generator only when the problem really is a small static origin; for managed hosting, containers, Kubernetes ingress, or a CDN, the correct configuration surface is usually elsewhere. The most maintainable result is the smallest reviewed config that matches the deployment evidence on the day of release.