Docker Env Vars and Secrets: Build Time vs Runtime

Docker's Dockerfile reference is blunt about the two instructions that look like configuration. ENV values are always persisted in the built image and carry into every container run from it. ARG values are not embedded in the image or available in the final container, but build arguments can still be seen with docker history, and Docker says plainly that it is not recommended to pass secrets through them.

When a build truly needs a credential, for example to fetch a private package, Docker's answer is a secret mount: RUN --mount=type=secret makes the value available to that one instruction, by default as a file under /run/secrets, and it is supplied on the command line with --secret. This site never needs it. Its Dockerfile declares no ARG, and the only ENV lines set harmless values such as the port.

The same inlining makes it build-time configuration. Next.js's docs note that after the build the app no longer responds to changes in those variables, and that a single Docker image promoted through several environments freezes them at the values from the build. Dynamic lookups such as process.env[name] are not inlined at all. Server variables are the opposite: they can be read at request time during dynamic rendering, which is what lets one image run with different values.

This site's two secrets, an AI provider key and an email provider key, are server-side only. They are read from process.env inside API route handlers on the server, never in a component that ships to the browser. That is the shape to copy: public identifiers at build time, secrets at runtime on the server.

Plain configuration goes in variables, read through the vars context, and an unset variable returns an empty string. That is why the workflow writes vars.APP_PORT || 3002: an empty value falls back to a default. The rule of thumb on this site: anything that would be harmful if posted publicly is a secret, everything else is a variable.

GitHub evaluates every dollar-brace expression and substitutes the result before the shell script runs, so by the time the SSH step executes, the heredoc already contains the real values. Bash says that if any part of the heredoc delimiter is quoted, the lines are not expanded, which is why the delimiter is written 'ENVEOF' with quotes: a value containing a dollar sign stays literal instead of being treated as a variable.

When one variable is set in several places, Compose resolves it in a fixed order, highest first: docker compose run -e, then environment or env_file entries with an interpolated value, then environment alone, then env_file alone, and last an ENV baked into the image. A Dockerfile ENV therefore only applies when Compose sets nothing for that name. With several env_file entries, later files override earlier ones.

There is an honest trade-off here. Compose's own documentation advises against passing passwords and API keys as environment variables, because they are often available to all processes in the container and hard to track, and offers Compose secrets, mounted as files under /run/secrets. This site keeps env_file: a single container on a single machine, an owner-only file, and secrets that exist only on the server. Know that the stronger option exists before choosing the simpler one.

Out of the logs: GitHub redacts secrets printed to the log, but its docs say this redaction is not guaranteed, because a secret can be transformed in many ways, and the runner can only redact secrets used in the current job. So never print one. If a secret produces another sensitive value, register that value for masking too, and avoid wrapping several secrets in one JSON or YAML blob; create one secret per value.

And plan for the day one leaks. GitHub's hardening guide recommends granting the minimum permissions, auditing how secrets are used, and rotating them periodically to shorten the window in which a compromised one is valid. This workflow applies the first rule to its own token: each job lists only the permissions it needs.