Docker & Next.js: Mastering Environment Variables

Strategy 2: Build-Time Arguments (--build-arg)

This strategy embraces Next.js's build-time nature. You pass the environment variables to Docker at the moment you build the image. This is done using ARG in your Dockerfile and the --build-arg flag in your `docker build` command.

Here's how you'd modify your production Dockerfile:

# ... (previous build stages)

# --- Runner Stage ---
FROM node:18-alpine AS runner
WORKDIR /app

# 1. Declare the build arguments
ARG NEXT_PUBLIC_API_URL
ARG SOME_OTHER_PUBLIC_VAR

# 2. Set them as environment variables for the build process
ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
ENV SOME_OTHER_PUBLIC_VAR=$SOME_OTHER_PUBLIC_VAR

# ... (copy built files from builder stage)
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next ./.next
# ...

# The 'next build' command (in the builder stage) will now see these ENVs

CMD ["npm", "start"]
    

You would then build your image like this:

docker build \
  --build-arg NEXT_PUBLIC_API_URL=https://api.production.com \
  --build-arg SOME_OTHER_PUBLIC_VAR=prod_value \
  -t my-nextjs-app:prod .
    

Verdict: Simple to understand, but deeply flawed for most workflows. It bakes the configuration into the image, forcing you to create separate images for staging and production. This breaks the "build once, run anywhere" paradigm and can be a security risk, as secrets become part of the image layers.

Strategy 3: Runtime Variables (The Production Standard)

This is the holy grail: a single Docker image that can be configured at run time. This aligns perfectly with modern DevOps practices and tools like Kubernetes.

Server-Side Variables: The Easy Part

For server-side variables (e.g., DATABASE_URL), it's straightforward. The Next.js server (running via next start) is a Node.js process. It can read environment variables from its host environment at any time. You can pass them to your container with ease:

docker run -p 3000:3000 \
  -e DATABASE_URL="postgresql://user:pass@host:port/db" \
  -e API_SECRET_KEY="super-secret-key" \
  my-nextjs-app
    

Inside your API routes or getServerSideProps, process.env.DATABASE_URL will have the correct value. No tricks needed.

Client-Side Variables: The Mastery Part

This is where we solve the build-time inlining problem for NEXT_PUBLIC_ variables. The strategy is to use placeholders during the build and replace them just before the server starts.

Step 1: Use Placeholders in your .env file

During the build, you need to provide a value. We'll use a distinct placeholder format.

# .env.production
NEXT_PUBLIC_API_URL=__NEXT_PUBLIC_API_URL__
NEXT_PUBLIC_ANALYTICS_ID=__NEXT_PUBLIC_ANALYTICS_ID__
    

Step 2: Create an Entrypoint Script

This shell script will run when the container starts. It will find all the built JavaScript files and replace the placeholders with the actual environment variables provided to the container.

Create a file named entrypoint.sh:

#!/bin/sh

# Find all .js files in the .next/static directory
find /app/.next/static -type f -name "*.js" | while read file; do
  # Use the environment variables passed to the container to replace placeholders
  sed -i "s|__NEXT_PUBLIC_API_URL__|${NEXT_PUBLIC_API_URL}|g" "$file"
  sed -i "s|__NEXT_PUBLIC_ANALYTICS_ID__|${NEXT_PUBLIC_ANALYTICS_ID}|g" "$file"

  echo "Replaced placeholders in $file"
done

# Start the Next.js server
exec "$@"
    

Make sure this script is executable: chmod +x entrypoint.sh.

Step 3: Update Your Production Dockerfile

Finally, copy the entrypoint script into your image and set it as the ENTRYPOINT. The CMD will be passed as an argument to the entrypoint script.

# --- Runner Stage ---
FROM node:18-alpine AS runner
WORKDIR /app

ENV NODE_ENV=production

# ... (copy built files)

# Copy the entrypoint script
COPY --from=builder /app/entrypoint.sh .
RUN chmod +x ./entrypoint.sh

ENTRYPOINT ["./entrypoint.sh"]
CMD ["npm", "start"]
    

Now, you build your image once. Then, you can run it anywhere, providing the configuration at run time:

# For Staging
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_API_URL="https://api.staging.com" \
  -e NEXT_PUBLIC_ANALYTICS_ID="STG-12345" \
  my-nextjs-app

# For Production
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_API_URL="https://api.production.com" \
  -e NEXT_PUBLIC_ANALYTICS_ID="PROD-67890" \
  my-nextjs-app
    

Verdict: This is the most robust and flexible solution. It fully embraces containerization principles, making your application portable and easy to manage in automated CI/CD pipelines. It's the professional standard for production deployments.

Comparing the Strategies

Here's a quick summary to help you choose the right approach:

Security & Best Practices

• Never commit secrets: Always keep .env.local and other secret files out of Git by adding them to your .gitignore file. Commit a .env.example file to show what variables are needed.
• Use a Secrets Manager: For production, inject environment variables from a secure source like AWS Secrets Manager, HashiCorp Vault, or your cloud provider's secret management service.
• Minimize Exposed Variables: Be extremely cautious with what you prefix with NEXT_PUBLIC_. This data is fully visible in your users' browsers. If it's sensitive, it belongs on the server.

Conclusion: Build Once, Configure Anywhere

Managing environment variables in a Dockerized Next.js application doesn't have to be a source of frustration. By understanding the fundamental difference between build-time and run-time configuration, you can choose the right strategy for the job.

While quick-and-dirty methods work for local development, adopting the runtime variable strategy for production is a game-changer. It sets you up for a scalable, secure, and maintainable deployment process that will save you countless headaches down the line. You build your image once, and you can confidently run it anywhere, from your staging server to a complex Kubernetes cluster, simply by providing the right configuration at the right time.