Production checklist¶
What to set and verify before the service takes real traffic. Most items are one environment variable.
Required¶
-
APP_ENV=production. The container image sets it. It selects JSON logs and PostgreSQL by default, turns response validation off and enables the checks below. -
AUTH_SECRETis random and at least 32 characters (with HS256). The server refuses to start in production with the default value or a shorter one. Generate one withopenssl rand -base64 48. -
DATABASE_URLuses TLS where the network is not trusted, for examplesslmode=requireorverify-full. - Secrets come from a secret store, not from the image, the repository or a
committed
.envfile:AUTH_SECRET,DATABASE_URL,BOOTSTRAP_ADMIN_PASSWORD, and the key file for EdDSA.
Network¶
- The admin port is not public. Port 9090 serves metrics, and profiles when
enabled, without authentication. Publish 8080 only. Bind the admin server to a
private interface with
ADMIN_HOST, restrict it with a network policy, or disable it withADMIN_PORT=0. -
HTTP_CORS_ALLOWED_ORIGINSlists your origins. The default*lets any site call the API from a browser. Set explicit origins, comma-separated. -
HTTP_TRUSTED_PROXIESmatches your topology. It is the number of reverse proxies in front of the service. With0the client address is the TCP peer, which behind a proxy is the proxy itself, so every client shares one rate limit bucket. Set it too high and clients can forge their address throughX-Forwarded-For. - TLS terminates in front of the service. The server speaks plain HTTP. It sends
Strict-Transport-Securitywhen the proxy setsX-Forwarded-Proto: https. -
/docsis intended to be public, or off. SetOPENAPI_DOCS_ENABLED=falseto remove it. The page loads a script from a CDN.
Accounts¶
- Decide on open registration. With
AUTH_REGISTRATION_ENABLED=true, anyone can create an account. Set it tofalsewhen accounts are created by administrators. - The bootstrap administrator has a strong password, and
BOOTSTRAP_ADMIN_PASSWORDis removed from the environment once that account exists. The variables are ignored after the first administrator is created. - Token lifetimes fit your risk.
AUTH_ACCESS_TOKEN_TTL(15 minutes) bounds how long a stolen access token works.AUTH_REFRESH_TOKEN_TTL(30 days) bounds a session.
Database¶
- Choose how migrations run. Either leave
DATABASE_AUTO_MIGRATE=true, which is safe with several replicas on PostgreSQL because of the advisory lock, or set it tofalseand run/app/migrate upas a deployment step. The second option lets the server run with a database role that cannot change the schema. - Migrations are backward compatible with the version still running during a rolling update: add columns before using them, remove them after.
- The pool fits the database.
DATABASE_MAX_OPEN_CONNStimes the number of replicas must stay below the connection limit of PostgreSQL. - Backups exist and have been restored once.
- PostgreSQL, not SQLite, for anything with more than one instance.
Limits¶
- Rate limits are sized per replica. The counters are in process memory:
RATE_LIMIT_REQUESTSapplies to each replica separately. For a strict global limit, enforce it at the gateway. -
HTTP_MAX_BODY_BYTES(1 MiB) fits your largest legitimate request. - Timeouts fit your slowest endpoint.
HTTP_REQUEST_TIMEOUT(30 s) must be shorter than the timeout of the proxy in front, andHTTP_WRITE_TIMEOUT(10 s) bounds how long a response may take to write. -
APP_SHUTDOWN_TIMEOUT(10 s) is shorter than the grace period your platform gives a container before killing it.
Performance¶
-
OPENAPI_VALIDATE_RESPONSES=false. It is the production default. When on, every response is buffered in memory and validated. -
AUTH_BCRYPT_COST(12) is measured on your hardware. Each login costs one hash; a higher cost slows logins and password guessing alike. -
ADMIN_PPROF_ENABLED=falseunless you are profiling.
Observability¶
- Logs are collected from standard output, as JSON.
- Metrics are scraped from
:9090/metrics, with an alert on the 5xx rate and on latency. - Probes are configured:
/health/livefor liveness and/health/readyfor readiness. - Traces go somewhere, if you enable them:
OTEL_ENABLED=trueandOTEL_EXPORTER_OTLP_ENDPOINT.
Supply chain¶
- Dependabot is enabled for Go modules, actions and base images.
-
make vulnpasses. CI runsgovulncheckon every change. - Images are pinned by digest in your manifests, and their signature is verified where your platform supports it.