DEV Community

Gharelu Remedy
Gharelu Remedy

Posted on Edited on

How I Deploy Next.js with Docker, Caddy HTTPS and GitHub Actions

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"]
Enter fullscreen mode Exit fullscreen mode

Two details matter here:

  • npm ci uses your package-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;
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

  1. Starts the production stack and calls /api/health.
  2. Builds the production image and pushes it to GitHub Container Registry (GHCR).
  3. Copies the deploy files to your server over SSH.
  4. 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
Enter fullscreen mode Exit fullscreen mode

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 .env and never commit it.
  • Do not expose port 3000 without HTTPS.
  • Run npm audit and 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)