What is the best way to use NextJS with docker?

[wilsonneto-dev]

Hi guys,
whats the best way to use NextJS in a docker image/container?

IS a good choice the image below?

FROM node:12
WORKDIR /usr/src/app

COPY . ./

# building the app
RUN npm i
RUN npm run build

# Running the app
CMD [ "npm", "start" ]

Thanks so much!

[frankievalentine]

Alternatively, for yarn:

FROM node:alpine

RUN mkdir -p /usr/src/app
ENV PORT 3000

WORKDIR /usr/src/app

COPY package.json /usr/src/app
COPY yarn.lock /usr/src/app

# Production use node instead of root
# USER node

RUN yarn install --production

COPY . /usr/src/app

RUN yarn build

EXPOSE 3000
CMD [ "yarn", "start" ]

[kachkaev]

Before RUN yarn install --production, you can also add ENV YARN_CACHE_FOLDER=/dev/shm/yarn_cache. This will reduce the size of the final image because it will no longer contain unneeded archives in yarn cache dir. It is something like ~/.yarn/cache by default, while /dev/shm is a temp folder that’s not included in the image.

By default, the size of /dev/shm is quite small so you might end up with "no space on disk" error when running yarn install. Adding --shm-size 1G to docker build command solves this.

Adding --frozen-lockfile to yarn install is also a good idea. This argument makes sure that the dependencies you end up with are what you expect them to be.

[frankievalentine]

Thank you, just getting started with Docker so this is helpful!

[awareness481]

Similarly to --frozen-lockfile, npm ci --only-production is also a good idea. The main benefit is

If dependencies in the package lock do not match those in package.json, npm ci will exit with an error, instead of updating the package lock.

[maxymapp]

Thanks a lot!

RUN mkdir -p /usr/src/app is redundant as WORKDIR /usr/src/app will create the dir if it doesn't exist.
Also,

COPY package.json /usr/src/app
COPY yarn.lock /usr/src/app

can be simplified to

COPY package.json yarn.lock ./

as WORKDIR /usr/src/app will navigate to /usr/src/app.

Final result:

WORKDIR /usr/src/app

COPY package.json yarn.lock ./

See docs: https://docs.docker.com/engine/reference/builder/#workdir

[hane-smitter]

No one is mentioning node_modules is getting copied over and over-riding the one that was created with yarn install in this part of the Dockerfile:

RUN yarn install --production

COPY . /usr/src/app

This is assuming a user already generated the node_modules folder in their project. I know most likely the node_modules folder created is the same but the fact that it is over-riding what was created by yarn install command ran in the container, makes me cringe😬.

[yordis]

This is a more optimized version leveraging multi-stage.

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

WORKDIR /opt/app
COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile

# Rebuild the source code only when needed
# This is where because may be the case that you would try
# to build the app based on some `X_TAG` in my case (Git commit hash)
# but the code hasn't changed.
FROM node:lts-alpine AS builder

ENV NODE_ENV=production
WORKDIR /opt/app
COPY . .
COPY --from=deps /opt/app/node_modules ./node_modules
RUN yarn build

# Production image, copy all the files and run next
FROM node:lts-alpine AS runner

ARG X_TAG
WORKDIR /opt/app
ENV NODE_ENV=production
COPY --from=builder /opt/app/next.config.js ./
COPY --from=builder /opt/app/public ./public
COPY --from=builder /opt/app/.next ./.next
COPY --from=builder /opt/app/node_modules ./node_modules
CMD ["node_modules/.bin/next", "start"]

[dvidsilva]

@yordis IS there an older, or different dockerfile that doesn't leverage multi stage? many docker clients we're using can't be updated 🤷🏼‍♀️

[malgin1983]

This script is not work with my app (``

=> [internal] load build definition from Dockerfile 0.0s
=> => transferring dockerfile: 37B 0.0s
=> [internal] load .dockerignore 0.0s
=> => transferring context: 2B 0.0s
=> [internal] load metadata for docker.io/library/node:lts-alpine 0.7s
=> [runner 1/6] FROM docker.io/library/node:lts-alpine@sha256:3bca55259ada636e5fee8f2836aba7fa01fed7afd0652e12773ad44af95868b9 6.9s
=> => resolve docker.io/library/node:lts-alpine@sha256:3bca55259ada636e5fee8f2836aba7fa01fed7afd0652e12773ad44af95868b9 0.0s
=> => sha256:5e48ab13756bb607cfc8fcb7edb126389aefbdce0255ae98bb9c81e9b2e76d77 2.35MB / 2.35MB 1.3s
=> => sha256:3bca55259ada636e5fee8f2836aba7fa01fed7afd0652e12773ad44af95868b9 1.43kB / 1.43kB 0.0s
=> => sha256:7001ff8aabeabe8844ef8e7613afaf723e832e19fba55bf1b9929739c7723ece 1.16kB / 1.16kB 0.0s
=> => sha256:39f4f776940eb50164084d62d5a44106ff9958b6f13d0cb4a938f42487d0eaa8 6.53kB / 6.53kB 0.0s
=> => sha256:a0d0a0d46f8b52473982a3c466318f479767577551a53ffc9074c9fa7035982e 2.81MB / 2.81MB 1.1s
=> => sha256:d5320f804f7bd11fd1bb2d080d4547785045fc9d367149aeeaabaa56925f6514 34.81MB / 34.81MB 4.1s
=> => extracting sha256:a0d0a0d46f8b52473982a3c466318f479767577551a53ffc9074c9fa7035982e 0.3s
=> => sha256:f3e4d3677336839feb69c9dae9854f585ea233eb157145b1df0cf2bcd327faca 448B / 448B 1.3s
=> => extracting sha256:d5320f804f7bd11fd1bb2d080d4547785045fc9d367149aeeaabaa56925f6514 2.3s
=> => extracting sha256:5e48ab13756bb607cfc8fcb7edb126389aefbdce0255ae98bb9c81e9b2e76d77 0.2s
=> => extracting sha256:f3e4d3677336839feb69c9dae9854f585ea233eb157145b1df0cf2bcd327faca 0.0s
=> [internal] load build context 6.7s
=> => transferring context: 245.13MB 6.3s
=> [runner 2/6] WORKDIR /opt/app 0.1s
=> [builder 3/5] COPY . . 2.0s
=> [deps 3/4] COPY package.json yarn.lock ./ 0.0s
=> [deps 4/4] RUN yarn install --frozen-lockfile 44.1s
=> [builder 4/5] COPY --from=deps /opt/app/node_modules ./node_modules 3.2s
=> [builder 5/5] RUN yarn build 38.7s
=> ERROR [runner 3/6] COPY --from=builder /opt/app/next.config.js ./ 0.0s

[runner 3/6] COPY --from=builder /opt/app/next.config.js ./:

---

failed to compute cache key: "/opt/app/next.config.js" not found: not found ``

[edenreich]

Hey, I've improved your version based on what other people posted here and ended up with this final version:

FROM node:17.1.0-alpine3.12 AS development
WORKDIR /app
ENV HOST=0.0.0.0
ENV PORT=3000
ENV NODE_ENV=development
EXPOSE 3000
CMD [ "yarn", "dev" ]

FROM node:17.1.0-alpine3.12 AS dependencies
ENV NODE_ENV=production
WORKDIR /app
COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile

FROM node:17.1.0-alpine3.12 AS builder
ENV NODE_ENV=development
WORKDIR /app
COPY . .
RUN yarn install --frozen-lockfile && NODE_ENV=production yarn build

FROM node:17.1.0-alpine3.12 AS production
WORKDIR /app
ENV HOST=0.0.0.0
ENV PORT=3000
ENV NODE_ENV=production
COPY --chown=node --from=builder /app/next.config.js ./
COPY --chown=node --from=builder /app/public ./public
COPY --chown=node --from=builder /app/.next ./.next
COPY --chown=node --from=builder /app/yarn.lock /app/package.json ./
COPY --chown=node --from=dependencies /app/node_modules ./node_modules
USER node
EXPOSE 3000
CMD [ "yarn", "start" ]

To build it for production:

docker build -t <tag> --target production .

To use it locally for development:

docker build -t <tag> --target development .
docker run --rm -it --name <name> -p 3000:3000 -v ${PWD}:/app -w /app <tag>

The only improvement you would see here is that I'm copying production dependencies rather than development dependencies, that's saving approx. 100MB of image size, final size of this container image ~ 354MB.
I also use a fixed version of nodejs container image.
I was not sure what ARG X_TAG is, that's why I omitted it from the instructions set, I would be curious to understand what's the use-case ? Not sure I understand how you use it.
With this final version we also use a non-root user for the build and all of the files copied over are owned by that user.
This version works perfectly for me and I think it's kept generic for every NextJS installation.

Enjoy!

[kachar]

Nicely done!

Looks like you don't install dependencies in the target development - are you mounting them locally?

[edenreich]

Nicely done!

Thanks! :)

Looks like you don't install dependencies in the target development - are you mounting them locally?

That's correct, probably at the first time you'll need execute yarn install inside of the container to have all the development dependencies.

docker exec -it <name> /bin/sh
yarn

[stefanprobst]

when using next/image, do you put the image cache folder (.next/cache/images) on a docker volume?

[romelgomez]

Hi @Simonpedro

how do I deploy the doker with the .env.development ?

The docker pick the .env.production

[DanielBailey-web]

Does the image optimization (compression) need to happen every time the docker image is reused (cold start)?

[alaintalk]

nice this is helpful

[alekskorovin]

In addition to that please make sure to include the 'sharp' dependency in your package.json as it's essential if you're deploying not on vercel and you're gonna use next/image.

[MartinFiskaly]

@alekskorovin How did you manage to install sharp? I installed it on the monorepo as a dependency but the standalone build is still throwing the "sharp missing" error. I checked inside the build folders and sharp is in the package.json and the node_modules

[mvasin]

I noticed that the SIGTERM isn't passed: CTRL-C doesn't work and I have to kill a container from a separate terminal window after the start. I tried both CMD ["node_modules/.bin/next", "start"] and CMD ["yarn", "start"]. How do you solve it?

[mvasin]

Indeed, that helps, thank you!

But I'm still curious why is it required; if I do yarn start in a terminal, I'm able to stop the process with CTRL-C. What's the difference if the same process is started within the container with CMD ["yarn", "start"]. It should have PID 1 and directly receive signals, right?

I thought maybe the entrypoint.sh from the base image messes things up, but using ENTRYPOINT ["node_modules/.bin/next", "start"] instead of CMD ["node_modules/.bin/next", "start"] doesn't help.

[stefanprobst]

i'm not sure tbh. but using --init will use docker built-in tini as pid 1.

[stefanprobst]

for reference: https://github.com/nodejs/docker-node/blob/master/docs/BestPractices.md#handling-kernel-signals

[ivan-kleshnin]

Beware that Yarn v1 still have unfixed bugs related to this topic yarnpkg/yarn#4667

Currently yarn terminates with exit code 1 when it receives a SIGTERM without waiting for the child to exit and without passing its child's exit status up the chain.

[alexey-sh]

yarn start and npm start are kind of bad practice.

[TommySorensen]

I have docker running our NextJS v10 website with multiple environments, but since i am using getStaticProps with getStaticPaths i can't reuse that build to both develop and qa/staging environment, because those generated files will contain data from an develop cms endpoint. Has any figured out a better way to avoid building for every single target?

[DanielBailey-web]

@dpbeaumont You can COPY your .production.env file into the build environment and then just not copy it into the running env. (which would make it use your hosted secrets instead)

[ItsDaveB]

@DanielBailey-web By build environment, do you mean where the application hosting infrastructure is, if so this will not help with a containerized application. The image that is containerized is done at build time (docker build), so still needs the correct secrets to get the static pages from the headless CMS when the container is built. Then it's the same issue, you can only have one container image pointing to one headless cms environment to generate the static pages, this piece seems really strange and does not factor in containerization, because for example a container image built in dev, might point to a dev environment in the cms, but the dev pages might be different to what's in test or prod. So essentially you are building up the wrong static pages which defeats the point of static generation in my opinion.

[ItsDaveB]

Yes, would be good to near from some NextJS devs for how they saw this working as it does seem we are using docker and containerization best practices and it is add unnecessary complexity with NextJS.

Agreed, with the new standalone support in 12.1 and also the documented docker example here. https://github.com/vercel/next.js/tree/canary/examples/with-docker

It seems as though this functionality needs to align with docker best practices, it feels like a gap for me.
Only way I can think of is generating the static content upon first request to the website potentially with an opt in feature.
A few benefits, I can think of is:

• This process would fall in line with deployment best practices, health checks, kubernetes etc.
• The docker build stage is abstracted from the CMS, meaning if the CMS goes down the image is still built.
• The docker build can be done once, and the same image can flow through multiple environments, without an image for each environment.
• Secrets can be abstracted from the dockerfile and coupled instead to the hosting environment promoting security best practices.

[DanielBailey-web]

@dpbeaumont I was referencing from the example with-docker/Dockerfile FROM node:16-alpine AS builder and FROM node:16-alpine AS runner as the build environment and the run environment respectively.

[dm17]

@dpbeaumont I'm curious if you've made headway or found explanations from nextjs devs about their recommended solutions! There's been a lot more detail in another thread about why "build time networking" is increasingly difficult in docker: docker/buildx#175 (comment) (great comment about the current state of things)
So with this in mind, I wonder how Vercel containerizes everything in production - or perhaps they don't bother? For some reason the majority of other comments in this thread seem to miss the idiosynchrasies of why docker+nextjs in multi-service build environments is incongruous.

[frankievalentine]

What would be the best way to set up a docker-compose.yml?

[kennethnwc]

I would like to know too.
I am also trying to make a docker-compose setup.
You may visit this docker-compose setup and any suggestion is welcome.

[Tokenyet]

@kennethnwc Thanks for sharing your setup! However, I think It's worth mention that It has some risk for the parent machine is Windows or Macos with node_modules (ref: 1, 2), but If you are on linux, I think there is no problem 😄

[leerob]

Thanks to lots of valuable feedback in this thread, we've shipped the first version of the Docker deployment docs. We will continue to evolve this with the best practices for using Next.js with containers.

[guidorice]

For next.js devs, and whoever else is using k8s. @fabb posted this guidance:

# we cannot call npm/yarn here because that would not forward SIGTERM correctly to the node process which is necessary for graceful kubernetes shutdown
# use CMD exec form (with brackets) to avoid starting a shell
# ...
CMD ["node", "--max-http-header-size=16000", "./.server/server.js"]

So that's using a custom server.js.... What's the solution for folks using the npm start or yarn start as recommended by the next.js docs here https://nextjs.org/docs/deployment#docker-image ?

I just tried this command on my dev machine, but it exits immediately with no output:

node ./node_modules/next/dist/server/next.js start

Surely there is some node .js magick that someone already figured out. Alternatively, I could try writing a script that imports npm and runs the start script procedurally, but that seems like it should not be necessary.

[guidorice]

Actually, it may be a moot point, because it appears server running with CMD [ "npm", "run", "start" ] does do the right thing with a termination event:

docker kill --signal="SIGTERM" container

edit: fabb describes the problem well in the followup:

[fabb]

No it does not. It immediately kills the app which is not graceful. It will immediately abort an in-progress request and also all requests that are already enqueued for this pod. The app should only quit itself a few seconds after SIGTERM in order to be graceful and finish serving its enqueued requests. k8s will not enqueue further requests to a pod that it already sent SIGTERM to, but it cannot reschedule already enqueued requests to other pods. In my app I just wait 5 seconds before quitting the app, that fixed nearly all of the cancelled requests during deployment or downscaling. Another solution would be to just ignore SIGTERM, k8s then would force-quit the pod after 30 seconds. Not ideal because the longer the pod takes to shutdown, the longer deployments take because of max surge. The cleanest way would be to track the pool of enqueued requests and quit when it‘s empty, but it was too complicated with express and not worth it for me.

Here‘s a nice blog post: https://blog.risingstack.com/graceful-shutdown-node-js-kubernetes/

Note that the blog post is wrong about the livenessProbe - according to k8s documentation, during shutdown (starting when SIGTERM is being sent) the livenessProbe is no longer of relevance.

[guidorice]

Thanks @fabb for the clarification and correction.

[acederberg]

Hi @leerob!

I'm late to this party, but it appears the link in your comment is no longer correct, I get "404" (https://github.com/vercel/next.js/blob/canary/docs/deployment.md). Is it possible it exists on another branch?

UPDATE: It would appear that this is the link we need.

[inductor]

I highly do not recommend not using alpine based image since it may cause performance degradation and compatibility issue when bundling native modules.

Use gcr.io/distroless/nodejs-debian10 instead.

Ref. https://github.com/GoogleContainerTools/distroless#docker

[leerob]

Please open a PR if you believe the official docs need updated 🙏🏼 Thank you!

[inductor]

@leerob I thought this place was for discussion...? Would you like everyone who wants to give their opinion creates a single PR right away? 👀

[leerob]

I highly do not recommend

You seemed pretty convinced 😄 But yes sure, we can let others chime in here!

[limal]

The official Next.js Docker image is not working for my project. It throws below excpetion on production:

TypeError: Object(...) is not a function

It works OK on the next start which makes it incredible troublesome to debug due to large Docker image sizes (500 MB).

I suggest using below much simpler Dockerfile. The performance is as bad as the multi-stage one (compared to CRA) but at least it works:

# Base on offical Node.js Alpine image
FROM node:alpine

# Set working directory
WORKDIR /usr/app

COPY package.json yarn.lock ./
RUN yarn

COPY . .

# Build app
RUN yarn build

EXPOSE 3000

# Run container as non-root (unprivileged) user
# The node user is provided in the Node.js Alpine base image
USER node

# Run npm start script when container starts
CMD [ "npm", "start" ]

[leerob]

Please open a PR if you can identify the root cause of that TypeError 🙏🏼 I don't think we should recommend using a bare Dockerfile in the docs, based on the conversations in this discussion.

Thank you!

[kachar]

@wilsonneto-dev You might wanna check this sample repo/project which integrates next.js + production ready multi-stage dockerfile + docker-compose setup

https://github.com/kachar/yadi/tree/main/web/next.js

The multi-stage build is explained at https://github.com/kachar/yadi#build-multi-stage-build-explained

For clarity I'm posting the contents of Dockerfile here as well

# Build target base #
#####################
FROM node:14-alpine AS base
WORKDIR /app
ARG NODE_ENV=production
ENV PATH=/app/node_modules/.bin:$PATH \
    NODE_ENV="$NODE_ENV"
RUN apk --no-cache add curl
COPY package.json yarn.lock /app/
EXPOSE 3000

# Build target dependencies #
#############################
FROM base AS dependencies
# Install prod dependencies
RUN yarn install --production && \
    # Cache prod dependencies
    cp -R node_modules /prod_node_modules && \
    # Install dev dependencies
    yarn install --production=false

# Build target development #
############################
FROM dependencies AS development
COPY . /app
CMD [ "yarn", "dev" ]

# Build target builder #
########################
FROM base AS builder
COPY --from=dependencies /app/node_modules /app/node_modules
COPY . /app
RUN yarn build && \
    rm -rf node_modules

# Build target production #
###########################
FROM base AS production
COPY --from=builder /app/public /app/public
COPY --from=builder /app/.next /app/.next
COPY --from=dependencies /prod_node_modules /app/node_modules
CMD [ "yarn", "start" ]

HEALTHCHECK --interval=5s --timeout=5s --retries=3 \
    CMD curl --fail http://localhost:3000 || exit 1

[guidorice]

The dockerfile at https://nextjs.org/docs/deployment#docker-image only works with CMD yarn start, it does not work with yarn build, or yarn dev (both complain about missing pages/ dir). So I am not sure of the utility of the dockerfile in practice?

I see how @kachar included a build target development, which runs yarn dev. This is a nice approach but adds complexity by copying node_modules around.

Maybe for next.js docs an improvement would be to provide a docker compose based environment showing both a production usage and a development usage?

edit: ah, yarn build runs in the builder stage, of course.

[kachar]

The yarn build indeed is in builder stage and needs devDependencies like typescript, which are not essential for the final production stage.

This is the main cause for the split and the extra effort of using separate set of node_modules directory around.

This as well makes the final docker image with smallest size possible (no dev deps).

An useful tool to inspect the docker images can be found at https://github.com/wagoodman/dive

[votemike]

I'm not overly familiar with Docker, but I feel that the example repo has been set up so that yarn dev runs for development but yarn start runs for production. I have tried to get this to work, but can't. Am I mistaken?

[fabb]

Never start your application with npm or yarn in your dockerfile. That would immediately end the application when SIGTERM is received, even when the pod currently processes a request or has more requests in the queue. Kubernetes uses SIGTERM to signal a pod that it needs to shutdown within the next 30 seconds, either because a newer application version is being deployed, or when scaling down. You need to use your own SIGTERM handler in your express server, and just exit after a few seconds timeout. And you need to start your application by directly executing node, in order for the SIGTERM signal being forwarded to your application correctly.

https://blog.risingstack.com/graceful-shutdown-node-js-kubernetes/

[gayratv]

Never start your application with npm or yarn

Please, write the correct command to start the application in docker.

[joshes]

@fabb is implying to not use a go-between to start the process. Instead just use node /path/to/startup/script.js.
Also, in the same vein for handling SIGTERM (and other signals) checkout Terminus and healthchecks, shutdown hooks, etc. Really easy to integrate.

[joshes]

How are folks managing environment variables in containerized next apps, especially with SSR NEXT_PUBLIC_* variables. Seems that we have to bind the configuration with the image, which in turn means that a build is required for any environment variable updates (e.g., as opposed to updating a ConfigMap or Secret if running in a k8s cluster). Is this what others are doing?

[fabb]

we are passing an env var (CONTEXT) to the k8s pod to configure it which environment it is running on and which backend urls to use. this way, we only have one docker image build and can just deploy it to any environment.

Here's a quick summary of the configuration:

next.config.js:

    publicRuntimeConfig: {
        context: process.env.CONTEXT,
    },

package.json:

        // note that we don't set the env var for dev mode - in the code we know that when it's undefined, it's running on localhost
        "dev": "cross-env PORT=3010 cross-env NODE_ENV=development nodemon server/server.ts",
        // note that at build time we don't yet know which env the container will run on, so it has to be `CONTEXT=prod`
        // this means for the rendered html on SSG pages, always the prod env is used with everything that implies. but after hydration of the SSG pages, the correct CONTEXT will be used
        "build:next": "cross-env CONTEXT=prod cross-env BUILD_ID=$BUILD_ID ANALYZE=true next build",
        // note that we don't use the `start` script for running the app, because running an application with `npm` or `yarn` in k8s is evil because it breaks graceful shutdown on SIGTERM
        "start": "cross-env TZ=Europe/Vienna cross-env NODE_ENV=production cross-env CONTEXT=$CONTEXT node --max-http-header-size=16000 .server/server.js",

Dockerfile:

# Run container as non-root (unprivileged) user
# The node user is provided in the Node.js Alpine base image
USER node

ENV TZ Europe/Vienna
ENV NODE_ENV production
# we cannot call npm/yarn here because that would not forward SIGTERM correctly to the node process which is necessary for graceful kubernetes shutdown
# use CMD exec form (with brackets) to avoid starting a shell
# note that we do not need to pass the `CONTEXT` env var explicitly here, it will happen implicitly because CMD just uses the available env when being run in k8s
CMD ["node", "--max-http-header-size=16000", "./.server/server.js"]

helm deployment.yaml:

apiVersion: apps/v1
kind: Deployment
...
spec:
  template:
    spec:
      containers:
        - name: {{ include "node-application.fullname" . }}
          env:
          - name: CONTEXT
            value: "{{ required ".Values.context must be set!" .Values.context }}"

server.ts (we use a custom express server):

    server.use(addContextCookie)

...

// this passes the CONTEXT env var value from the server to the client via Set-Cookie, so it can be used in client code too
const addContextCookie = (_req: Request, res: Response, nextMiddleware: NextFunction) => {
    if (process.env.CONTEXT) {
        res.cookie('context', process.env.CONTEXT)
    }
    return nextMiddleware()
}

in the app code:

// INFO: DO NOT USE FOR CONDITIONAL RENDERING - that breaks hydration
export const isServer = () => {
    return typeof window === 'undefined'
}

type Context = 'prod' | 'uat' | 'st' | 'dev' | undefined

// structure of relevant available settings in next.config.js
interface NextConfig {
    publicRuntimeConfig: PublicRuntimeConfig
}

// structure of `publicRuntimeConfig` key in next.config.js
interface PublicRuntimeConfig {
    context?: Context
}

const config = getConfig() as NextConfig | undefined
const publicRuntimeConfig = config?.publicRuntimeConfig

const context = publicRuntimeConfig ? publicRuntimeConfig.context : (process.env.CONTEXT as Context)

// this function can be used in client code to access the CONTEXT env var value
export const getContext = () => {
    if (isServer()) {
        return context
    } else {
        const cookies = cookie.parse(document.cookie)
        return cookies.context
    }
}

If you have any questions, fire away.

[joshes]

Interesting take I hadn't thought of, thanks for the response!

[fabb]

Welcome! We had quite the brainstorming session to come up with this approach 😅

[sambacha]

your dockerfile as show with Alpine does not have locales with it. your not configuring your ENV TZ correctly. Ignoring why you would set TZ to something other than UTC the correct way to implement it in Alpine-based distros is:

RUN apk add --no-cache tzdata
ENV TZ=Europe/Vienna
RUN cp /usr/share/zoneinfo/$TZ /etc/localtime

[dm17]

Any graceful solutions for dealing with NextJS dynamic builds before & during docker image builds?

Basically a docker container has to be up with networking so another can build via API (using getStaticProps / npm run build)? There must be a better way... If it really is for "dynamic builds" so the static pages get generated (like below), then shouldn't happen after the docker images are build instead of during?

info  - Compiled successfully
info  - Collecting page data...
info  - Generating static pages

Doesn't seem like many others encounter this for some reason.

[MauriceArikoglu]

@dm17 Have you found a solution to this hen-egg problem?

[approached]

This works well with RUN NODE_ENV=${NODE_ENV} yarn build:

# Install dependencies only when needed
FROM node:alpine 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
COPY package.json yarn.lock ./
RUN yarn install --frozen-lockfile


# Rebuild the source code only when needed
FROM node:alpine AS builder
WORKDIR /app
COPY . .
COPY --from=deps /app/node_modules ./node_modules
ARG NODE_ENV=devolpement
RUN echo ${NODE_ENV}
RUN NODE_ENV=${NODE_ENV} yarn build

# Production image, copy all the files and run next
FROM node:alpine AS runner
WORKDIR /app
RUN addgroup -g 1001 -S nodejs
RUN adduser -S nextjs -u 1001

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

USER nextjs

# Expose
EXPOSE 3000

# 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.
ENV NEXT_TELEMETRY_DISABLED 1
CMD ["yarn", "start"]

[tamvm]

Hi,
I got this error in yarn build

#11 57.83 FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
#11 58.04 error Command failed with signal "SIGABRT".

Anyone has an experience with that?

Thank you,

[rtrembecky]

happened to me once on CI. I googled a bit and fixed it by using "NODE_OPTIONS=\"--max_old_space_size=8192\" next build" as the "build" script in package.json

[nazywamsiepawel]

If this is happening within a Docker build you might also want to try to bump up the memory

docker build . -m 8g

[nemanjam]

Can someone explain this? This shuts down container if website isn't up, why is that useful?

HEALTHCHECK --interval=5s --timeout=5s --retries=3 \
    CMD curl --fail http://localhost:3000 || exit 1

[m1stermanager]

@nemanjam I imagine if the process has died, its better to kill the container so that the outage can be detected at the container level and a new one will be provisioned by whatever provider you use.

you can always configure your own healthcheck and hook into whatever cloud service, but this is actually pretty sufficient for just about any provider/use-case

quick edit:
this feels like something that would work well for kubernetes as well.... feels like a really nice cross platform solution.... almost every container service out there will allow you to set a restart policy.... might as well take the container down if it detects an issue and let the restart policy take over.

[nemanjam]

Thank you.

[joacim88]

We are also looking in to this and having the same problem. It would be great to hear from the devs on this?

Maybe having the option to tell nextjs on startup to do the static build instead of the buildstep to pre-render static pages at runtime?

Something like

next build --skip-build-ssg
next run --build-ssg

Wouldn't something like this solve this issue? This probably introduce some other issues I haven't thought of but it would be interesting to hear some ideas

[tabuchid]

@ijjk @timneutkens bump

[dm17]

How does vercel work on the backend? They must have worked around this or do they not use containers or images? Perhaps nextjs was just designed with vercel in mind and using the image/container paradigm should not be considered supported.

[ItsDaveB]

Agreed @dm17. Hopefully this isn't the case, in the 12.1 release notes they have listed docker examples and recommendations including the standalone support feature which worked great when I tested it to reduce the Docker image sizes.

[joacim88]

Long time since I've been here. I wrote a piece on how our solution ended up here if you're interested
#39899

[mp205]

Bumping this

[benmarte]

I ran into this issue and got it working with Docker while still respecting the 12 Factor App Rules, the TL;DR is you need to modify your next.js.config and your _app.js files with the following:

next.js.config

/** @type {import('next').NextConfig} */
const nextConfig = {
  publicRuntimeConfig: {
    // remove private variables from processEnv
    processEnv: Object.fromEntries(
      Object.entries(process.env).filter(([key]) =>
        key.includes('NEXT_PUBLIC_')
      )
    ),
  },
}

module.exports = nextConfig

_app.js

import App from 'next/app'

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />
}

// Only uncomment this method if you have blocking data requirements for
// every single page in your application. This disables the ability to
// perform automatic static optimization, causing every page in your app to
// be server-side rendered.

MyApp.getInitialProps = async (appContext) => {
  // calls page's `getInitialProps` and fills `appProps.pageProps`
  const appProps = await App.getInitialProps(appContext);
  return { ...appProps }
}

export default MyApp

To access the environment variables in any page or component simply add this:

import getConfig from 'next/config';

const {
  publicRuntimeConfig: { processEnv },
} = getConfig();

Here’s an example of what component would look like:

import getConfig from 'next/config';

const {
  publicRuntimeConfig: { processEnv },
} = getConfig();

const Header = () => {

  const {NEXT_PUBLIC_MESSAGE} = processEnv;
  
  return (
    <div>
      Hello, {NEXT_PUBLIC_MESSAGE}
    </div>
  )
}

export default Header;

The real issue is the way the Dockerfile starts the app in order to load env vars we need to start it with npm start.

I wrote an article with my findings if you want to get the full details of why and how it works: https://benmarte.com/blog/nextjs-in-docker/

I also made a sample repo which can be used as a template: https://github.com/benmarte/nextjs-docker

I will make a PR this week to the with-docker repo.

[dm17]

I really wonder how folks are using nextjs in production... The same way they're using on their dev machines? Not in docker? Probably... This is still a big design flaw. Maybe it is just time to accept that any non-simple non-dev stacks using nextjs will need docker build time networking. Seems inefficient though - if we have the data in one image that nextjs needs to Create an optimized production build / compile / collect page data, then why can't it just be exported/imported and read as a file?

[tachang]

Thank you for writing this up @benmarte.

In your blog post you mention having to call getServerSideProps if you need the props. I assume this causes the page to get rendered server side? I thought everything would be CDN cacheable.

[dm17]

The wait has been long enough... Maybe there's another work around. Perhaps a proxy can allow nextjs to build without build time networking by making the other containers appear as if they're online instead of in a local docker network. I guess that would be enabled/disabled just for the build so it doesn't become a network security liability.

[benmarte]

@tachang Sorry for the late response. Anyways I believe this won't be an issue since all NEXT_PUBLIC env vars are stored in the __NEXT_DATA__ script object. You can test this by just inspecting the page and look for the __NEXT_DATA__ object and see all your NEXT_PUBLIC env vars.

Let me know if that's not the case because I could be wrong and my use case is to run nextjs in kubernetes with runtime env vars.

[indralukmana]

Thank you for the write-up @benmarte your case appears to be similar with the case I have in my current team. I usually use Vercel where everything aligned with how Next.js define the proper way of doing environment variables, but my current team was required to do everything on-premise and there are already some definite requirements. So in my case:

• I cannot have environment variables in build time (in docker), and therefore it is not possible to inline the NEXT_PUBLIC_* variables when Next.js build the project for production.
• I have multiple live environment: development, staging, and production. Each of them have different environment variables, and they are available on the server.

Some things that I tried, please excuse my contrived examples, I use other libraries in my actual project (React Query, etc.) but I want to keep it simple here:

A. Create an api endpoint that return the environment variables

Make API route that read environment variables server side src/pages/api/general/env-vars.ts

import { NextApiRequest, NextApiResponse } from "next";

export default async function handler(
  _req: NextApiRequest,
  res: NextApiResponse<{ envVars: { [key: string]: string } }>
) {
  const envVars = Object.keys(process.env)
    .filter((key) => key.startsWith("NEXT_PUBLIC_"))
    .reduce((env, key) => {
      env[key] = process.env[key] ?? "";
      return env;
    }, {} as { [key: string]: string });

  return res.status(200).json({ envVars });
}

Make wrapper component for initializing the environment variables src/components/EnvVars.tsx

import { useEffect, useState } from "react";

export const EnvVars = ({ children }) => {
	// I actually make a global state, but I want to keep it simple here
  const [envVars, setEnvVars] = useState<{ [key: string]: string } | null>(
    null
  );

  useEffect(() => {
    fetch("/api/general/env-vars")
      .then((res) => res.json())
      .then((data) => setEnvVars(data.envVars));
  }, []);

  if (envVars === null) {
    return "Loading...";
  }

  return <>{children}</>;
};

src/pages/_app.tsx

import { EnvVars } from "../components/EnvVars";

function MyApp({
  Component,
  pageProps: { session, ...pageProps },
}: AppPropsWithLayout<PageProps>) {
  return (
    <>
      <EnvVars>{<Component {...pageProps} />}</EnvVars>
    </>
  );
}

B. Inline script in _document.tsx that set the environment variables server side

Read the script server side and inline it in src/pages/_document.tsx

import NextDocument, { Head, Html, Main, NextScript } from "next/document";

const nextPublicENV = Object.keys(process.env)
  .filter((key) => key.startsWith("NEXT_PUBLIC_"))
  .reduce((env, key) => {
    env[key] = process.env[key] ?? "";
    return env;
  }, {} as { [key: string]: string });

export default class Document extends NextDocument {
  render() {
    return (
      <Html lang="en">
        <Head />
        <script
          dangerouslySetInnerHTML={{
            __html: `
                        console.table(${JSON.stringify(nextPublicENV)});
		        window.process = window.process || {};
		        window.process.env = window.process.env || {};
			Object.assign(window.process.env, ${JSON.stringify(nextPublicENV)});
                  `,
          }}
        ></script>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

Turn off client-side rendering so the _document can read the environment variables on the server-side

src/pages/_app.tsx

MyApp.getInitialProps = async (context: AppContext) => {
  if (context?.ctx?.res) {
    context.ctx.res?.setHeader(
      "Cache-Control",
      "public, s-maxage=10, stale-while-revalidate=59"
    );
  }

  const ctx = await App.getInitialProps(context);

  return {
    ...ctx,
  };
};

---

I think the second approach is better. It is simpler, and it is not making an extra request to the server. And it is how I ended up doing it. But I am still curious if there is a better way to do it. Whether it is approach A or B, I think it is still a hack. Your post https://benmarte.com/blog/nextjs-in-docker/ give me some ideas on how to do it properly (in less hacky way).

With the advent of app dir hopefully I can change these hacks to something better, as they will be server side rendered by default, but then I will also have other challenges in client only libraries like Chakra UI 😅

[craigwardman]

I'm just looking into the options on this one for myself for a deployment I'm planning in the near future.

It seems to me that trying to do the "next build" as part of the Dockerfile is the wrong thing to do (unless you're trying to do next export); this introduces all the issues with inlined environment variables and SSG content being baked into a container image making them impossible to move around environments. Presumably this also means whenever the content team make changes in the CMS you need to rebuild the containers? 😯

My original thoughts on this, before I found this thread, were simply to create a container image that was based on node, copy in package.json and the source code files and pre-install the node modules by doing npm i and that's it. The container entrypoint would be to run "next build" then "next start".

This artifact is then a deployable version of the code that can be repeatably deployed/tested anywhere and all the environment variables can be managed by the release process (e.g. Helm or whatever).

The obvious foreseeable drawback to this approach would be a longer delay between starting the container and container being ready to serve traffic, (i.e. while it builds the code and renders any SSG content) but I can't see that being an unmanageable amount of time.

Is there anything else fundamental that I'm missing here?

[dm17]

As someone dealing with nextjs in production and not dev: this thread destroys all faith in nextjs.
@craigwardman You think it is intelligent to ignore the terms "build time" and "run time" in order to overlook an engineering issue where you have to cause build time to happen at run time - not to mention make it harder for build time to happen before run time (at build time) because networking is required between the components being built?

[craigwardman]

@dm im not ignoring the terms, simply moving the server on which the build occurs. (from the build server to the hosting server).

Whilst this isn't ideal, it's not "runtime" for a container until it reports that it's ready and healthy. Pre generation of content (which is basically all next build does, aside from syntax checking which can be done independently) isn't something you'd expect to run on a build server anyway. It's essentially just pre loading a cache on the server.

The 2 biggest issues without doing this is its not just networking between components, if the build is happening in github or azure devops and the cms server and database are on a private network, it's a physical networking issue. The other thing is it destroys any hope of putting container images on docker hub for public consumption as they can't be configured by the end user.

[dm17]

So this solution requries something more advanced like k3s or k8s. Those using docker-compose to replace/upgrade running containers will have to experience downtime - unless there is some way I don't see that allows one to replace containers with new corresponding ones (according to a docker-compose.yml) without downtime (when it is "ready and healthy" as you say).

[craigwardman]

@dm17 correct, my assertions have all been based on using K8S to manage the container instance(s). I'm not sure of the implications of using a different container manager, so maybe this problem is exacerbated with Docker Compose.

With K8S at least, you'd have a delay starting the very first container and then potentially issues if you get a spike in traffic and have to wait for another instance to start (which you could mitigate by scaling up sooner rather than later). For scaling purposes there might actually be some merit in having a volume mounted "dist" folder so the first container creates that and all other instances simply read, but I'm not sure if next.js would support that kind of file sharing.

For upgrades of course there'd be no downtime as the old instance would only be replaced when the new instance is ready.

[dm17]

Well k8s would replace them as they came online & healthy, as you said. So there shouldn't be a need for delay if it is designed correctly with nextjs - because the newly built front end should be able to talk to an older back end (since new backend-etc- would be up first). At least should be OK during the minute(s) that the new front end builds via nextjs.

So I just need to figure out a coherent "replace the new container with the old" method (networking-wise) in docker-compose.

[dm17]

NextJS authors: dynamic (re)building of pages can happen at run time. The initial build of the site should happen at build time. No need to rebuild the entire site at run time - just changes that are made. No need to build the entire site at run time. If you want an initial build, then that would happen at build time. Any other cases?
If any of this does not make sense, then please check out the above threads.

[craigwardman]

I've done some further investigation since last time I responded to this thread, so I now have a better understanding of the problem and of the pros and cons of the various solutions.

Ultimately the best solution is going to be Vercel adding "runtime SSG" as a feature of Next.js - until then I've put together a blog post of my findings that others might find helpful:

http://www.craigwardman.com/Blogging/BlogEntry/ssg-isr-and-environment-variables-in-next-js-and-docker

[dgbau]

I've been using a multi-stage build similar to many of the ones shown in this thread, but I can't manage to find a way for it to only run the run the builder and runner when source code changes. It always just runs with the caches images, and I'm forced to purge all the intermediary layers to get it to build changed source code, which then forces it to download all dependencies again and negates any benefit of a multi-stage build. Can anyone see what is incorrect about this config? Many thanks!

FROM node:18-alpine AS deps
LABEL stage=deps
RUN apk add --no-cache libc6-compat
RUN apk update
WORKDIR /app
COPY package.json ./
RUN npm install

FROM node:18-alpine AS builder
LABEL stage=builder
RUN apk add --no-cache libc6-compat
RUN apk update

WORKDIR /app
COPY . .
COPY --from=deps /app/node_modules ./node_modules
RUN mkdir -p node_modules/.cache && chmod -R 777 node_modules/.cache
RUN npx nx build arch-epec

FROM node:18-alpine AS runner
LABEL stage=runner
WORKDIR /app
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
USER nextjs
COPY --from=builder /app/dist/apps/arch-epec/next.config.js .
COPY --from=builder /app/dist/apps/arch-epec/package.json .
COPY --from=builder /app/certs/jaas.key ./certs/jaas.key
COPY --from=builder /app/dist/apps/arch-epec/with-nx.js .
COPY --from=builder /app/dist/apps/arch-epec/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/dist/apps/arch-epec/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
COPY ./.env ./.env

EXPOSE 3000
ENV PORT 3000
ENV NEXT_TELEMETRY_DISABLED 1
CMD ["npm", "run", "start:next"]

[eli-front]

https://medium.com/@elifront/best-next-js-docker-compose-hot-reload-production-ready-docker-setup-28a9125ba1dc

[deadcoder0904]

Checkout my solution as it uses Docker best practices for security. I don't think even Vercel's solution does that fully. And it creates another user when you can use the user created by Node package itself.

[dangduytung]

For docker image can run multiple environments like staging, production, develop... Read here:
https://stackoverflow.com/questions/77329575/different-env-variables-for-the-same-nextjs-docker-image/78112804#78112804

[dukemai]

nice, thanks for sharing the whole implementation. We did similar "hack" with a script to replace configs in our projects. The downside of this approach that you need to build your apps with special configurations so when removing it will not be matched with other codes.

[dangduytung]

Yes, right. Need to verify and test again after the build first and run with other configurations. For safety just use in configure like API_ENDPOINT because has the prefix "http://" or "https://" will replace the string ok.

[TomLaVachette]

You are creating a CI/CD pipeline and want to build NextJS. However, NextJS needs another service (database, Redis, etc.) to build, and you don't want to expose your services to your host machine?

Read this.

1. In the docker-compose.yaml, add your services to an external Docker network

services:
    pgadmin:
        container_name: my-database
        image: postgres
        networks:
            - my-net

networks:
    my-net:
        name: 'my-super-net'
        external: true

2. In the docker-compose.yaml, use the network: host to build your NextJS (it won't be exposed to your host machine, keep reading)

webserver:
    build:
        context: .
        dockerfile: Dockerfile
        network: host

3. In the pipeline, add these steps.

# Create the Docker network if not already present
docker network create my-super-net || true

# Create the Docker builder
docker buildx create --name my-builder --use --driver-opt network=my-super-net --buildkitd-flags '--allow-insecure-entitlement network.host'
# `--use` to use this builder by default
# `--driver-opt network=my-super-net` to add the Docker builder to the Docker network so it can access our services
# `--buildkitd-flags '--allow-insecure-entitlement network.host'` to allow building with --network=host

# Bootstrap the Docker builder to get it ready for use
docker buildx inspect my-builder --bootstrap

# Start the services manually
docker compose -f docker-compose.yaml up -d database
docker compose -f docker-compose.yaml up -d redis

# Build as usual
docker compose -f docker-compose.yaml build
# The build will use the `network: host`, which is not your host machine's network, but the network of your previously created builder. Your services are not exposed to your host machine.

[pilot22]

Original from @dgbau (#16995 (comment))

I've been using a multi-stage build similar to many of the ones shown in this thread, but I can't manage to find a way for it to only run the run the builder and runner when source code changes. It always just runs with the caches images, and I'm forced to purge all the intermediary layers to get it to build changed source code, which then forces it to download all dependencies again and negates any benefit of a multi-stage build. Can anyone see what is incorrect about this config? Many thanks!

FROM node:18-alpine AS deps
LABEL stage=deps
RUN apk add --no-cache libc6-compat
RUN apk update
WORKDIR /app
COPY package.json ./
RUN npm install

FROM node:18-alpine AS builder
LABEL stage=builder
RUN apk add --no-cache libc6-compat
RUN apk update

WORKDIR /app
COPY . .
COPY --from=deps /app/node_modules ./node_modules
RUN mkdir -p node_modules/.cache && chmod -R 777 node_modules/.cache
RUN npx nx build arch-epec

FROM node:18-alpine AS runner
LABEL stage=runner
WORKDIR /app
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
USER nextjs
COPY --from=builder /app/dist/apps/arch-epec/next.config.js .
COPY --from=builder /app/dist/apps/arch-epec/package.json .
COPY --from=builder /app/certs/jaas.key ./certs/jaas.key
COPY --from=builder /app/dist/apps/arch-epec/with-nx.js .
COPY --from=builder /app/dist/apps/arch-epec/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/dist/apps/arch-epec/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
COPY ./.env ./.env

EXPOSE 3000
ENV PORT 3000
ENV NEXT_TELEMETRY_DISABLED 1
CMD ["npm", "run", "start:next"]

Currently having the same issue with a similar Dockerfile. This is very annoying while trying to avoid any downtime when deploying new code changes.

[dangduytung]

Your Dockerfile is normal. The cached layer is the default of Docker, when anything changes, that layer will build again.

[Abir-K]

i want to dockerize nextjs full stack project with nginx config. how can i write multistage dockerfile for my project include nginx. Please help.

current nginx config:

server {
listen 80;
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}

}

Current Dockerfile :

FROM node:20-alpine AS builder

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install
COPY . .
RUN npm run build

FROM nginx:alpine

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

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

RUN mkdir .next
RUN chown nextjs:nodejs .next

COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./standalone

COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

COPY ./conf/nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 3000
CMD ["nginx", "-g", "daemon off;"]

[Bosshie96]

@wilsonneto-dev why you don't use docker-compose?

./docker-compose.prod.yml

services:
 next-app-prod:
    container_name:  next-app-prod
    build:
      context: ../
      dockerfile: .docker/Dockerfile.prod
    working_dir: /app
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
  nginx:
    image: nginx:latest
    container_name: nginx
    restart: always
    ports:
      - "80:80"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - next-app-prod

./nginx/nginx.conf

http {
    server {
        listen 80;
        listen [::]:80;
        
        location / {
            proxy_pass http://next-app-prod:3000;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }

        location /static/ {
            alias /usr/share/nginx/html/static/;
            autoindex on;
        }
    }
}

Modify to suit your project !

[dm17]

@Bosshie96 Because nextjs often needs to fetch artifacts during build time from another container and docker compose no longer has build time networking that will work for this. Supposedly one can go outside of compose for this functionality now:
docker/buildx#175