Pulp Engine v0.39.0 — Release Notes
This release makes hardened production the endorsed and clearly signposted default path across every operator-facing surface: the README quick-start, the Dockerfile container defaults, .env.example, the deployment guide, the operator runbook, the release checklist, and the deployment validation script. No application logic changed. The HARDEN_PRODUCTION runtime default remains false — all existing deployments are fully backward-compatible.
One behavioral change: the Docker image now defaults to DOCS_ENABLED=false. Swagger UI is no longer exposed by default in container deployments. See the Upgrade section below.
What changed
1. README — hardened production as the primary Docker quick-start
The ## Docker section previously showed a single docker run example with only API_KEY_ADMIN set. This is evaluation posture — security controls are advisory only.
After: the section now leads with a “Supported production deployment” block that shows all five required security controls plus HARDEN_PRODUCTION=true, followed by a clearly labeled “Evaluation / demo” block for the minimal case. The hardening paragraph no longer attributes HARDEN_PRODUCTION to a specific version (“v0.27.0: Set…”) — it is now phrased as a standing requirement.
2. Dockerfile — DOCS_ENABLED=false added to runtime ENV defaults
Breaking change (minor): The container image now sets DOCS_ENABLED=false in its runtime ENV block. Swagger UI (/docs, /docs/json, /docs/yaml) is disabled by default in all container deployments.
Why: A production API container should not expose its internal API specification surface by default. Swagger UI is a development and debugging tool. Operators who need it for development can re-enable it with -e DOCS_ENABLED=true.
Upgrade: If your deployment uses the Swagger UI and relies on the container default, add -e DOCS_ENABLED=true to your docker run command or compose file. This is a one-line change.
3. .env.example — hardened production example block added
The individual security vars (CORS, DOCS, METRICS, HTTPS, TRUST_PROXY, HARDEN_PRODUCTION) were already present in .env.example as commented-out single-var entries. Existing defaults are unchanged.
After: a new clearly labeled “Hardened production example” block is appended immediately after the individual var comments. The block shows all six lines ready to copy into a production .env. The section header now reads: “HARDEN_PRODUCTION=true is the endorsed production posture.”
4. validate-deploy.sh — security posture advisory warnings added
The deployment validation script previously reported only functional health (liveness, readiness, metrics reachability, auth, render). A deployment with an open CORS policy, unauthenticated /metrics, and a publicly exposed Swagger UI would pass all checks with no indication.
After: two new advisory checks are added (exit code unaffected — warns do not fail the script):
- Check 3a: If no
METRICS_TOKENwas provided AND/metricsreturns 200 without auth →WARN: /metrics is publicly accessible. - Check 3b: If
GET /docsreturns any 2xx or 3xx response (redirects into the UI count) →WARN: Swagger UI is publicly accessible.
The results line now includes a warned count: Results: N passed, N failed, N skipped, N warned. A security posture summary is printed before the final exit line.
5. docs/deployment-guide.md — minimum production configuration section added
A new “Minimum Supported Production Configuration” section is inserted immediately after the environment variables table. It shows the canonical hardened .env block as the expected production baseline and explains that “Deployments running without HARDEN_PRODUCTION=true are in evaluation posture.”
The HARDEN_PRODUCTION table row now reads: “Endorsed posture for all production deployments: true.” The DOCS_ENABLED table row notes that the Docker image now defaults to false.
The “Hardened Production Mode” subsection header is updated from “Recommended for all production deployments” to “Required for supported production deployments.”
6. docs/runbook.md — hardening moved to a direct requirement
The pre-deployment checklist previously had a conditional entry (“If HARDEN_PRODUCTION=true… / If HARDEN_PRODUCTION is not set…”). This framing treated hardening as an optional configuration mode.
After: the entry is rewritten as a direct requirement with all five controls listed inline. It is moved earlier in the checklist — above asset binary store and named-user configuration. An upgrade path note is preserved: “Upgrading incrementally: omit HARDEN_PRODUCTION and resolve each advisory warning before enabling it. Running without HARDEN_PRODUCTION=true is evaluation posture — not supported for production.”
7. docs/release-checklist.md — hardening in the primary deployment gate
HARDEN_PRODUCTION=true was previously in a “Security hardening checks (v0.25.0+)” sidebar section after the main deployment gates. It was labeled “recommended.”
After: each deployment section (postgres, file, sqlserver) now includes a dedicated hardening checklist item immediately before/alongside the validate-deploy.sh command. The section label is updated to “Required for supported production deployments.” The validate-deploy.sh command is updated to include $METRICS_TOKEN as the normal argument (since METRICS_TOKEN is required in hardened mode). The upgrade note is preserved.
Validation
pnpm typecheck— 10/10 passedpnpm lint— 0 errors (1 pre-existing unrelated warning)pnpm --filter @pulp-engine/api test— 573 passed, 41 skipped, 0 failedpnpm build— 10/10 passed (full turbo cache hit)
Upgrade
Docker users: if your deployment uses Swagger UI (/docs) and you relied on the container default, add -e DOCS_ENABLED=true to your docker run command or compose file. No other changes required.
All other deployments: fully backward-compatible. HARDEN_PRODUCTION runtime default is still false. Advisory warnings continue to fire as before. No migrations, no API changes, no credential changes.
docker pull ghcr.io/OWNER/pulp-engine:v0.39.0