claude-code-mastery-project-starter-kit: Skill for Claude Code

NGINX: Production Reverse-Proxy Config

Aimed at NGINX in front of containerized backends. The defaults are fine for a static site, these are the things that bite in production.

Resolve upstreams through Docker DNS with a short TTL

By default NGINX resolves an upstream host once, at startup, and caches the IP forever. In Docker that IP belongs to a container that will be replaced, so the proxy keeps sending traffic to a dead address. Point NGINX at Docker's internal DNS and force re-resolution:

http {
    resolver 127.0.0.11 ipv6=off valid=10s;   # Docker DNS, re-resolve every 10s
}

valid=10s is what makes NGINX pick up the new container after a restart or scale. This is the NGINX side of "never hardcode IPs", see the docker-swarm skill for the principle.

Upstreams by service name, with keepalive

Reference backends by service name, never IP. Reuse connections with keepalive, which needs HTTP/1.1 and a cleared Connection header:

upstream backend {
    server backend-service:8080;
    keepalive 32;
}
server {
    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}

Structured JSON logs to stdout/stderr

Log JSON so an aggregator can parse it, and write to stdout/stderr so Docker's logging driver captures it. Never log to a file inside the container.

log_format json_log escape=json '{'
    '"time":$msec,"method":"$request_method","status":$status,'
    '"uri":"$request_uri","rt":$request_time,'
    '"upstream":"$upstream_addr","cache":"$upstream_cache_status",'
    '"client":"$remote_addr","xff":"$http_x_forwarded_for"'
'}';
access_log /dev/stdout json_log;
error_log  /dev/stderr warn;

Health and status on separate, access-restricted ports

Keep health checks and metrics off the production port: different access control, no log noise, no interference with real traffic. Restrict to internal networks and turn off access logging.

server {                          # load balancer health check
    listen 82;
    allow 10.0.0.0/8; allow 172.16.0.0/12; allow 127.0.0.1; deny all;
    location /health { access_log off; return 200 "OK"; }
}
server {                          # stub_status for Prometheus/Datadog
    listen 81;
    allow 10.0.0.0/8; allow 127.0.0.1; deny all;
    location /nginx_status { stub_status on; }
}