How to Dockerize Next.js: A Working Guide

Most people who dockerize Next.js for the first time write the obvious Dockerfile. It copies the whole project into a Node image, runs npm install, then npm run build. Everything stays in the final layer. That means dev dependencies, the package cache, your test files, and a node_modules tree that the running app mostly never reads.

Next.js has a build mode for this. During next build it traces which files each page can actually load, using static analysis of import, require and fs calls. Set output to standalone and it copies just those files, including the few node_modules it needs, into .next/standalone. That folder can run on its own, without installing anything.

You also get a small server.js that replaces next start. The docs say it can be deployed "on its own without installing node_modules", which is the whole point. It is also what Docker recommends: their own Next.js guide builds a sample this way and shows the result at 130MB.

Before you dockerize Next.js, three small decisions save you an afternoon. First, a base image. Use a Node line that is still supported. Pin the major version, not "latest", so a rebuild next spring does not change your runtime by surprise.

Node 24 is the sensible pick today. Node 20 reached end of life in April, so if your old Dockerfile still says node:20, that is the first thing to change.

Second, a .dockerignore file. Without it, COPY . . drags your local node_modules, .git and any old .next folder into the build. Docker's guide excludes node_modules, .next, out, .env files and .git. Do the same.

Third, know which variables are baked in. Only names starting with NEXT_PUBLIC_ are inlined into the JavaScript at build time. Everything else is read when the server runs. We come back to that below, because it decides whether one image can serve every environment.

1. 1Turn on standalone outputIn next.config.ts set output to the string standalone. Nothing else in the config needs to change. In a monorepo, also set outputFileTracingRoot to the repository root, or files outside the app folder will not be traced and the container will fail on a missing import.
2. 2Add a .dockerignoreList node_modules, .next, out, .git and .env followed by a star. It keeps the build context small and stops a stale local build leaking into the image.
3. 3Write the DockerfileThree stages: install from the lockfile, build, then copy only the standalone output into a clean base. The full file is in the next section.
4. 4Build itFrom the project root run docker build with a tag. The first build is slow. Later builds reuse the dependency layer until package-lock.json changes.
5. 5Run it with the port publishedUse docker run with -p 3000:3000. If the page does not load, the cause is nearly always HOSTNAME, covered in the pitfalls.
6. 6Check the image, not just the pageRun docker images to see the size, and docker run with your production variables to confirm the app reads them at runtime rather than from your laptop.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  output: 'standalone',
}

export default nextConfig

node_modules
.next
out
.git
.env*
Dockerfile
npm-debug.log

# syntax=docker/dockerfile:1
FROM node:24-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM node:24-slim AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:24-slim AS runner
WORKDIR /app
ENV NODE_ENV=production PORT=3000 HOSTNAME=0.0.0.0
COPY --from=builder --chown=node:node /app/.next/standalone ./
COPY --from=builder --chown=node:node /app/.next/static ./.next/static
COPY --from=builder --chown=node:node /app/public ./public
USER node
EXPOSE 3000
CMD ["node", "server.js"]

That is the whole file. Read the runner stage closely. It starts from a fresh image, so nothing from deps or builder survives except what the three COPY lines bring across. The build stage can be as heavy as it likes. Only the runner ships.

The standalone server does not copy public or .next/static by default. The Next.js docs say these "should ideally be handled by a CDN instead". If you have no CDN in front, copy them in as above, or the page loads with no styles and no images.

Almost always the server is listening on the wrong interface. By default it binds to localhost, which inside a container means only the container itself can reach it. Set HOSTNAME to 0.0.0.0 and docker run -p works. The Next.js docs show the same form: PORT=8080 HOSTNAME=0.0.0.0 node server.js.

• Page loads with no CSS or images: public or .next/static was not copied into the runner stage.
• Container exits at once with "Cannot find module": in a monorepo, outputFileTracingRoot is not set, or a native package such as sharp needs an outputFileTracingIncludes entry.
• Permission errors writing the cache: the files were copied as root and the app runs as the node user. The --chown flags above fix it.
• A NEXT_PUBLIC_ value is stale: it was inlined at build time. Changing it means rebuilding the image, not restarting the container.
• Image is still huge: the runner stage starts from the builder stage instead of a fresh FROM line.

That sentence is the reason to keep secrets and URLs out of NEXT_PUBLIC_ names. Read them on the server during a dynamic render and one image can move from staging to production untouched.

Image size sounds abstract until you multiply it. This is a worked example with assumed inputs, so change the numbers to match yours. Take the 130MB sample image from Docker's guide. Say you ship 20 times a month to 3 servers, and every server pulls the whole image each time.

Real pulls reuse unchanged layers, so the true figure is lower for both. The gap is what matters. A smaller final image also starts faster on a new machine, which shows up when a container restarts at a bad moment.

On a single container, every Next.js feature works, ISR included. The trouble starts with a second copy. Each container keeps its own cache on local disk, so a revalidation on one does not reach the other. The docs also ask for the same build to boot every container, and one shared NEXT_SERVER_ACTIONS_ENCRYPTION_KEY, or Server Actions fail with "Failed to find Server Action" errors.

The caching side is covered in Incremental Static Regeneration when you self-host. If you are choosing between a container and a plain Node server, the comparison of every way to deploy a Next.js app sets them side by side.

Once you dockerize Next.js, the image runs on a VPS with Docker, on Kubernetes, on Cloud Run, or on a platform that builds it for you. Docker hosting has its own trade-offs, set out in Docker hosting explained. Helm7 builds your repository in a container, starts the new version, waits until it answers, moves traffic across and gives the old one 30 seconds to finish. Running the Dockerfile above locally is still a good way to check that a deploy will behave.

If you would rather not maintain a Dockerfile at all, the self-hosting guide covers the plain Node route.