Skip to content

SYSTEM Cited by 1 source

nginx

nginx is a high-performance open-source HTTP server + reverse proxy. Dominant choice for edge-facing web tiers at engineering orgs that want a small, predictable static-hosting / proxy primitive rather than a full application framework. Event-driven, C-implemented, minimal per-connection memory footprint. Canonical use-shape in this wiki: front the stateful origin and do the routing decision in a small amount of embedded logic.

Features load-bearing on wiki coverage

  • proxy_pass — reverse-proxy to an upstream; URL can include variables set earlier in the request lifecycle. GitHub Pages uses proxy_pass http://$gh_pages_host$request_uri where $gh_pages_host is set by a Lua router — stock-nginx, one line, all the routing smarts live in the Lua variables.
  • ngx_http_map_module — static key→value mapping inside the config (e.g. hostname → backend). Loaded at config time; works well when the map fits in memory and changes slowly. Canonical wiki failure-mode: GitHub Pages pre-2015 had the map regenerated by cron every 30 minutes + reloaded; cold-restart cost scaled with map size, publish latency was the regen cadence. Static maps are wrong when the key-space grows or changes often; move the lookup to per-request DB query (see patterns/db-routed-request-proxy) or short-TTL cache-backed lookup.
  • Shared memory zones via ngx_lua or native modules. Worker-shared LRU dict usable for in-process caching of expensive lookups. GitHub Pages caches MySQL routing lookups here for 30 s to reduce DB load + absorb blips (see patterns/cached-lookup-with-short-ttl).
  • access_by_lua_file via ngx_lua — hook a Lua script into nginx's access phase. Canonical wiki pattern for expressing routing decisions.

Programmability via ngx_lua

nginx's embeddability is the load-bearing feature for GitHub Pages' 2015 rewrite. GitHub's report: "we're able to reuse nginx's rock-solid proxy functionality rather than reinventing that particular wheel on our own" + "we spend less than 3ms of each request in Lua (including time spent in external network calls) at the 98th percentile across millions of HTTP requests per hour." The routing smarts live in ~one Lua file; the HTTP + proxy + connection-management substrate is untouched nginx.

See systems/ngx-lua for the scripting layer.

Use-shapes on the wiki

  • Stateless frontend routing tier. GitHub Pages pages-fe: nginx + ngx_lua + shared-mem cache + proxy_pass to fileserver pair.
  • Stateful origin nginx. GitHub Pages pages-fs: nginx with document root set to X-GitHub-Pages-Root from the forwarded header, serving static files off local DRBD-replicated storage.
  • CDN origin. Fastly fronts Pages' nginx tier.

Stub page

This is a stub anchoring nginx's role in the wiki's first DB-routed static-hosting source. Broader nginx coverage — full list of modules, config directives, performance-tuning — out of scope.

Seen in

  • sources/2025-09-02-github-rearchitecting-github-pages — nginx + ngx_lua at both tiers of GitHub Pages' 2015 rewrite; the frontend does routing via Lua + MySQL + shared-mem cache + proxy_pass; the backend serves static files from a header-controlled document root; <3 ms p98 across millions RPH.
Last updated · 319 distilled / 1,201 read