docker image with NEXT_PUBLIC_ env variables

[firefart]

Hi,
I'm currently trying to dockerize a next.js app which will be built using github actions, the image is pushed to githubs container registry and after that it is deployed to our kubernetes cluster. We use the same image for multiple stages in our environment (dev, staging, prod) and all configuration values are passed to the docker image via secrets or env variables upon start.

Now a problem arises when using browser exposed env variables in next.js with NEXT_PUBLIC_.... (in our case needed for google recaptcha and stripe.js):
It seems like all NEXT_PUBLIC_ env vars need to be defined at build time, as the next build command replaces them with the actual values in the generated JS code. But as the env keys differ for each environment (test has other public keys as prod), we can't provide them at build time to the image without having to build separate images for each env which we would like to prevent.

Is there a clean way of providing these env vars at runtime instead? The docs at https://nextjs.org/docs/basic-features/environment-variables are not really helpful in this case.

Putting the next build step in the entrypoint of the dockerfile so it will be executed upon start is also no option, as the build steps take a huge amount of memory.

Thanks!

Dockerfile example:

FROM node:current-slim

ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
ENV NO_UPDATE_NOTIFIER=true
ENV PORT=8080

RUN groupadd -r app && useradd -r -g app app
WORKDIR /usr/src/app
RUN chown app:app -R /usr/src/app

COPY package*.json ./

RUN npm ci --only=production

COPY --chown=app:app . .

USER app

# build next.js app
RUN npm run-script build

EXPOSE $PORT

CMD [ "npm", "run-script", "start" ]

[nilevia]

any update ?

[hanisntsolo]

Checkout latest reply!

[reanimatedmanx]

Guys its bothering me also, the same problem. Fighting with it for like a weak now, tried a lot of stuff. Any news how nextjs can swallow .env file and make client side env variables work?

[firefart]

I ended up supplying them as build args to the image and create 2 separate images. Sadly there seems to be no other way currently instead of switching all sites from static to dynamic processing which should not be considered at all for such a trivial task.

[alamenai]

@firefart , please could you share an example of what you did ?

[balazsorban44]

You cannot switch NEXT_PUBLIC_ variables at runtime, because they are inlined/hard-coded in the static HTML. (there is nothing to switch after the build step, really. env variables become string values)

I guess you could expose those variables in getStaticProps and send them as props, then with a low revalidate value they would be recalculated, but be careful not to accidentally expose secrets this way! maybe add your own safe prepended versions like PUBLIC_.

Also, your variables won't be embedded anymore, and may or may not be correctly crawled if you have a fallback page (getStaticPaths fallback: true). Google handles it, but Facebook for example cannot.

[reanimatedmanx]

@balazsorban44 Man thanks. I've read your comment carefully, re-read docs and actually made it working.

// pages/_app.tsx
TestAutoApp.getInitialProps = async (appContext: AppContext) => {
  const appProps = await App.getInitialProps(appContext)

  const {
    publicRuntimeConfig: { PROJECT_API },
  } = getConfig()

  console.log('PROJECT_API', PROJECT_API) // Here project API is available

  return { ...appProps }
}

The idea is if you don't really need ASO to opt-out of it https://nextjs.org/docs/advanced-features/automatic-static-optimization

more then this, just an empty getInitialProps inside _app.js enables to read from publicRuntimeConfig where do you want, helper functions, classes, FC components:)

[neerajincaendo]

@balazsorban44 @one-thunder This works but this way publicRuntimeconfig won't be available in reducer (using redux) , what solution would you propose ?

[yakserr]

@balazsorban44 @one-thunder This works but this way publicRuntimeconfig won't be available in reducer (using redux) , what solution would you propose ?

have you found a solution with using redux ?

[OscarJVD]

@reanimatedmanx or someone have the same solution to nextjs v13 or v14 with app directory and layout?

[edalexfancher]

Why can’t you execute a bash script to generate at run time?

…

On Sat, Oct 24, 2020 at 5:17 AM Alexei Gaidulean ***@***.***> wrote: @balazsorban44 <https://github.com/balazsorban44> Man thanks. I've read your comment carefully, re-read docs and actually made it working. // pages/_app.tsxTestAutoApp.getInitialProps = async (appContext: AppContext) => { const appProps = await App.getInitialProps(appContext) const { publicRuntimeConfig: { PROJECT_API }, } = getConfig() console.log('PROJECT_API', PROJECT_API) // Here project API is available return { ...appProps }} The idea is to opt-out of this https://nextjs.org/docs/advanced-features/automatic-static-optimization — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#17641 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AHNS74M5QRLWOM2EAGEWWYTSMKSSDANCNFSM4SFJ2QOQ> .

[firefart]

Because when doing this during startup it also means that the site has to be built on startup and that can take a lot of time.

[maranomynet]

Also building at runtime requires massive amounts of memory, whereas actually running the app server may only require a small bit.

[madhankumar028]

@firefart did you find out any workaround for this issue? I am also into the same phase now.

[firefart]

sadly not, I had to include the keys in the docker image. The alternative would be to switch all the sites using the key to dynamic rendering which is also not really a good option as you would lose a lot of next.js benefits

[qw-in]

[andrewmclagan]

don't do this...

[rboixaderg]

Hi! @firefart Maybe you can use this approach, first set enviroment variable with a specific string in build time and then use an entrypoint file to replace this string with the docker enviroment variabless value.

I don't know if you lose some benfits of next.js

Docker file:

FROM node:12 as builder

WORKDIR /usr/src/app

COPY . .

RUN yarn

# Building app
RUN NEXT_PUBLIC_ENVIROMENT_VAR=APP_NEXT_PUBLIC_ENVIROMENT_VAR yarn build

# Permisions to execute script
RUN ["chmod", "+x", "./entrypoint.sh"]
ENTRYPOINT ["/usr/src/app/entrypoint.sh"]

CMD [ "yarn", "start" ]

entrypoint.sh

#!/usr/bin/env bash
set -Ex

function apply_path {

    echo "Check that we have ENVIROMENT_VAR vars"
    test -n "$ENVIROMENT_VAR"

    find /usr/src/app/.next \( -type d -name .git -prune \) -o -type f -print0 | xargs -0 sed -i "s#APP_NEXT_PUBLIC_ENVIROMENT_VAR#$ENVIROMENT_VAR#g"
}

apply_path
echo "Starting Nextjs"
exec "$@"

Docker run:

docker run -e ENVIROMENT_VAR=value_envioment_var image_name

[CopyJosh]

RUN NEXT_PUBLIC_ENVIROMENT_VAR=APP_NEXT_PUBLIC_ENVIROMENT_VAR yarn build

Does this mean you have to add every single env variable in your app to this command...?

-- Running this, I only managed to get the runtimeConfig to return "APP_NEXT_PUBLIC_ENVIRONMENT_VAR" .. essentially just returning a string of what should have been replaced with a value..

[alete89]

this is too hacky! I don't know why it got so many 👍

[nishthaarora1409]

i am using the similar approach but still not working , env variable are not getting updated at the runtime

Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --legacy-peer-deps
COPY . .
RUN npm run build
COPY start.sh .
ENTRYPOINT ["./start.sh"]
CMD ["npm", "start"]

start.sh
`#!/bin/sh
set -e

env_file=".env.${NEXT_ENV:-uat}"

replace_env_vars() {
while IFS='=' read -r key value; do
if [ -n "$key" ] && [ -n "$value" ]; then
find /app/public /app/.next -type f -name "*.js" |
while read file; do
sed -i "s|$key|$value|g" "$file"
done
fi
done < "$env_file"
}

replace_env_vars
exec "$@"`

please help me finding the error

[fcano-ut]

A drawback of this approach is that Next.js does some optimization to remove reduntant conditions, so for example if you have this in code:

if (process.env.ENVIRONMENT === 'staging' && someOtherCondition) {

And you replace ENVIRONMENT with #_ENVIRONMENT_# (or whatever)... Then code will look like this:

if ('#_ENVIRONMENT_#' === 'staging' && someOtherCondition) {

Next.js includes some optimizations that would remove redundant conditions such as those ones from your build files, so in the build, code would look something like this:

if (!1 && someOtherCondition) {

So unfortunately this approach can cause hard-to-debug and unexpected issues

[maranomynet]

this approach can cause hard-to-debug and unexpected issues

This! So very much this!

The only possible way to get truly correct/sane results is to run next build with the exact same ENV as next start.

(Especially since Next will always render static HTML pages for 404, 500 if nothing else)

[charlesloubao]

might be an old question but I solved this issue using Docker build arguments (ARG)

FROM node:lts

# Argument passed at build time that will be appended to .env.production (if the file doesn't exist it will just create it)
ARG PROD_ENV=""

WORKDIR /usr/src/app

COPY package*.json ./
RUN npm install

COPY . .

# Appends to .env.production
RUN printf "$PROD_ENV" >> .env.production

# Build the site in production mode. .env.production is used
RUN npm run build

# I run my app on port 80 but you get the idea
EXPOSE 80
ENTRYPOINT ["npm", "run", "start", "--", "-p", "80"]

When building my image

docker build -t mytag --build-arg PROD_ENV="FOO=BAR\nBAZ=BUM" .

When checking the image the .env.production content:

FOO=BAR
BAZ=BUM

This way doesn't affect static optimization and doesn't require custom config file.

[zanechua]

This is not correct. It does not solve the original point of the discussion which was to not include any environment values at build time. They want to only include the values at run time.

For anyone who is building docker images and sharing it within a repository to people, don't use this and distribute as the secrets will still be written directly into the docker image.

[tubbo]

@zanechua the clue is in the name. NEXT_PUBLIC env vars are for public values, not "secret" values. Using ARG or RUN with mount type secrets is totally valid and secure for this use case.

[zanechua]

@tubbo I understand that the topic for discussion is NEXT_PUBLIC env values, but even you yourself call it secrets below. :p But that's just semantics. What I meant was for env values in general, I understand that there is a distinct difference between NEXT_PUBLIC and NEXT in terms of NEXT_PUBLIC being accessible on your live site if you look at the code anyway. But sometimes you just don't want to store those values into the built image, exactly like the original discussion above.

The other problem is, this example shows generic env values. Which means secrets or public values alike are both encoded into the image. Anyone who doesn't really understand what's going on may use this and start actually embedding server side only values into the image. So yes, I suppose you could use it only for NEXT_PUBLIC values but even I wouldn't do so.

[tubbo]

Have you tried using Docker BuildKit Secrets? They pretty much solve this use case, if your build system/CI can support BuildKit which is a relatively new Docker feature. Using a command like...

RUN --mount=type=secret,id=env,dst=/path/to/your/next/app/.env.production.local

...you can mount the env file in your Next application temporarily during the build process, then remove it later. This causes Next to compile in the NEXT_PUBLIC_ env variables without exposing those secrets in a file somewhere on your container.

[zanechua]

Unless I am understanding this wrongly, the NEXT_PUBLIC_ env values still get embedded into the static pages inside the container image right?

If so, that doesn't really solve the problem either.

[tubbo]

Yes, this doesn't solve the problem of runtime config. But it does solve the problem of having to check in a .env file with secrets.

[yuuk]

My approach is to dynimc create a env-config.js to ./public path by script, then include the env-config.js to the _document.js, finally you can access the vars you defined in env-config.js.
see https://www.freecodecamp.org/news/how-to-implement-runtime-environment-variables-with-create-react-app-docker-and-nginx-7f9d42a91d70/

[yuuk]

I don't know if there's some problems when i put next build to docker run phase

[tubbo]

This is basically what next runtime config does.

[zanechua]

Here's the way i'm doing it at the moment that I'm comfortable with:

@andrewmclagan pointed out that his package solves this problem in a similar manner but it seems to be directly embedding the .env files into the image itself based on the repo instructions at the moment. But no worry, the package can do everything at runtime even env ingestion. What an nifty little package.

https://github.com/andrewmclagan/react-env/

Setup

yarn add @beam-australia/react-env

entrypoint.sh

#!/bin/sh
set -e

# Generate env for runtime use
yarn react-env --env APP_ENV
# Execute any subsequent command
exec "$@"

Dockerfile

FROM node:alpine
WORKDIR /app

(...) truncated, all the other build tasks

# You can choose to put the entrypoint with yarn react-env here
# but I've chosen to use an entrypoint script instead
COPY entrypoint.sh /usr/local/bin/entrypoint.sh
RUN chmod +x /usr/local/bin/entrypoint.sh
ENTRYPOINT ["entrypoint.sh"]

CMD ["yarn", "start"]

__document.js

<Head>
  <script type="text/javascript" src="/__ENV.js" />
</Head>

.env.staging

REACT_APP_SECRET=sekret

page.js

import env from '@beam-australia/react-env';
<p>{env('SECRET')}</p>

Build

docker build -t next-app -f Dockerfile .

Usage

At this point we have an image with no environment values in the built image.

Assuming we're deploying for the staging environment, running the following will allow us to:

• Map the host's port 8080 to the container's 3000
• Define APP_ENV environment variable to be staging for the container
• Bind the volume .env.staging from the host to the container

docker run -p 8080:3000 --env APP_ENV=staging -v $(pwd)/.env.staging:/app/.env.staging next-app

After running the command, the __ENV.js will be generated in the /app/public in the container. You can verify by going to the directory after the container has booted.

I understand that there a lot of semantics here, "Why do you even bother hiding NEXT_PUBLIC_ values etc etc". Could be an internal project with secret keys or what not but the general best practice for me at least, I don't compile env values into docker images.

[sparanoid]

Here's another workaround to insert environment variables for runtime client-side rendering:

https://github.com/sparanoid/env.sh

This is simply a bash version of react-env, which does not require you to build your project inside the container.

The benefit of this method can help you avoid multistage Dockerfile. You can build your Next.js project in GitHub Actions. And only COPY built files required for production. With this method your image can be much smaller:

# A simplified version of https://github.com/vercel/next.js/blob/canary/examples/with-docker/Dockerfile
FROM node:16-alpine AS runner

# Install bash for env.sh
RUN apk add --no-cache bash
WORKDIR /app

# You only need to copy next.config.js if you are NOT using the default configuration
COPY next.config.js ./
COPY public ./public
COPY package.json .env env.sh ./

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

EXPOSE 3000

ENV PORT 3000

RUN chmod +x ./env.sh
ENTRYPOINT ["./env.sh"]

CMD ["node", "server.js"]

[gilbertkaradja]

This helps with providing env to server.js only no? The image itself already has all the generated static files inlined with some env params. Or maybe I'm missing something.

[mlarcher]

This is exactly what we needed to be able to have a real _run_time configuration ! Thank you @sparanoid !!
t

There are many questions about this topic, as for example:
#22266
#22343
#11106
or
#34894
In this last one I described our previous approach, this one is way better in many ways!
The only point that was not cracked is the middleware, as it seems there is no way to pass configuration to it outside of build time :/

Here is how we handle it now thanks to this awesome approach :

// env.sh

#!/bin/bash
# taken from https://github.com/sparanoid/env.sh/blob/master/env.sh
#
# env.sh - Dead-simple .env file reader and generator
# Tunghsiao Liu ([email protected])
#
# Inspired by:
# - https://github.com/andrewmclagan/react-env
# - https://www.freecodecamp.org/news/7f9d42a91d70/
# - https://github.com/kunokdev/cra-runtime-environment-variables
#
# Features:
# - Designed to be used for Next.js app inside a Docker container (General
#   React app should also work)
# - Read env file and generate __env.js file for runtime client use
# - Merge current environment variables passing to it (Useful for Docker images)
# - No dependencies (More like a lite version of react-env). This is important
#   to keep our container image as small as possible.
#
# Usage:
# - General usage:
#   $ ./env.sh
#
# - Replacing variable:
#   $ NEXT_PUBLIC_API_BASE=xxx ./env.sh
#
# - Enviroment variable not in whitelist will be discarded:
#   $ BAD_ENV=zzz ./env.sh
#
# - Change script options:
#   $ ENVSH_ENV="./.env.staging" ENVSH_OUTPUT="./public/config.js" ./env.sh
#
# - Use it inside Dockerfile:
#   RUN chmod +x ./env.sh
#   ENTRYPOINT ["./env.sh"]
#
# Debug:
# NEXT_PUBLIC_OB_ENV=123_from_fish NEXT_BAD_ENV=zzz NEXT_PUBLIC_OB_TESTNEW=testenv NEXT_PUBLIC_CODE_UPLOAD_SIZE_LIMIT=6666 ./env.sh

echo -e "env.sh loaded\n"

# Config
ENVSH_ENV="${ENVSH_ENV:-"./.env"}"
ENVSH_PREFIX="${ENVSH_PREFIX:-"NEXT_PUBLIC_"}"
ENVSH_PREFIX_STRIP="${ENVSH_PREFIX_STRIP:-true}"

# Can be `window.__env = {` or `const ENV = {` or whatever you want
ENVSH_PREPEND="${ENVSH_PREPEND:-"window.__env = {"}"
ENVSH_APPEND="${ENVSH_APPEND:-"}"}"
ENVSH_OUTPUT="${ENVSH_OUTPUT:-"./public/__env.js"}"

# Utils
__green() {
  printf '\033[1;31;32m%b\033[0m' "$1"
}

__yellow() {
  printf '\033[1;31;33m%b\033[0m' "$1"
}

__red() {
  printf '\033[1;31;40m%b\033[0m' "$1"
}

__info() {
  printf "%s\n" "$1"
}

__debug() {
  ENVSH_VERBOSE="${ENVSH_VERBOSE:-"false"}"
  if [ "$ENVSH_VERBOSE" == "true" ]; then
    printf "ENVSH_VERBOSE: %s\n" "$1"
  fi
}

ENVSH_SED="sed"
if [[ "$OSTYPE" == "darwin"* ]]; then
  echo "macOS detected, switching to gsed"

  if command -v gsed >/dev/null 2>&1 ; then
    __info "$(__green "Found"): $(gsed --version | head -n 1)"
  else
    __info "gsed not found, trying to install..."

    if command -v brew >/dev/null 2>&1 ; then
      __info "$(__green "Found"): $(brew --version | head -n 1)"
      brew install gnu-sed
    else
      __info "$(__red "Homebrew not found, install it first: https://brew.sh/")"
      exit 1;
    fi

  fi

  ENVSH_SED="gsed"
fi

# Recreate config file
rm -f "$ENVSH_OUTPUT"
touch "$ENVSH_OUTPUT"

# Create an array from inline variables
matched_envs=$(env | grep ${ENVSH_PREFIX})
IFS=$'\n' read -r -d '' -a matched_envs_arr <<< "$matched_envs"
echo -e "\nMatched inline env:\n"
for matched_env in "${matched_envs_arr[@]}"; do
  echo $matched_env
done

# Add assignment
echo "$ENVSH_PREPEND" >> "$ENVSH_OUTPUT"

# Check if file exists
[[ -f "$ENVSH_ENV" ]] || { echo "$ENVSH_ENV does not exist" ; exit 1 ;}

# Process .env for runtime client use
__info "$(__green "Parsing ${ENVSH_ENV}...\n")"
while IFS= read -r line
do
  # Check if this line is a valid environment variable and matches our prefix
  if printf '%s' "$line" | grep -e "=" | grep -e "$ENVSH_PREFIX"; then

    # Read and apply environment variable if exists
    # NOTE: <<< here operator not working with `sh`
    awk -F '=' '{print $1 ": \"" (ENVIRON[$1] ? ENVIRON[$1] : $2) "\","}' \
      <<< "$line" >> "$ENVSH_OUTPUT"
  fi
done < "$ENVSH_ENV"
echo "$ENVSH_APPEND" >> "$ENVSH_OUTPUT"

# Strip prefix if needed
$ENVSH_PREFIX_STRIP && $ENVSH_SED -i'' -e "s~$ENVSH_PREFIX~~g" "$ENVSH_OUTPUT"

# Update .env file itself
# NOTE: This step is not necessary because variables on pages inside the
# Next.js prod server won't be changed. They're already inlined during the
# build time.
for matched_env in "${matched_envs_arr[@]}"; do
  echo $matched_env
done

for i in "${!matched_envs_arr[@]}"; do
  IFS='=' read -ra key_arr <<< "${matched_envs_arr[$i]}"
  key=${key_arr[0]}

  if [[ "${matched_envs_arr[$i]}" = *"${key}"* ]]; then
    index="$i"
    echo -e "Got index from inline env: ${index}, replacing ${key}"
    find "$ENVSH_ENV" -type f -exec $ENVSH_SED -i'' \
      -e "s~$key=.*~${matched_envs_arr[$index]}~g" {} \;
  fi
done

# Print result
__debug "$(__green "\nDone! Final result in ${ENVSH_OUTPUT}:\n")"
__debug "`cat "$ENVSH_OUTPUT"`"

__debug "$(__green "\nDone! Modified ${ENVSH_ENV}:\n")"
__debug "`cat "$ENVSH_ENV"`"

__info "$(__green "\nenv.sh done\n")"

^ I think we only changed the separator in sed to ~ so that it doesn't crash on URLs

// in package.json
"dev": "./env.sh && next dev",

// in _document.js

<Head>
  {/* eslint-disable-next-line @next/next/no-sync-scripts */}
  <script src="/__env.js" />
</Head>

^ for some reason using Script from next the script was not loading, so we used the real script tag

// in .gitignore

/public/__env.js

// in .dockerignore

**/public/__env.js

// .env

NEXT_PUBLIC_API_BASE_URL=http://localhost:4000/graphql
NEXT_PUBLIC_DEBUG=false
SERVER_ONLY_BASIC_AUTH_LOGIN=mylogin
SERVER_ONLY_BASIC_AUTH_PASSWORD=mypwd

// config.js

import { isBrowser } from '../lib/utils';

const config = {
  public: {},
  serverOnly: {},
};

const publicPrefix = 'NEXT_PUBLIC_';
const serverOnlyPrefix = 'SERVER_ONLY_';

function convertBoolean(value) {
  if (value === 'true') {
    return true;
  }
  if (value === 'false') {
    return false;
  }
  return value;
}

const sortKeys = (obj) => {
  return Object.keys(obj)
    .sort()
    .reduce((acc, key) => {
      acc[key] = obj[key];

      return acc;
    }, {});
};

if (isBrowser()) {
  Object.entries(window.__env).forEach(([key, value]) => {
    config.public[key] = convertBoolean(value);
  });
  // we need to make sure keys are always in the same order to prevent "Text content did not match" issue 
  // when displaying config on a page
  config.public = sortKeys(config.public);
} else {
  Object.entries(process.env).forEach(([key, value]) => {
    if (key.startsWith(publicPrefix)) {
      config.public[key.replace(publicPrefix, '')] = convertBoolean(value);
    }
    if (key.startsWith(serverOnlyPrefix)) {
      config.serverOnly[key.replace(serverOnlyPrefix, '')] = convertBoolean(value);
    }
  });
  // we need to make sure keys are always in the same order to prevent "Text content did not match" issue 
  // when displaying config on a page
  config.public = sortKeys(config.public);
}

export default config;

// Dockerfile

# Install dependencies only when needed
FROM node:18.2.0-alpine AS deps

WORKDIR /app

# 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

COPY client/package.json .
# we use npm install and not npm ci because package-lock.json is generated on mac host machine and not compatible with alpine
RUN npm install

# Rebuild the source code only when needed
FROM node:18.2.0-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY client .


# 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
RUN npm run build

# Production image, copy all the files and run next
FROM node:18.2.0-alpine AS runner
WORKDIR /app

RUN apk add --no-cache dumb-init bash

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

# required for sed from env.sh to work in the docker container
RUN chown -R nextjs:nodejs /app

# You only need to copy next.config.js if you are NOT using the default configuration
COPY --from=builder --chown=nextjs:nodejs /app/next.config.js ./
COPY --from=builder --chown=nextjs:nodejs /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/package.json ./
COPY --from=builder --chown=nextjs:nodejs /app/entrypoint.sh ./entrypoint.sh
COPY --from=builder --chown=nextjs:nodejs /app/env.sh ./env.sh

# 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

ENTRYPOINT ["./entrypoint.sh"]
# use `dumb-init`, not `npm start` to make sure signals are passed properly and node don't run as pid 1
# cf https://snyk.io/blog/10-best-practices-to-containerize-nodejs-web-applications-with-docker/
# NOTE: this value will be overriden in Kubernetes, to set maxOldSpace value dynamically
CMD ["dumb-init", "node", "server.js"]

// entrypoint.sh

#!/bin/sh

echo "starting entrypoint"

./env.sh

# Hand off to the CMD
# cf https://stackoverflow.com/questions/42857897/execute-a-script-before-cmd
exec "$@"

I hope this can help someone out there on the road to dynamic configuration...

[saqib-ahmed]

Worked like a charm.

[baptisteArno]

I'm replacing environment variables during runtime using the entrypoint technique that replaces the values (#17641 (comment)).

It mostly works but I have a weird behavior. Here is what I check in a component:

console.log(
    process.env.NEXT_PUBLIC_SMTP_AUTH_DISABLED,
    process.env.NEXT_PUBLIC_SMTP_AUTH_DISABLED === 'true'
  )

It logs "true" false. I would expect the last log to be true.

So I checked the built file (after the value injection) to retrieve this log: console.log("true", "true" === "true");

Why doesn't it print out "true" true? 🤯

I'm suspecting static generation, but I'm not sure to understand. Can someone explain to me?

[AlejandroRodarte]

I am also having this problem when replacing environment variables during runtime.

console.log('process.env.NEXT_PUBLIC_ENV', process.env.NEXT_PUBLIC_ENV); // process.env.NEXT_PUBLIC_ENV = production-docker
console.log(
  "process.env.NEXT_PUBLIC_ENV === 'production-docker'?: ",
  process.env.NEXT_PUBLIC_ENV === 'production-docker'
); // false

This happens only in production. In development mode it works properly.

[AlejandroRodarte]

@baptisteArno I found out that extracting environment variables from next/config instead of process.env solved the issue.

import getConfig from 'next/config';

const { publicRuntimeConfig } = getConfig();

export const IS_DOCKER =
  publicRuntimeConfig.NEXT_PUBLIC_ENV === 'production-docker' ||
  publicRuntimeConfig.NEXT_PUBLIC_ENV === 'development-docker';

You only need to declare the public environment variables you desire to extract on next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  // ...
  publicRuntimeConfig: {
    NEXT_PUBLIC_ENV: process.env.NEXT_PUBLIC_ENV,
  },
};

module.exports = nextConfig;

Now replacing NEXT_PUBLIC_ environment variables before running next start works with assertions such as ===.

[mihaic195]

This solution worked for me: https://raphaelpralat.medium.com/system-environment-variables-in-next-js-with-docker-1f0754e04cde

[CopyJosh]

The solid examples above are useful for getting the env variables from .env files or in the docker container.. but having trouble tackling a case where the docker container is built and deployed to ec2/fargate, and the env variables are passed into the docker run -e ... command, not sourced from a .env or .env.production file.

[vorillaz]

Just published a detailed guide about using public env variables along with Docker.

You can find the guide on my blog https://www.vorillaz.com/nextjs-docker-env, and you can also explore the sample application as well https://github.com/vorillaz/tutorials/tree/main/docker-nextjs-env

[alamenai]

Thank you @vorillaz but my env variables do not change during the runtime.

ISSUE : vorillaz/tutorials#1

[vorillaz]

Replied on the issue and also leaving here some notes as a reference:

• Variables prefixed with NEXT_PUBLIC_ are statically replaced during build time, you can pick a different prefix and guard what's been added to the .env files of yours using envsafe or a similar library. In the tutorial I am prefixing public variables as DOCKER_
• If you need to just change the passed through variables per environment, you can still reference my other tutorial: https://www.vorillaz.com/nextjs-docker#envinromental-variables. A sample Dockerfile can be found here: https://github.com/vorillaz/tutorials/blob/main/docker-nextjs-app/Dockerfile

[alamenai]

@vorillaz's solution worked well for me.

[jimmyzzxhlh]

I think the problem with this approach is that the first time the client side renders, the environment variables are not available yet (as the state is empty {}).

[Mostafa-dayasoft]

@alamenai

Could you please share your solution , im using azure to pass env from app setting

[JonasDoe]

We're loading many of env variables as constants like this:
export const SOME_URL = trimTrailingSlash(process.env.NEXT_PUBLIC_SOME_URL || 'https://some-default.tld'
Sadly, this is totall incompatible with Next.js bundling as well the workarounds mentioned here. I really don't see the point of this unflexible bundling ... Next.js enforces some approaches here which break with the paradigm to build the docker image only ones and deploy it at many places.
Another case where all alternatives mentioned here won't work is in middleware - I have to pass those env variables (e.g. whether to redirect to the test or the prod system) are request params now.

[kevcoxe]

Hi! @firefart Maybe you can use this approach, first set enviroment variable with a specific string in build time and then use an entrypoint file to replace this string with the docker enviroment variabless value.

I don't know if you lose some benfits of next.js

Docker file:

FROM node:12 as builder

WORKDIR /usr/src/app

COPY . .

RUN yarn

# Building app
RUN NEXT_PUBLIC_ENVIROMENT_VAR=APP_NEXT_PUBLIC_ENVIROMENT_VAR yarn build

# Permisions to execute script
RUN ["chmod", "+x", "./entrypoint.sh"]
ENTRYPOINT ["/usr/src/app/entrypoint.sh"]

CMD [ "yarn", "start" ]

entrypoint.sh

#!/usr/bin/env bash
set -Ex

function apply_path {

    echo "Check that we have ENVIROMENT_VAR vars"
    test -n "$ENVIROMENT_VAR"

    find /usr/src/app/.next \( -type d -name .git -prune \) -o -type f -print0 | xargs -0 sed -i "s#APP_NEXT_PUBLIC_ENVIROMENT_VAR#$ENVIROMENT_VAR#g"
}

apply_path
echo "Starting Nextjs"
exec "$@"

Docker run:

docker run -e ENVIROMENT_VAR=value_envioment_var image_name

Here is what I did to solve the issue, I took inspiration from @rboixaderg with the entrypoint.sh. In my Next.js project I have a .env.example with all of the examples and dummy data for the ENV vars I will be using in the project. The Dockerfile will copy over the .env.example file as .env and build Nextjs. When you run the docker container it will run the entrypoint.sh which will read in all of the ENV vars that are set in your .env.example and then check if any of those values are current ENV vars (because you set them when running your docker container). It then does the find and replace with sed for all files in the .next dir replacing the dummy data with the actual values you passed in when running the container.

I have put this all into a gist for anyone interested https://gist.github.com/kevcoxe/4e8030fb5c2c1a580137d5e2e202812b

[JonasDoe]

This sed thing is smart, but I think I'ld prefer something less magical and more robust (when it comes to changes in Next.js bundling behavior etc). Also, I wanted to utilize env injections from all places, not just .env (e.g. in our case set in ArgoCD).
So maybe it helps someone, here's a sketch of my approach. It's basically about creating a short-living, local server instance on startup, which provides NEXT_PUBLIC_ env variables (as well as possibly other data injected at delivery time). The app fetches those variables and could either set them at process.env - what I found a bit wonky - or provide them in a Context etc. Since I also had some use cases where I wanted to injected public variables at server side and even at top level (so without hooks or async calls), I additionally established also a new prefix: DYNAMIC_NEXT_PUBLIC_, which can be accessed at server side via process.env (since it's effectively a private variable for Next.js and therefore can be injected on startup), but will also be passed to the client-side afterwards.

So here's the bare-bones server, without the need for any new dependencies:

import http from 'http';

const server = http.createServer((req: http.IncomingMessage, res: http.ServerResponse) => {
  try {
    switch (req.url) {
      case '/env': {
        const envData: { [envKey: string]: string | undefined } = {};
        for (const k of Object.keys(process.env)) {
          if (k.startsWith('NEXT_PUBLIC_') || k.startsWith('DYNAMIC_NEXT_PUBLIC_'))
            envData[k] = process.env[k];
        }
        res.end(JSON.stringify(envData));
        return;
      }
      case '/shutdown':
        res.end();
        return process.exit(0);
      default:
        res.writeHead(404);
        res.end();
    }
  } catch (err) {
    console.error(err);
    if (typeof err === 'object' && err != null && 'message' in err && typeof err.message === 'string') {
      res.write(err.message);
    }
    res.writeHead(500);
    res.end();
  }
});

server.listen(3001, () => console.log('Serving descriptions on port', 3001));

This is how I fetch it at the RootLayout or RootPage:

let fetchedData:  { rawEnvData: string; } | undefined = undefined;

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  if (fetchedData == null) {
    const envRes = await fetch('http://localhost:3001/env', { cache: 'no-store' });
    if (!envRes.ok) {
      throw new Error(`Fetching the env data failed: ${envRes.status} (${envRes.statusText})`);
    }
    fetchedData = { rawEnvData: await envRes.text() };
    if (process.env.NODE_ENV === 'production') // on dev, runtime recompiles will fail otherwise
      void (await fetch('http://localhost:3001/shutdown', { cache: 'no-store' }));
  }
  return (
    <html>
      <body>
        <MyNonRSCComponent envData={fetchedData.rawEnvData}>
          {children}
        </MyNonRSCComponent>
      </body>
    </html>
  );
}

Of course, this rawEnvData must get JSON.parsed in MyNonRSCComponent and processed.

In the package.json I set up those scripts:

  "scripts": {
    "dev": "npm run dev:serve-nextjs-data & next",
    "build": "next build && npm run build:serve-nextjs-data",
    "start": "npm run start:serve-nextjs-data & next start",
    "dev:serve-nextjs-data": "node -r ts-node/register --env-file=.env $([ -f .env.local ] && echo \"--env-file .env.local \") serveNextjsData/serve.ts",
    "build:serve-nextjs-data": "cd serveNextjsData && tsc && cd ..",
    "start:serve-nextjs-data": "node --env-file=.env serveNextjsData/serve.js",
}

In case you have a multi-staged Dockerfile, make sure to copy the transpiled serve.js.

I'm still startled that Next.js enforces such an error-prone, pointlessly complex way to comply with a common paradigm for managing deployments. If somebody has some proposols on how to improve that approach, I'ld be grateful, too. I'm especially unhappy how I start both processes at once, npm-run-all might be an alternative. Also, this approach doesn't prevent developers from accessing process.env.PUBLIC_NEXT_MY_VAR (or process.env.DYNAMIC_PUBLIC_NEXT_MY_VAR) at client side (instead of the Context), leading to unexpected results.

[brianmriley]

Just in case anyone else runs into this on Next 14 with App Router... I opted for build once, deploy everywhere and created a simple NextJS API route that accessed the env vars and gave them back to the UI to persist to a store or to use directly in CSR comps, etc. The key is using export const dynamic = "force-dynamic";

Here's a full example:

export const dynamic = "force-dynamic";

import { ConfigDto } from "@/model/dto/config.dto";
import { Logger } from "@/util/Logger";
import { NextResponse } from "next/server";

export async function GET() {
    const logger = Logger.createLogger(`ConfigApi`, false);
    const config: ConfigDto = {
        env: process.env.NEXT_PUBLIC_ENV,
        apiUrl: process.env.NEXT_PUBLIC_API_URL,
        stripeApiKey: process.env.NEXT_PUBLIC_STRIPE_PUBLIC_KEY,
    };
    logger.debug(`fetchConfig( Stripe API key: ${JSON.stringify(config, null, 2)} )`);

    return NextResponse.json(config);
}

And I tested it out with a quick deployment to AWS ECS like this:

"use client";

import { ConfigDto } from "@/model/dto/config.dto";
import { useEffect, useState } from "react";

const FooBar = () => {
    const logger = Logger.createLogger(FooBar.name, false);
    
    useEffect(() => {
        const fetchConfig = async () => {
            const response = await fetch(apiEndpoints.config.root);
            const config: ConfigDto = await response.json();

            if (config.stripeApiKey) {
                logger.debug(`fetchConfig( Stripe API key: ${config.stripeApiKey} )`);
            } else {
                logger.error(`fetchConfig( Stripe API key not found )`);
            }
        };

        fetchConfig();
    }, []);

    return (
        ...
    );
};


export default FooBar;

Side note, my API is running in ECS as well so I made my NextJS API dir like this src/app/next-api as my real API on ECS is /api/* -- this way they don't conflict. HTHs.

[JonasDoe]

Hm, I cannot confirm this is working. And api endpoint under app/api/env with

export const dynamic = 'force-dynamic';

export function GET() {
  return new Response(JSON.stringify({ NEXT_PUBLIC_MY_TEST_VAR: process.env.NEXT_PUBLIC_MY_TEST_VAR }));
}

won't reflect the change if run with
NEXT_PUBLIC_MY_TEST_VAR=initial next build && NEXT_PUBLIC_MY_TEST_VAR=changed next start. curl http://localhost:3000/api/env -s will convey {"NEXT_PUBLIC_MY_TEST_VAR":"initial"}.

Or am I missing something from your solution?

[chunghei0116]

I just deployed my next js application on my K8s server. After setting up ingress, it works fine. And now, I would like to use ConfigMap to mount the .env to redefine the env that I define when the image was being built.

[jimmyzzxhlh]

@vorillaz's solution seems to be working relatively well. The idea is to have the environment variables exported from server side to client side components. I made a little bit tweak on his above solution to ensure that the environment variables are initialized only once.

// env.ts
"use server";

export type EnvType = {
  NEXT_PUBLIC_APP_ENVIRONMENT: "development" | "staging" | "production" | undefined;
};

export const getEnv = async () => ({
  // You can define as many NEXT_PUBLIC environment variables here as you want. 
  NEXT_PUBLIC_APP_ENVIRONMENT: process.env.NEXT_PUBLIC_APP_ENVIRONMENT as
    | "development"
    | "staging"
    | "production"
    | undefined,
});

// EnvProvider.tsx

"use client";

import { createContext, useContext, useEffect, useRef, useState } from "react";
import { EnvType, getEnv } from "./env";

export const EnvContext = createContext(null as EnvType | null);

export const EnvProvider = ({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) => {
  const [env, setEnv] = useState<EnvType | null>(null);
  // Create a reference to insure that the environment provider is only initialized once. 
  const initialized = useRef(false);

  useEffect(() => {
    if (!initialized.current) {
      initialized.current = true;
      getEnv().then((env) => {
        setEnv(env);
      });
    }
  }, []);

  if (env === null) {
    return null;
  }

  return <EnvContext.Provider value={env}>{children}</EnvContext.Provider>;
};

export const useEnv = () => {
  return useContext(EnvContext);
};

To use the provider:

function ClientComponent() {
  const env = useEnv();
  const environment = env.NEXT_PUBLIC_APP_ENVIRONMENT;
}

You might want to do something like this in layout.tsx:

export default function Layout({children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html>
      <body>
        <EnvProvider>{children}</EnvProvider>
      </body>
    </html>
  )
}

On Docker / K8S side, set NEXT_PUBLIC_APP_ENVIRONMENT or other environment variables that start with NEXT_PUBLIC_ with the values that you need.

[calugar-claudiu-c]

The solution from the following link: https://dev.to/vorillaz/nextjs-with-public-environment-variables-in-docker-4ogf worked very well for me, especially the one from the subtitle: "A More Consistent Approach."

[JonasDoe]

The thing is that all of these solutions basically recommend to drop the NEXT_PUBLIC_ prefix and the according logic for good. I really don't get what Vercel is trying to achieve here.

[Djay77]

And how do you handle statics contents generated at build time ?

1/ Statics contents will be generated, for example, in a github/gitlab pipeline with test env
2/ NEXT_PUBLIC are updated by script
3/ X days later, we deploy (no build) in production => we have statics contents with old test data !

[hanisntsolo]

So i am writing (on monday) after three days[Friday, Saturday & Sunday] of unsuccessful attempts.
All you need is to put.

export const dynamic = "force-dynamic";

on top of the server side file where you are referencing the variables dynamically.

This is the code which I made working with above.

// /app/api/github/config/route.ts
export const dynamic = "force-dynamic";
import { NextResponse } from 'next/server';

export async function GET() {
    const config = {
        GITHUB_CLIENT_ID: process.env.NEXT_PUBLIC_GITHUB_CLIENT_ID,
        GITHUB_CALLBACK_URL: process.env.NEXT_PUBLIC_GITHUB_CALLBACK_URL
    };
    console.log('Debug :: github config : ', config);
    return NextResponse.json(config);
};

and this is the client side code which I am using to call the above and it works now in production.

'use client'
import React, { useState, useEffect, useCallback } from 'react';
import { Modal, Button, Form, Input, Flex, message } from 'antd';
import { GoogleLogin } from '@react-oauth/google';
import { GithubLoginButton } from 'react-social-login-buttons';
import { CredentialResponse } from '@react-oauth/google';
import { useUser } from '../usercontext/UserContext';
export const dynamic = "force-dynamic";

interface SignInModalProps {
  onSuccess: (email: string, message: string) => void;
}
const SignInModal: React.FC<SignInModalProps> = ({onSuccess}) => {
  const [isModalVisible, setIsModalVisible] = useState(false);
  const [isSignup, setIsSignup] = useState(false);
  const [githubClientId, setGithubClientId] = useState('');
  const [githubCallbackUrl, setGithubCallbackUrl] = useState('');
  const GITHUB_SCOPES = 'user';
  const { user, setUser } = useUser();
  useEffect(() => {
    const fetchGithubConfig = async () => {
      try {
        const res = await fetch('/api/auth/github/config');
        const data = await res.json();
        console.log('Github Config:', data);
        setGithubClientId(data.GITHUB_CLIENT_ID);
        setGithubCallbackUrl(data.GITHUB_CALLBACK_URL);
      } catch (error) {
        console.error('Error fetching Github config:', error);
      }
    };
    fetchGithubConfig();
  }, []);

[vorillaz]

For those still interest, you can also use global exposed variables both to client and server components with proper validation as well.
I wrote a detailed article in my blog
https://www.vorillaz.com/nextjs-public-variables

[sokhuong-uon]

How could we access those envs in client component?

When I mark var.tsx as client component, it stop working.

'use client';
export const Vars = () => {
  return (
    <div className="flex min-h-[350px] w-full justify-center p-10 items-center">
      <div className="flex w-[300px] w-[300px] items-center justify-center rounded-md border border-dashed text-sm">
        <pre className="text-balance font-mono text-mono">
          PUBLIC_VARIABLE={globalThis.PUBLIC_VARIABLE}
          PUBLIC_MY_NUM={globalThis.PUBLIC_MY_NUM}
          PUBLIC_BOOL={globalThis.PUBLIC_BOOL}
          PUBLIC_PORT={globalThis.PUBLIC_PORT}
        </pre>
      </div>
    </div>
  );
};

my application need to use React Query on the client which need access to NEXT_PUBLIC_API_URL. I'm going through the pain now 😂.

[enzocomics]

I've been following this topic for a while and I found a solution that worked for my case: next-runtime-env

This is what I have. My layout.tsx:

import { env, PublicEnvScript } from "next-runtime-env"

export default function RootLayout(){
  const publicEnv = env("NEXT_PUBLIC_ENV_TEST")
  return (
    <html>
      <head>
        <PublicEnvScript />
      </head>
      <body>
        <p>public env test: {publicEnv}</p>
      </body>
      </html>
   )
}

My Dockerfile (it doesn't seem to work with multi-stage Dockerfiles):

# Use Docker's Node Alpine Linux image as the base Image
FROM node:alpine3.20 AS base

# Set the working directory inside the container
WORKDIR /app

# Copy `package.json` & `package-lock`.json to the root folder 
COPY package*.json ./

# Install the node module dependencies
RUN npm install

# Copy everything else
COPY . . 

# Build the Next.js app
RUN npm run build

# Set the environment
ENV NODE_ENV=production

# Expose the port Next.js needs
EXPOSE 3000

# Run the server!
CMD ["node", ".next/standalone/server.js"]

My docker-compose.yml:

services:
  nextjs:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - NEXT_PUBLIC_ENV_TEST="hello world"

Now you only need to build the container the first time! If you change the ENV variable, you just need to run docker compose up again. I hope it works for you too.

[mrksph]

Hi @leerob,

I’d really appreciate some guidance on what feels like a recurring pain point: handling environment variables for a Dockerized Next.js app with a single image and multiple environments—specifically without relying on platforms like Vercel.

The Next.js docs touch on the basics, but they don’t provide enough detail for this use case. For example:

• NEXT_PUBLIC variables are inlined at build time, so they aren’t suitable for runtime configuration.
• Server-only variables don’t make it to the client, which is fine, but how do we dynamically provide different values per environment when using Kubernetes with plain Docker images?

If the image is built once and then deployed to multiple environments (e.g., staging, production), what’s the recommended approach for injecting the correct variables at runtime? Most solutions I’ve found feel hacky or overly complex like using a script that replaces the variables, using a npm library just to use runtime environments or having to call any of the Dynamic APIs to opt in into runtime environments (exclusively for server side components).

Would love to hear your thoughts on this (or see it covered in the docs more in depth). I know I’m not alone in struggling with this.

Thanks!

[leerob]

Thanks for the feedback! I agree that we should likely link to register() from the environment variables docs. Realistically most people won't look at the self-hosting docs to find that video/repo 😄

[mrksph]

Just realized it actually is already linked, though a simple link to the register() function is not enough, IMHO.

I mean, I'm not expecting the NextJs docs to have a step-by-step tutorial on how to make a enterprise-level app, ready to launch and be used by 10M users concurrently out-of-the-box. But an example on how to setup different environments + single image docker would be great.

[vihsonic]

Hi, @mrksph
I am running into the same issue and have tried several ways but it is not working yet.
Could you please share your solution(git) here, just in case?

[mlarcher]

For what it's worth, the solution described in #17641 (reply in thread) has been a decent workaround to us for years now 🤷

[themagickoala]

@leerob I notice that you haven't addressed @JonasDoe's question here about doing this with client-side variables. Your example shows how to fetch variables at runtime and access them from the server. My requirement is for client-side variables which differ per-environment, where the environments have dynamic names. I can't do this via a .env.staging file, as there's no static set of variables here. It would be nice to know if there's a standard recommended pattern for doing this, potentially with the new client-instrumentation hook?

[rohan-chaturvedi]

I took a crack at using the instrumentation file to try and create a better solution for runtime env vars, but ultimately found that it doesn't really help with the core problem of how public environment variables are handled. My approach going forward is going to be to avoid using the NEXT_PUBLIC_ prefix entirely, and just pass required env vars from server to client components. Either way, I wrote a quick blog about using instrumentation for this purpose: https://phase.dev/blog/instrumenting-nextjs-with-runtime-secret-injection/

[imShakil]

I had to use docker entrypoint to update string lines inside chunks forcefully using bash script. Its working but tricky. Details on medium