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.

