Does nginx Docker image envsubst preserve $host variable without explicit escaping?

Short answer

No — with the default configuration, the nginx Docker image's envsubst step does not reliably preserve $host. If an environment variable named host exists in the container, it gets substituted; if it doesn't, envsubst typically replaces $host with an empty string, silently breaking your config. The reliable, version-independent fix is to escape nginx variables as $$host in the template. NGINX_ENVSUBST_FILTER works too, but it is an allowlist of names to substitute, not a denylist — so it protects nginx variables only indirectly, and its default value has changed between image releases.

Why the default is unsafe

The image entrypoint runs envsubst over each /etc/nginx/templates/*.template file and writes the result to /etc/nginx/conf.d/. GNU gettext envsubst has no knowledge of nginx; every $name token looks like a variable reference to it. NGINX_ENVSUBST_FILTER restricts substitution to variable names matching a pattern — when set, only matching names are replaced, which incidentally leaves $host alone. When unset, substitution is effectively unfiltered, so nothing protects nginx-internal variables.

Because the entrypoint script and its defaults have been adjusted across image lines (the 1.25-era and 1.27-era entrypoints are not identical), do not assume the filter default on one tag applies to another. Treat any claim about "the default filter excludes nginx variables" as unverified until you check your pinned tag.

Recommended approach

Use the double-dollar escape in templates. It is standard envsubst behavior ($$ renders a literal $) and does not depend on the image's filter default:

server {
    listen 80;
    server_name ${APP_DOMAIN};
    location / {
        proxy_pass ${UPSTREAM_URL};
        proxy_set_header Host $$host;
        proxy_set_header X-Original-URI $$request_uri;
    }
}

Here ${APP_DOMAIN} and ${UPSTREAM_URL} are substituted from the environment, while $$host renders as the literal $host nginx expects.

The alternative — setting NGINX_ENVSUBST_FILTER to list only your own variables (e.g. NGINX_ENVSUBST_FILTER=APP_DOMAIN|UPSTREAM_URL, depending on the tag's expected format) — also works, but couples correctness to that tag's entrypoint implementation and to you remembering to add every new variable to the filter.

Verify against your pinned tag

Do not trust documentation summaries; check the actual entrypoint and render output:

# Inspect the filter default in your exact tag
docker run --rm nginx:1.27.2 \
  sh -c 'grep -n ENVSUBST_FILTER /docker-entrypoint.d/20-envsubst-on-templates.sh'

# Render a test template and check the output
docker run --rm -e APP_DOMAIN=example.com \
  -v "$PWD/templates:/etc/nginx/templates" \
  nginx:1.27.2 \
  sh -c '/docker-entrypoint.sh nginx -t && cat /etc/nginx/conf.d/*.conf'

Confirm the rendered file contains literal $host and that nginx -t passes. Repeat against any second tag you deploy (e.g. 1.25.x) before assuming parity.

Caveats

This guidance reflects well-established envsubst and entrypoint behavior, but exact filter defaults and escaping handling are version-specific — pin an immutable tag (or digest), verify as above, and re-verify on upgrades. If your rendered config still shows an empty value where $host should be, share the template snippet and the exact image tag; that combination determines which of the two mechanisms is misfiring.