Every new Next.js project, I ended up rebuilding the same Docker setup: a dev container with hot reload, a lean production image, CI that builds it, and a way to deploy with HTTPS. So I put it together once and tested it. Here is how the pieces fit, and what I would check before using it on a real server.
1. One Dockerfile, three targets
A multi-stage Dockerfile keeps dev and production separate, so the production image stays small.
# syntax=docker/dockerfile:1
ARG NODE_VERSION=22
FROM node:${NODE_VERSION}-alpine AS base
WORKDIR /app
RUN apk add --no-cache libc6-compat
FROM base AS deps
COPY package.json package-lock.json* ./
RUN if [ -f package-lock.json ]; then npm ci; else npm install; fi
# used by the dev compose file
FROM base AS dev
ENV NODE_ENV=development
COPY --from=deps /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["npm", "run", "dev"]
FROM base AS builder
ENV NEXT_TELEMETRY_DISABLED=1
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build
# used by production
FROM base AS prod
ENV NODE_ENV=production NEXT_TELEMETRY_DISABLED=1 PORT=3000 HOSTNAME=0.0.0.0
RUN addgroup -S nodejs -g 1001 && adduser -S nextjs -u 1001 -G nodejs
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
USER nextjs
EXPOSE 3000
CMD ["node", "server.js"]
Two details matter here:
-
npm ciuses yourpackage-lock.json, so builds are reproducible. Commit the lock file. - The production stage copies only the standalone output and runs as a non-root user.
For the standalone output, enable it in next.config.mjs:
const nextConfig = {
output: "standalone",
};
export default nextConfig;
2. Dev stack with hot reload
The dev compose file mounts your source into the container and waits for the database to be healthy before the app starts.
services:
app:
build:
context: .
target: dev
ports:
- "3000:3000"
volumes:
- .:/app
- /app/node_modules # keep the container's node_modules
- /app/.next
depends_on:
postgres:
condition: service_healthy
On Windows and macOS, bind mounts do not always trigger file watching. Enabling polling in the Next.js webpack config for dev fixes that.
3. Production behind Caddy
On the server I run the prebuilt image behind Caddy. Caddy gets and renews a free HTTPS certificate on its own, so the config is tiny:
{$DOMAIN} {
encode gzip zstd
reverse_proxy app:3000
}
The server compose file starts the app, Postgres, Redis and Caddy together. Caddy only starts once the app reports healthy:
caddy:
image: caddy:2
ports:
- "80:80"
- "443:443"
environment:
DOMAIN: ${DOMAIN:?set DOMAIN in .env}
depends_on:
app:
condition: service_healthy
For this to work, the DNS record for your domain must point to the server, and ports 80 and 443 must be open.
4. GitHub Actions: test, build, push, deploy
The workflow does four things on every push to main:
- Starts the production stack and calls
/api/health. - Builds the production image and pushes it to GitHub Container Registry (GHCR).
- Copies the deploy files to your server over SSH.
- Runs the deploy script.
If the SSH secrets are not set yet, the deploy job skips itself instead of failing, so you still get the test and build results.
5. A deploy script that rolls back
The server script pulls the new image, restarts the stack and waits until it is healthy. If it is not, it restores the previous image:
if $COMPOSE up -d --remove-orphans --wait --wait-timeout 180; then
echo "Deployed $IMAGE"
else
echo "Deploy FAILED for $IMAGE" >&2
if [ -n "$PREV" ] && [ "$PREV" != "$IMAGE" ]; then
echo "Rolling back to $PREV" >&2
set_image "$PREV"
$COMPOSE up -d --remove-orphans --wait --wait-timeout 180 || true
fi
exit 1
fi
It stores the current image name in .env, which is how it knows what to go back to.
What I tested, and what I did not
I want to be upfront about this:
- Tested: the dev and production stacks on Docker Desktop (Windows 11, WSL2), the server stack with Caddy locally, and the GitHub Actions test and image build.
- Not tested: a deploy to a real VPS over SSH with a public domain. If you try it, I would like to hear what breaks.
Before you use this in production
- Set strong passwords in
.envand never commit it. - Do not expose port 3000 without HTTPS.
- Run
npm auditand decide how to handle the findings for your project. - Test the rollback on a staging server before you rely on it.
The kit
I packaged all of this as a starter kit with a Postgres version and a MySQL version (the MySQL one also adds a BullMQ worker, a scheduler, Mailpit and phpMyAdmin): Next.js Docker Starter Kit
What would you add to a setup like this? I would like to hear what your deploys always need.

Top comments (0)