docs(ops): NEXT_PUBLIC_APP_VERSION is build-time only — drop runtime env-var

The env-var is baked into the Next.js bundle at build time via
docker-publish; the Coolify runtime entry was misleading. Document
the "DO NOT SET" rule in the Coolify section of the reverse-proxy
guide so operators don't try to fix the stale entry. The same
build-time semantics apply to NEXT_PUBLIC_APP_BUILD_SHA and
NEXT_PUBLIC_APP_BUILT_AT; both are now called out alongside.

Closes H0 in v1.4.48 backlog.
This commit is contained in:
Marc-André Bombeck committed 2026-05-23 10:24:13 +02:00
1 parent 5824b5321d
commit 78f91d7876
1 file changed
+22
+22
View File
@@ -131,6 +131,28 @@ operator attention:
`DEPLOY_WEBHOOK_SECRET`. The app gates the endpoint with a
timing-safe compare against that env var.
### DO NOT set as runtime env vars
The following variables are **build-time only** — they are injected
via `--build-arg` by the `docker-publish` workflow and baked into the
shipped image. Setting them under Coolify's *Environment Variables*
panel has zero effect on the running container, and the stale value
becomes a misleading artefact next time someone audits the deploy
config:
- `NEXT_PUBLIC_APP_VERSION` — sourced from the GHCR tag at build
time. Next.js inlines the value into both the client bundle (so
the `<VersionPoller>` self-healing reload compares against the
shipped shell) and the `/api/version` server route (so the public
endpoint returns the same string). The `env: {…}` block in
`next.config.ts` short-circuits the runtime `process.env` read.
- `NEXT_PUBLIC_APP_BUILD_SHA`, `NEXT_PUBLIC_APP_BUILT_AT` — same
pattern. The CI workflow stamps the short SHA and build timestamp
into the image during `pnpm build`.
If you spot any of these in the Coolify panel, delete the entry. The
image already carries the correct value.
Coolify-Tunnel adds one hop to the chain; pair with
`TRUST_PROXY_HOPS=2`. If you front Coolify itself with Cloudflare,
bump to `3`.