Docker and Self-Hosting Next.js

Vercel is the path of least resistance, but many teams run Next.js on their own infrastructure: a VPS, Kubernetes, a company cloud account. Next.js supports this fully through next start and the standalone output mode. After this lesson you will be able to build a small production Docker image, run it with a database via Compose, and handle the details that differ from a managed platform: environment variables, image optimisation and the ISR cache.

Standalone Output

Set output: "standalone" in next.config.ts. During next build, Next.js traces every file the server actually imports and copies them into .next/standalone, including a minimal server.js and only the required parts of node_modules. The result is typically a fraction of the size of a full node_modules folder. Two folders are not included and must be copied alongside: public/ and .next/static/.

The Dockerfile

The sample at the top of this lesson uses three stages:

deps installs dependencies with npm ci so the layer is cached until the lockfile changes.
builder copies the source and runs next build.
runner starts from a clean image, copies only the standalone output, and runs as a non-root user.

Add a .dockerignore so the build context stays small:

text

node_modules
.next
.git
.env*.local

Build and run:

bash

docker build -t my-next-app .
docker run -p 3000:3000 --env-file .env.production my-next-app

HOSTNAME=0.0.0.0 is required so the server listens on all interfaces inside the container rather than only on localhost.

Environment Variables in Containers

Server-side variables are read when the container starts, so --env-file or the orchestrator's secrets work as expected. NEXT_PUBLIC_ variables are different: they are inlined during npm run build, which happens inside the image. Either pass them as build arguments (ARG NEXT_PUBLIC_SITE_URL before RUN npm run build) or avoid them for values that change between environments and read them on the server instead.

Running With a Database

A Compose file wires the app to PostgreSQL for staging or small deployments:

yaml

# compose.yaml
services:
  web:
    build: .
    ports: ["3000:3000"]
    environment:
      DATABASE_URL: postgresql://app:secret@db:5432/app
    depends_on: [db]
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes: ["pgdata:/var/lib/postgresql/data"]
volumes:
  pgdata:

Run migrations as a separate one-off command (docker compose run web npx prisma migrate deploy) rather than at container start, so several replicas never race to migrate.

Details That Differ From Managed Hosting

| Concern | What to do | |---|---| | Image optimisation | sharp is bundled with Next.js; nothing extra is needed. For very high traffic, set images.loader to a CDN. | | ISR and Data Cache with several replicas | Each instance has its own file cache by default; configure cacheHandler in next.config.ts with a shared store such as Redis, and set cacheMaxMemorySize: 0. | | TLS and compression | Terminate TLS at a reverse proxy (nginx, Caddy, a load balancer) in front of port 3000. | | Process management without Docker | Run next start under PM2 or a systemd unit so it restarts on failure. | | Health checks | Add app/api/health/route.ts returning 200 and point the orchestrator at it. |

Common mistakes

Copying the whole .next folder instead of .next/standalone, which defeats the size savings.
Forgetting .next/static and public, resulting in a running server with missing CSS and images.
Running as root inside the container; create a user as the sample does.

Key Takeaways

output: "standalone" produces a minimal server folder; copy public and .next/static next to it.
Use a multi-stage Dockerfile with a non-root runner and HOSTNAME=0.0.0.0.
Server variables are read at start; NEXT_PUBLIC_ values must be present at build time.
Run migrations as a one-off command, not at container start.
With multiple replicas, configure a shared cacheHandler and put a reverse proxy in front.

Next lesson: Migrating from the Pages Router to the App Router — move an existing project route by route without a rewrite.