Build small, secure Next.js Docker images with the standalone output: a multi-stage Dockerfile, non-root runtime, health checks and a Compose stack with PostgreSQL.

Francis K Njenga
Senior Developer
Containers make deployments reproducible: the same image runs on your laptop, CI, and the VPS. But the naive approach — copy the whole repo, npm install everything, run next start — produces a 1.5 GB image with your source code, dev dependencies and build tools inside. Next.js has a purpose-built answer: output: "standalone", which traces exactly the files the server needs and emits a self-contained server.js. Combined with a multi-stage build, you get images around 150–250 MB that contain no source, no dev deps, and no shell history.
/** @type {import('next').NextConfig} */
const nextConfig = {
output: "standalone",
};
export default nextConfig;This is the same setting our own production site uses.
Four stages, each with one job: deps installs from the lockfile, builder compiles, runner contains only the traced output. Two details people miss:
public/ and .next/static/ are not part of the standalone trace — you must copy them explicitly.nextjs, not root.# ---------- deps ----------
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
# ---------- builder ----------
FROM node:22-alpine AS builder
WORKDIR /app
COPY /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED=1
RUN npm run build
# ---------- runner ----------
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
ENV PORT=3000
ENV HOSTNAME=0.0.0.0
RUN addgroup -S nodejs -g 1001 \
&& adduser -S nextjs -u 1001 -G nodejs
COPY /app/public ./public
COPY /app/.next/standalone ./
COPY /app/.next/static ./.next/static
USER nextjs
EXPOSE 3000
CMD ["node", "server.js"]node:22-alpine keeps the base tiny; libc compatibility is fine for Next.js standalone.
node_modules
.next
.git
.env*
upload
*.md
docker-compose.yml
Dockerfile
.dockerignore
npm-debug.log*
coverage
.qodernode_modules and .next must be rebuilt inside the image, never copied from the host.
A TCP port being open does not mean the app works. Add a lightweight route that verifies the process is serving — and, if you want deeper checks, that the database answers. Orchestrators (Compose, Kubernetes, Coolify, CapRover) use it to restart or hold traffic from broken containers.
export const dynamic = "force-dynamic";
export async function GET() {
return Response.json({
status: "ok",
uptime: process.uptime(),
timestamp: new Date().toISOString(),
});
}Point your orchestrator's health check at /api/health.
App + PostgreSQL + automatic restarts, with the database on an internal network and a named volume so data survives rebuilds. Note the app never publishes the DB port to the host — only Nginx (or your proxy) faces the internet.
services:
app:
build: .
restart: unless-stopped
ports:
- "127.0.0.1:3000:3000" # proxy-facing only
environment:
DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/appdb
AUTH_SECRET: ${AUTH_SECRET}
depends_on:
db:
condition: service_healthy
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/api/health"]
interval: 30s
timeout: 5s
retries: 3
db:
image: postgres:16-alpine
restart: unless-stopped
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_DB: appdb
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app"]
interval: 10s
timeout: 5s
retries: 5
volumes:
pgdata:Secrets come from .env on the host — never baked into the image.
docker compose pull && docker compose up -d on deploy.next/image works in standalone, but add sharp to dependencies for production-grade speed.Prefer bare metal? Containers are a means, not a religion — we also deploy Next.js directly on VPSes with PM2 and Nginx (see our VPS hosting guide). The right tool depends on your team and traffic.
Need the whole pipeline — containerization, registry, zero-downtime deploys — handled for you? That's our DevOps service.

Senior Developer
Francis Njenga is an experienced Lead Developer specializing in React, Next.js, and modern JavaScript frameworks, with a strong background in web development.