System environment variables at build time? What to do when building with docker?

[AssisrMatheus]

I figured that the environment variables are needed at build time, for NEXT_PUBLIC_ vars at least, even if we aren't using SSG.

When building with docker-compose from a dockerfile, we can set up the environment variables for the system, using the environment keyword, which forwards those variables as system wide variables. However, they are not available when the dockerfile is running(and building the app) but rather, only when docker runs the app, thus, making my NEXT_PUBLIC_ equals to undefined.

We cannot necessarily read from a .env file in our deployed services, only for local development. We want the hosting service to handle our vars system wide.

What is the usual best practice in this case? Read from the system variables without an .env file?

---

This is my setup:

docker-compose.yml

version: '3.7'
services:
  fe:
    build: ./
    ports:
      - '3000:80'
    environment:
      NEXT_PUBLIC_API_URI: arbitrary_value

Dockerfile

FROM node:12.18.0-alpine
WORKDIR /app/
COPY . .
RUN npm i
RUN npm run build
EXPOSE 3000
EXPOSE 80
CMD ["npm", "run", "serve"]

In this case here. "arbitrary_value" is not available in the browser, reading with process.env.NEXT_PUBLIC_API_URI

[AssisrMatheus]

Also, one more thing. In that case is the only option using publicRuntimeConfig? How does SSG handles that?(I'd assume it doesn't)

[rafaelalmeidatk]

For build time values you need to use build args instead of environment variables. Here are the updated files:

# docker-compose.yml
version: '3.7'
services:
  fe:
    build: ./
    ports:
      - '3000:80'
    # the build args are defined by this key
    args:
      NEXT_PUBLIC_API_URI: arbitrary_value

# Dockerfile
FROM node:12.18.0-alpine
WORKDIR /app/

# here we are reading the value from the build args and inserting into the environment variables
ARG NEXT_PUBLIC_API_URI
ENV NEXT_PUBLIC_API_URI=${NEXT_PUBLIC_API_URI}

COPY . .
RUN npm i
RUN npm run build
EXPOSE 3000
EXPOSE 80
CMD ["npm", "run", "serve"]

Also, one more thing. In that case is the only option using publicRuntimeConfig? How does SSG handles that?(I'd assume it doesn't)

You would only need to use publicRuntimeConfig if you want to change some value at runtime and can't do another build.

[alingavriliuc]

Additional property args is not allowed

[alamenai]

@rafaelalmeidatk , will your solution work if I define my en values in App Settings in Azure instead of env files?

[tranquanghuy0801]

@alamenai Yes we did that way and the solution work. However, we have to manually set the env when running yarn build in Dockerfile. For example, yarn build NEXT_PUBLIC_API_URI=${NEXT_PUBLIC_API_URI}

[alamenai]

@tranquanghuy0801 , this is my Dockerfile:

FROM node:20-alpine AS base

# Install dependencies only when needed
FROM base AS deps
# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
RUN apk add --no-cache libc6-compat


WORKDIR /app

# Install dependencies based on the preferred package manager
COPY package.json ./

# You can use these package managers
# yarn.lock* package-lock.json* pnpm-lock.yaml*

# RUN \
#   if [ -f yarn.lock ]; then yarn --frozen-lockfile; \
#   elif [ -f package-lock.json ]; then npm ci; \
#   elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \
#   else echo "Lockfile not found." && exit 1; \
#   fi

RUN npm install --legacy-peer-deps --verbose

# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Next.js collects completely anonymous telemetry data about general usage.
# Learn more here: https://nextjs.org/telemetry
# Uncomment the following line in case you want to disable telemetry during the build.
# ENV NEXT_TELEMETRY_DISABLED 1

ARG NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN

ENV NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=${NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN}

RUN npm run build

# Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app

ENV NODE_ENV production
# Uncomment the following line in case you want to disable telemetry during runtime.
# ENV NEXT_TELEMETRY_DISABLED 1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public

# Set the correct permission for prerender cache
RUN mkdir .next
RUN chown nextjs:nodejs .next

# Automatically leverage output traces to reduce image size
# https://nextjs.org/docs/advanced-features/output-file-tracing
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT 3000
# set hostname to localhost
ENV HOSTNAME "0.0.0.0"
# server.js is created by next build from the standalone output
# https://nextjs.org/docs/pages/api-reference/next-config-js/output
CMD ["node", "server.js"]

And this is my azure pipeline:

trigger:
  - credium-alpha

variables:
  # Container registry service connection established during pipeline creation
  dockerRegistryServiceConnection: "MY REGISTRY"
  imageRepository: "repos"
  containerRegistry: "myapi.azurecr.io"
  dockerfilePath: "$(Build.SourcesDirectory)/Dockerfile.prod"
  arguments: "--build-arg NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=${NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN}"
  tag: "$(Build.BuildId)"
  vmImageName: "ubuntu-latest"

pool:
  vmImage: ubuntu-latest

stages:
  - stage: Install
    displayName: "Install"
    jobs:
      - job: InstallJob
        displayName: "Install Node.js and Dependencies"
        steps:
          - task: NodeTool@0
            inputs:
              versionSpec: "20.x"
            displayName: "Install Node.js"
          - script: |
              npm install
            displayName: "Install Node.js and Dependencies"

  - stage: Tests
    displayName: "Run Unit and Component Tests"
    jobs:
      - job: TestsJob
        displayName: "Run Unit and Component Tests"
        steps:
          - script: |
              npm install
              npm test
              npm run cypress-run-component
            displayName: "Run Unit and Component Tests"

  - stage: Build
    displayName: Build
    jobs:
      - job: Build
        displayName: Build
        pool:
          vmImage: $(vmImageName)
        steps:
          - task: Docker@2
            displayName: Build and push an image to container registry
            inputs:
              command: buildAndPush
              repository: $(imageRepository)
              dockerfile: $(dockerfilePath)
              buildContext: "./"
              containerRegistry: $(dockerRegistryServiceConnection)
              tags: |
                $(tag)
                latest

In the env.production:

NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=

I expected to be replaced by the value from App Settings but it did not work, may I miss something ?

[tranquanghuy0801]

@alamenai Sorry for my late reply. The Dockerfile looks good to me.

Did you define the env vars inside env.production? If yes, I think this would overwrite the value you set in Dockerfile

[olamide226]

A simple way to think about this is:

• build.args are available while Docker is building the image.
• environment values are available when the container starts.
• NEXT_PUBLIC_* values are copied into the browser bundle during next build.

So if you do this:

services:
  fe:
    build: ./
    environment:
      NEXT_PUBLIC_API_URI: https://api.example.com

that value is too late for client-side process.env.NEXT_PUBLIC_API_URI, because the JS bundle was already built.

If the value is known at image build time, build args are fine:

services:
  fe:
    build:
      context: ./
      args:
        NEXT_PUBLIC_API_URI: https://api.example.com

ARG NEXT_PUBLIC_API_URI
ENV NEXT_PUBLIC_API_URI=$NEXT_PUBLIC_API_URI

RUN npm run build

But if the goal is one image for dev/staging/prod, build args are not enough, because they still bake the value into the image.

For that runtime case, this is the problem REP is designed for:

https://github.com/RuachTech/rep

REP does not make NEXT_PUBLIC_* dynamic. Instead, you stop using NEXT_PUBLIC_* for browser runtime config and pass REP_PUBLIC_* values when the container starts.

Client code:

import { rep } from '@rep-protocol/sdk'

const apiUri = rep.get('API_URI')

Runtime env:

services:
  fe:
    image: my-next-app:latest
    ports:
      - "8080:8080"
    environment:
      REP_PUBLIC_API_URI: https://api.example.com
      REP_PUBLIC_ENV_NAME: production

The REP gateway injects those values into the HTML as inert JSON:

<script id="__rep__" type="application/json">...</script>

For a standalone Next.js image, the gateway can sit in front of the Next server:

NODE_ENV=production node /app/server.js &

exec rep-gateway \
  --mode proxy \
  --port 8080 \
  --upstream localhost:3000

Then you can run the same image with different values:

docker run --rm -p 8080:8080 \
  -e REP_PUBLIC_API_URI=https://api.staging.example.com \
  -e REP_PUBLIC_ENV_NAME=staging \
  my-next-app:latest

docker run --rm -p 8080:8080 \
  -e REP_PUBLIC_API_URI=https://api.example.com \
  -e REP_PUBLIC_ENV_NAME=production \
  my-next-app:latest

So the short version is:

• use Docker build args if the value should be baked into the image;
• use runtime env + a runtime config layer like REP if the same image should work in multiple environments;
• keep real secrets server-only, not in browser runtime config.