Unverified Commit 9a706105 authored by Joseph's avatar Joseph Committed by GitHub

docs(examples): document env var handling in the Docker examples (#97968)

Improve with-docker example env var usage documentation.

Closes: https://github.com/vercel/next.js/issues/97959
parent 978a0809
...@@ -52,7 +52,11 @@ test-results/ ...@@ -52,7 +52,11 @@ test-results/
*~ *~
*.log *.log
# Environment variables (only commit template files) # Environment variables - keep credentials out of the build context.
# A static export has no run-time server, so anything left in the context is
# baked into the files served to every visitor. `.env.production` is
# deliberately not listed: use it for non-secret build-time config only. See
# the "Environment Variables" section of README.md.
.env .env
.env*.local .env*.local
.env.development .env.development
......
...@@ -182,6 +182,40 @@ Both Dockerfiles support multiple package managers: ...@@ -182,6 +182,40 @@ Both Dockerfiles support multiple package managers:
The Dockerfiles automatically detect which lockfile is present and use the appropriate package manager. The Dockerfiles automatically detect which lockfile is present and use the appropriate package manager.
## Environment Variables
The [`.dockerignore`](./.dockerignore) in this example **excludes `.env`**, so a local development file — which usually holds real credentials — is never copied into the build context or the final image.
With `output: "export"` there is **no server at run time**: Nginx (or `serve`) only hands out the prebuilt files in `out/`. `docker run -e …` therefore has no effect on the application. Values used by the exported application must be present while `next build` runs. Any value inlined or rendered into `out/` is served to every visitor.
### Non-secret configuration: use `.env.production`
`.env.production` is intentionally **not** ignored, so `next build` picks it up:
```bash
# .env.production
NEXT_PUBLIC_SITE_URL=https://example.com
```
### Per-environment values: use a build argument
To build the same source for several environments, pass the value into the build:
```dockerfile
ARG NEXT_PUBLIC_SITE_URL
ENV NEXT_PUBLIC_SITE_URL=$NEXT_PUBLIC_SITE_URL
# ... before the build step
```
```bash
docker build \
--build-arg NEXT_PUBLIC_SITE_URL=https://example.com \
-t nextjs-export-nginx .
```
> [!IMPORTANT]
> A static export cannot keep a secret. `NEXT_PUBLIC_*` values are inlined verbatim into the exported JavaScript, and values without the prefix are read while pages are prerendered, so anything derived from them can end up in the exported HTML. Keep API keys and other credentials out of the build entirely and call them from a separate backend.
## Deployment ## Deployment
This example can be deployed to any container-based platform: This example can be deployed to any container-based platform:
......
...@@ -49,7 +49,12 @@ playwright.config.* ...@@ -49,7 +49,12 @@ playwright.config.*
*~ *~
*.log *.log
# Environment variables (only commit template files) # Environment variables - keep credentials out of the build context.
# Anything left in the context is loaded by `next build` and copied into
# `.next/standalone`, so it ships inside the runner image. `.env.production` is
# deliberately not listed: use it for non-secret build-time config, and pass
# real secrets at run time with `docker run -e`. See the "Environment Variables"
# section of README.md.
.env .env
.env*.local .env*.local
.env.development .env.development
......
...@@ -156,6 +156,67 @@ To switch to Alpine, simply change the `NODE_VERSION` ARG in the Dockerfile to ` ...@@ -156,6 +156,67 @@ To switch to Alpine, simply change the `NODE_VERSION` ARG in the Dockerfile to `
> [!IMPORTANT] > [!IMPORTANT]
> **Node.js Version Maintenance**: This Dockerfile uses Node.js 24.13.0-slim, which was the latest LTS version at the time of writing. To ensure security and stay up-to-date, regularly check and update the `NODE_VERSION` ARG in the Dockerfile to the latest Node.js LTS version. Check the latest version at [Nodejs official website](https://nodejs.org/) and browse available Node.js images on [Docker Hub](https://hub.docker.com/_/node). > **Node.js Version Maintenance**: This Dockerfile uses Node.js 24.13.0-slim, which was the latest LTS version at the time of writing. To ensure security and stay up-to-date, regularly check and update the `NODE_VERSION` ARG in the Dockerfile to the latest Node.js LTS version. Check the latest version at [Nodejs official website](https://nodejs.org/) and browse available Node.js images on [Docker Hub](https://hub.docker.com/_/node).
## Environment Variables
The [`.dockerignore`](./.dockerignore) in this example **excludes `.env`**, so a local development file — which usually holds real credentials — is never copied into the build context or the final image.
The consequence is worth knowing up front: a value you rely on from `.env` is `undefined` inside the container, even though the same code works with `next build && next start` locally. Use one of the following instead.
### Secrets and server-only values: pass them at run time
Values read on the server at request time (Route Handlers, dynamically rendered Server Components, Server Actions) are read from the environment when the request happens, so they need nothing at build time:
```bash
docker run -p 3000:3000 -e MY_SECRET=value nextjs-standalone-image
```
or in [`compose.yml`](./compose.yml):
```yaml
services:
nextjs-standalone:
environment:
MY_SECRET: value
# or, to read a file that is not committed:
# env_file:
# - .env.production.local
```
Prefer this wherever it works: it keeps one image promotable across environments instead of baking values into a per-environment build.
### Non-secret build-time configuration: use `.env.production`
`.env.production` is intentionally **not** ignored, so it is available to `next build` and loaded by the server at run time. Use it only for values that are safe to publish:
```bash
# .env.production
NEXT_PUBLIC_SITE_URL=https://example.com
```
### Public values needed in the client bundle: use a build argument
`NEXT_PUBLIC_*` values referenced from Client Components are inlined into the JavaScript sent to the browser, so they have to be present while `next build` runs. Add them to the builder stage:
```dockerfile
ARG NEXT_PUBLIC_SITE_URL
ENV NEXT_PUBLIC_SITE_URL=$NEXT_PUBLIC_SITE_URL
# ... before the build step
```
```bash
docker build \
--build-arg NEXT_PUBLIC_SITE_URL=https://example.com \
-t nextjs-standalone-image .
```
> [!IMPORTANT]
> Never pass secrets as build arguments. They are recoverable from the image history, and `NEXT_PUBLIC_*` values are sent to the browser by definition.
> [!IMPORTANT]
> Any env file that **is** present in the build context is also copied into `.next/standalone` by `output: "standalone"`, and this Dockerfile copies that directory wholesale into the runner stage. The file therefore ships inside the image and is readable by anyone who can pull it. Keep credentials out of committed env files and pass them at run time.
To build a separate image per environment instead, see [`with-docker-multi-env`](../with-docker-multi-env).
## Deployment ## Deployment
This example can be deployed to any container-based platform: This example can be deployed to any container-based platform:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment