DEV Community: Mahmoud Mokaddem

docker-compose for Next.js + NestJS local dev

Mahmoud Mokaddem — Sat, 09 May 2026 09:21:00 +0000

Most docker-compose tutorials for Next.js stop at "here's a service block, here's how to mount your code." Then you start it on macOS, type a character in your editor, and hot reload doesn't fire. You add a Postgres service, your NestJS API tries to connect before the database is ready, and the container crashes on first boot. You stop the stack, your node_modules is mysteriously empty on the host. None of these are mysteries — they're all known issues with known fixes. Here's the docker-compose.dev.yml I actually use.

This compose file is part of a production-grade Next.js + NestJS starter I'm building. Free for email subscribers — subscribe at mahmoud-mokaddem.com. Follow-up to Dockerizing Next.js for production.

The compose file, up front

If you're in a hurry, copy this and skip to Common gotchas. The rest of the post explains every line.

services:
  web:
    build:
      context: ./web
      dockerfile: Dockerfile.dev
    ports: ['3000:3000']
    volumes:
      - ./web:/app           # bind-mount source
      - /app/node_modules    # anonymous vol shadows host node_modules
      - /app/.next           # anonymous vol preserves build cache
    environment:
      WATCHPACK_POLLING: 'true'
      NEXT_PUBLIC_API_URL: http://localhost:4000
    depends_on:
      api:
        condition: service_started

  api:
    build:
      context: ./api
      dockerfile: Dockerfile.dev
    ports: ['4000:4000']
    volumes:
      - ./api:/app
      - /app/node_modules
    environment:
      DATABASE_URL: postgres://dev:dev@db:5432/app
      NODE_ENV: development
    depends_on:
      db:
        condition: service_healthy
    command: npm run start:dev

  db:
    image: postgres:16-alpine
    ports: ['5432:5432']
    environment:
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev
      POSTGRES_DB: app
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U dev -d app']
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  db_data:

Three services: web (Next.js), api (NestJS), db (Postgres). Each decision in this file exists to work around a specific failure mode.

Why a separate `.dev.yml`

The production Dockerfile from the previous post builds a multi-stage image: it installs deps, compiles the app, then copies only the slim standalone output into a clean final image. No source code mounted, no dev dependencies, no hot reload. That's exactly correct for production and completely wrong for local work.

Local dev needs almost the opposite: source code mounted so changes take effect without a rebuild, dev dependencies installed, next dev and nest start --watch running, and fast incremental compilation. A Dockerfile.dev handles this — it installs deps and starts the dev server; it never runs npm run build.

The two-file approach gives you a clean mental model: docker-compose.yml for production-like local runs (useful for final QA and catching prod-only bugs), docker-compose.dev.yml for daily development. Run the dev stack with:

docker compose -f docker-compose.dev.yml up

Worth aliasing that flag away — I'll cover it in the workflow section.

Service: `web` (Next.js)

The dev Dockerfile for Next.js is intentionally minimal. It installs dependencies and starts the dev server; nothing more.

# web/Dockerfile.dev
FROM node:20-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
EXPOSE 3000
CMD ["npm", "run", "dev"]

No build stage, no standalone output, no multi-stage. The source arrives via the bind mount at runtime, not at build time.

The volume pattern that keeps hot reload working

This is the most important thing to get right in the whole file. The volume block for web looks like this:

volumes:
  - ./web:/app           # bind-mount source
  - /app/node_modules    # anonymous vol shadows host node_modules
  - /app/.next           # anonymous vol preserves build cache

The first line is a bind mount: your ./web directory on the host is mounted into /app inside the container. Every file you edit on the host is immediately visible inside the container — that's how hot reload works.

The problem: the bind mount overwrites everything at /app, including node_modules and .next. Your host's node_modules was either compiled on macOS (wrong architecture for Linux), or it doesn't exist at all if you didn't run npm install locally. Either way, the container's freshly-installed node_modules gets stomped.

The fix is two anonymous volumes. An anonymous volume at /app/node_modules tells Docker to manage that path separately — it won't be overwritten by the bind mount above it. The container's node_modules, installed during docker compose build and stored in a Docker-managed volume, stays intact. Same logic for /app/.next: preserving the Next.js build cache across restarts.

Without these two lines, you get a "cannot find module" error every time.

WATCHPACK_POLLING

WATCHPACK_POLLING: 'true' is required on macOS and Windows because Docker Desktop's filesystem bridge doesn't reliably deliver native file-system events to the container. Next.js uses Watchpack for its file watcher; polling mode makes it check for changes on a timer instead of waiting for an event that may never arrive.

Linux users running Docker Engine natively can usually leave this off — events propagate without polling. The trade-off is CPU: polling mode runs a constant low-level scan instead of sleeping between changes. Enable it when you need it; remove it when you're on Linux.

NEXT_PUBLIC_API_URL

NEXT_PUBLIC_API_URL: http://localhost:4000 — this one looks wrong at first glance. The api service is reachable at http://api:4000 inside the Docker network. So why localhost?

Because NEXT_PUBLIC_* variables are baked into the client-side JavaScript bundle, and that bundle runs in your browser — not inside Docker. Your browser doesn't know what api means as a hostname; it only sees localhost. So for any variable that the browser-side code uses, you need the host-mapped port, not the docker-network hostname.

Server-side Next.js code (API routes, getServerSideProps, Server Components) runs inside the container and can use docker hostnames. So if you have a purely server-side database URL, db:5432 is fine. The rule: if it touches the browser, use the host port; if it's server-only, use the docker-network hostname.

depends_on

depends_on: api: condition: service_started ensures the api container has at least started before Next.js tries to boot. This is a loose dependency — "started" means the container process launched, not that the API is ready to accept requests. For local dev, that's usually fine; Next.js doesn't make API calls at startup.

Service: `api` (NestJS)

The NestJS dev Dockerfile follows the same pattern:

# api/Dockerfile.dev
FROM node:20-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
EXPOSE 4000
CMD ["npm", "run", "start:dev"]

Where start:dev in your package.json runs nest start --watch. NestJS recompiles TypeScript on each save and restarts the process — the same hot-reload loop as next dev, just with TypeScript involved.

The volumes are identical to the web service: bind-mount source, anonymous volume for node_modules. Same reasoning applies.

DATABASE_URL and docker-network hostnames

DATABASE_URL: postgres://dev:dev@db:5432/app — the hostname here is db, the docker-compose service name. Inside the Docker network, services find each other by service name. This is server-side code only, so the docker hostname works fine.

The mistake I see most often: using localhost here. Inside the api container, localhost is the container itself, not the host machine and not the db container. The connection will be refused. Use the service name.

depends_on with service_healthy

The api service uses a stricter dependency than web:

depends_on:
  db:
    condition: service_healthy

service_healthy waits for the db service's healthcheck to pass before starting the api container. This is what prevents the connection-refused race condition.

Without it: Docker starts api shortly after db. Postgres takes 3–5 seconds to initialize on first boot (creating the user, setting up the database). Your API tries to connect during those seconds, gets refused, and crashes. If it doesn't auto-restart, you have to docker compose restart api manually every time you wipe the database volume.

With service_healthy: Docker holds the api container until Postgres says it's ready. The healthcheck (defined on the db service) handles the timing.

Note that command: npm run start:dev is set at the compose level, not in the Dockerfile. This is intentional — it lets you override the default command without rebuilding the image. If you want to run a migration before the dev server starts, you can override command here without touching the Dockerfile.

Service: `db` (Postgres)

postgres:16-alpine — small image, fast pull, stable. Alpine here is straightforward: Postgres ships its own binaries without the glibc complications that affect some Node packages.

The three environment variables (POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB) auto-create the user and database on first container start. dev/dev/app is fine for local. Don't waste time on secure local credentials — that's what environment files for production are for.

The named volume db_data persists your data across docker compose down. When you want a clean slate — after a schema change you can't migrate forward from, or at the start of a testing session — use docker compose -f docker-compose.dev.yml down -v. The -v flag removes named volumes too. Without it, your data survives restarts.

ports: ['5432:5432'] exposes Postgres to your host machine. This is optional from the stack's perspective — the api container connects over the Docker network and doesn't need the host port. The reason to keep it: direct access from GUI clients like TablePlus, Postico, or DBeaver, and the ability to run psql postgres://dev:dev@localhost:5432/app from your terminal. If you don't use those, remove the line.

The healthcheck

The healthcheck is what makes the whole dependency chain work:

healthcheck:
  test: ['CMD-SHELL', 'pg_isready -U dev -d app']
  interval: 5s
  timeout: 5s
  retries: 5

pg_isready is a Postgres CLI utility that returns exit code 0 when the server is accepting connections on the specified user and database. Docker's healthcheck system runs this command every 5 seconds, marks the container healthy when it passes, and marks it unhealthy after 5 consecutive failures.

The api service's depends_on: db: condition: service_healthy watches this status. As soon as pg_isready returns 0, Docker releases the api container to start. Without this healthcheck, service_healthy would block forever because Docker wouldn't know what "healthy" means for the db service.

Optional services

Add only what your app actually uses. Two common additions:

redis:
  image: redis:7-alpine
  ports: ['6379:6379']

mail:
  image: maildev/maildev
  ports: ['1080:1080', '1025:1025']  # web UI : smtp

Redis is useful for session storage, cache, or BullMQ queues. The redis:7-alpine image is tiny (~30 MB) and needs no configuration for local dev.

Maildev (or Mailhog — either works) catches outgoing emails without delivering them. Your app sends to mail:1025 over the Docker network using SMTP; you read the messages at localhost:1080 in your browser. Invaluable when working on email-sending flows like password reset or welcome sequences — no risk of accidentally spamming real inboxes.

Keep optional services optional. Every container you add to the stack consumes RAM and adds a few seconds to docker compose up. If Redis isn't needed for what you're working on today, comment it out.

Common gotchas

The five bugs that account for most local-dev compose failures with this stack:

1. Hot reload doesn't fire on Mac or Windows. Docker Desktop's filesystem bridge doesn't reliably propagate native file-system events into containers. Fix: set WATCHPACK_POLLING: 'true' in the web service environment. For NestJS with nodemon or Chokidar, add CHOKIDAR_USEPOLLING: 'true' to the api service environment. Polling costs CPU; only enable it where you need it. Linux users with Docker Engine native usually don't need it.

2. node_modules empty or missing on the host after docker compose up. The bind mount ./api:/app overwrites the container's /app with your host directory, including its (empty or macOS-compiled) node_modules. Fix: add the anonymous volume /app/node_modules below the bind mount. The anonymous volume takes precedence for that specific path; the container's installed modules survive. Same fix for /app/.next.

3. "Cannot find module" for native dependencies like bcrypt or sharp. Native packages are compiled for the platform where npm install runs. If you installed them on macOS, the binaries are macOS binaries and won't load in the Linux container. Fix: the anonymous volume pattern above means npm ci runs inside the container at build time, producing Linux binaries. If you still see the error, run docker compose -f docker-compose.dev.yml exec api npm rebuild bcrypt once after first up.

4. API container crashes with "connection refused" on first start. The API started before Postgres finished initializing. Fix: add the healthcheck block to the db service (exactly as shown above) and set depends_on: db: condition: service_healthy on the api service. The API container won't start until pg_isready returns 0. Without this, you'll restart the api container by hand every time you wipe the database volume.

5. Port already in use. Error starting userland proxy: listen tcp4 0.0.0.0:3000: bind: address already in use means something else on your machine owns that port. Fix: lsof -i :3000 to find the offending process. Kill it, or change the host-side port mapping in the compose file ('3001:3000' runs the container on 3000 but exposes it on 3001 on your host). Ports 4000 and 5432 are equally likely culprits.

Each one of these is a 5-minute fix once you know the name. Combined, they're 90% of the local-dev compose failures I've debugged on real teams.

The everyday workflow

How I actually run this stack day to day:

# Start everything in the background
docker compose -f docker-compose.dev.yml up -d

# Tail logs for the service you're working on
docker compose -f docker-compose.dev.yml logs -f api

# Run a one-off command inside a container
docker compose -f docker-compose.dev.yml exec api npm run db:migrate

# After changing package.json — rebuild just that service
docker compose -f docker-compose.dev.yml build api
docker compose -f docker-compose.dev.yml up -d api

# Wipe the database for a clean start
docker compose -f docker-compose.dev.yml down -v

# Connect to Postgres from your host terminal
psql postgres://dev:dev@localhost:5432/app

The -f docker-compose.dev.yml flag is the main ergonomic cost. Worth adding an alias to your shell rc file:

# In ~/.zshrc or ~/.bashrc
alias dc='docker compose -f docker-compose.dev.yml'

Then the commands above become dc up -d, dc logs -f api, dc exec api npm run db:migrate. Saves a significant amount of typing over a few months of daily use.

One more: if you're touching a section of the app that touches the database schema, the workflow is dc down -v (wipe), dc up -d (fresh start), dc exec api npm run db:migrate (apply migrations), then develop. Faster than trying to hand-migrate a dirty local database.

The full setup is in the starter

This compose file is part of a production-grade Next.js + NestJS starter I'm building. The starter ships everything you'd need to go from git clone to a running local stack in under five minutes, then deploy to production without rearchitecting:

The production Dockerfile (from the previous post) and a docker-compose.yml for prod-like local runs
docker-compose.dev.yml (this post, pre-wired)
Dockerfile.dev for both web and api
A working migration flow with Prisma — db:migrate and db:seed commands that run inside the container
Healthchecks pre-wired on every service that needs one
GitHub Actions pipeline: lint → test → build image → push to registry → deploy
JWT auth with refresh tokens — the hardest part of most apps to get right from scratch

It'll be free, and email subscribers get it the day it ships. Subscribe at mahmoud-mokaddem.com.

What's next

If your local dev compose has a gotcha I didn't cover — a platform-specific failure, a dependency manager edge case, a Docker Desktop version that changed something — find me on X or LinkedIn. I'll add it to the post.

Dockerizing Next.js for production

Mahmoud Mokaddem — Sat, 02 May 2026 21:19:38 +0000

Most Dockerfiles for Next.js you'll find online ship a 1.2 GB image, leak environment variables at build time, and rebuild every layer on a one-line change. They work on the demo. They don't work in production.

This is the Dockerfile I actually run. Multi-stage, ~150 MB final image, build-time and runtime env vars cleanly separated, layer caching that survives a package.json change. I'll walk through every line, explain why each stage exists, and call out the four gotchas that account for most "it worked locally" production failures.

The full setup (Dockerfile plus docker-compose, GitHub Actions deploy pipeline, auth, testing) is in a production-grade Next.js + NestJS starter I'm building. Free for email subscribers — subscribe at mahmoud-mokaddem.com.

The Dockerfile, up front

If you're in a hurry, copy this and skip to Common gotchas. The rest of the post explains every line.

# Stage 1: deps
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

# Stage 2: builder
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED=1
RUN npm run build

# Stage 3: runner
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production NEXT_TELEMETRY_DISABLED=1
RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 nextjs
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
ENV PORT=3000 HOSTNAME=0.0.0.0
CMD ["node", "server.js"]

Three stages: deps, builder, runner. The first two do work; only the third ships.

Why multi-stage

A naïve Dockerfile copies your source, installs dependencies, builds, and runs — all in one stage. The image you ship to production carries everything that helped you build it: the full Node toolchain, npm's cache, dev dependencies, build artifacts you don't need at runtime, your .git directory if you weren't careful with .dockerignore. Easily 1+ GB.

Multi-stage builds let you do all that work in a "fat" intermediate image, then copy only the artifacts that need to ship into a clean final image. Each FROM starts a fresh image; COPY --from= reaches back into a previous stage to grab specific files.

For Next.js, the practical result: ~150 MB final image vs ~1.2 GB single-stage. Why this matters in production:

Faster registry pulls on small VPSes or autoscaling platforms. Pulling 1.2 GB on a 100 Mbps link takes ~96 seconds; pulling 150 MB takes ~12.
Faster cold starts on platforms like Fly.io and Cloud Run, where containers start on demand.
Lower registry cost when you push every commit.
Smaller security surface — fewer packages carrying potential CVEs in production.

The mental shortcut: do the messy work in a fat intermediate image, ship only the artifacts that need to run.

Stage 1 — Dependencies

FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

node:20-alpine is a deliberate trade-off. Alpine Linux is ~50 MB; node:20-slim is ~340 MB; node:20 (Debian-based) is ~1 GB. Alpine wins on size and is fine for almost every Next.js app.

The catch: Alpine uses musl libc instead of glibc. Some npm packages with prebuilt native binaries (historically canvas, sharp, certain database drivers) ship glibc binaries that don't load on Alpine. If you hit a binary-compatibility error during npm ci, the fix is usually to switch this stage's base to node:20-slim and accept the larger image. For a vanilla Next.js app, you'll never see this.

Notice we copy only package.json and package-lock.json, not the source. This is layer-caching discipline. Docker caches each layer; if a layer's input hasn't changed, it reuses the cached output. By isolating the dependency install to the lockfile, we get full cache reuse on every commit that doesn't touch dependencies — which is most of them. If we copied the source first, every code change would re-run npm ci from scratch.

About npm ci vs npm install: ci is deterministic, installs exactly what's in the lockfile, fails if the lockfile is out of date, and is faster. Always ci in Docker. (Yarn: yarn install --frozen-lockfile. pnpm: pnpm install --frozen-lockfile.)

Stage 2 — Builder

FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED=1
RUN npm run build

Fresh stage, fresh Alpine, node_modules pulled forward from stage 1. COPY . . brings in the source tree (filtered by .dockerignore, covered below).

The standalone output mode is the one Next.js config flag you actually need. Add it to your next.config.js:

module.exports = {
  output: 'standalone',
};

Without this flag, npm run build produces the standard Next.js build output and your final image has to ship the entire node_modules tree (~300 MB+). With it, Next.js traces every dependency actually used by your built routes and emits a self-contained server.js plus only those traced packages in .next/standalone/node_modules, typically ~15 MB. That one flag is the biggest size win in this Dockerfile.

npm run build produces three things we care about:

.next/standalone/ — the self-contained server plus traced node_modules
.next/static/ — built static assets (JS bundles, CSS) for _next/static/* routes
public/ — static files you put in the public folder, which Next.js doesn't bundle into standalone

Stage 3 copies these three things and nothing else.

Build-time vs runtime env vars

This is the most common Next.js + Docker bug I see, so it gets its own callout.

Variables prefixed NEXT_PUBLIC_ are baked into the client-side JavaScript bundle at build time. They are not read at runtime from the container's environment. If you set NEXT_PUBLIC_API_URL only at runtime via docker run -e, your client code will see whatever value it had at build time (usually empty), not what you set at runtime.

Two ways to handle it.

(a) Pass NEXT_PUBLIC_* as --build-arg and rebuild per environment:

ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
RUN npm run build

docker build \
  --build-arg NEXT_PUBLIC_API_URL=https://api.example.com \
  -t my-app .

(b) Keep NEXT_PUBLIC_* for things that don't change per deploy (your domain, public Stripe key, public Sentry DSN), and put environment-specific config behind server-side data fetching where you can read process.env at runtime.

I prefer (b). Fewer images, simpler pipeline. Use (a) only when you genuinely need the value baked into the client bundle.

Stage 3 — Runner

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production NEXT_TELEMETRY_DISABLED=1
RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 nextjs
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
ENV PORT=3000 HOSTNAME=0.0.0.0
CMD ["node", "server.js"]

Final stage. Fresh Alpine, no toolchain, no dev dependencies. This is what ships.

NODE_ENV=production matters. Next.js skips dev-only logging and telemetry, and many libraries optimize behavior based on it.

The non-root user: addgroup creates a system group, adduser creates a user in it, USER nextjs switches the runtime to that user. Many container platforms (Kubernetes, ECS, Fly with strict modes) refuse to run containers as root by default. Even when they don't, running as root expands the impact of any container-escape CVE. This costs nothing; do it now.

The three copies are where the standalone output pays off:

COPY --from=builder /app/public ./public — public/ is not part of the standalone output. Forget this line and all your favicons, robots.txt, and static images return 404. The first time. Always.
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./ — the actual server. --chown makes the non-root user own the files, otherwise it can't read its own runtime.
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static — also not in standalone. Forgetting this gives you a site with no JS or CSS.

EXPOSE 3000 is documentation, not a port-open. It tells docker run -p and orchestrators "this app expects to be reachable on 3000."

HOSTNAME=0.0.0.0 is required to accept connections from outside the container. Next.js's standalone server defaults to localhost, which means your container would only accept traffic from itself.

Use CMD ["node", "server.js"], not npm start. npm wraps the process and intercepts signals, so your container won't gracefully shut down on SIGTERM. Orchestrator-driven restarts hang for 30+ seconds before the kernel kills it. node server.js handles signals correctly.

The .dockerignore file

This file gets skipped a lot, and it's often the answer to "why is my build context 2 GB?"

node_modules
.next
.git
.env*
README.md
*.log
coverage
.vscode
.idea
.DS_Store

Why each entry:

node_modules — gets reinstalled in the deps stage.
.next — build artifacts get rebuilt; carrying old ones in confuses Next.js's cache.
.git — your version history shouldn't ship in the container.
.env* — never bake secrets into images. Pass at runtime.
Logs, IDE folders, coverage reports — clutter.

The .env* line is a security concern worth dwelling on. If you've ever had an .env.local sitting in your working directory, .dockerignore is what keeps it out of the image. An image with .env.production baked in can be pulled by anyone with read access to your registry. Put real secrets in your runtime environment, not in the image.

Image size walkthrough

Approach	Final image
Naïve single-stage on `node:20`	~1.2 GB
Multi-stage on `node:20` (no standalone)	~600 MB
Multi-stage on `node:20-alpine` (no standalone)	~400 MB
Multi-stage on `node:20-alpine` + standalone	~150 MB

Numbers are approximate; your app's specific dependencies move them ±20%.

What this saves you: deploy time drops from ~96 seconds to ~12 on a 100 Mbps registry pull. Cold start time on Fly or Cloud Run becomes meaningful at the standalone size. The biggest win is the standalone output flag. The Alpine base is second. Multi-stage is the structural decision that makes both composable.

docker-compose for local dev

This Dockerfile builds the production image. For local dev you usually want hot reload, a local Postgres, maybe Redis. A minimal compose file:

services:
  app:
    build: .
    ports: ['3000:3000']
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/myapp
    depends_on: [db]
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: myapp
    volumes: ['db_data:/var/lib/postgresql/data']
volumes:
  db_data:

This runs the production build locally, which is useful for catching prod-only bugs but not for hot reload. For real dev work you want a separate docker-compose.dev.yml with the source mounted as a volume and next dev running. That's a full post in itself — coming next in this series.

Common gotchas

The four bugs that account for most "it worked locally" production failures with this setup:

1. Public folder not appearing. You forgot COPY --from=builder /app/public ./public. Symptom: 404s on every static asset. Fix: add the line.

2. NEXT_PUBLIC_* env vars not reaching the client. They were set at runtime, not build time. Symptom: client-side code reads undefined or stale values. Fix: pass via --build-arg (per the Stage 2 section) or restructure so the value isn't needed in the client bundle.

3. Container exits immediately, no logs. You're using npm start instead of node server.js. npm wraps the process and hides what's happening. Fix: CMD ["node", "server.js"].

4. OOM during npm run build on a small VPS. Hetzner CX11 / DigitalOcean $4 droplets often can't fit a Next.js build in RAM. Symptom: build fails with JavaScript heap out of memory or gets SIGKILLed. Fix: build in CI/CD and push the image to your registry, then pull on the VPS; or add a swap file on the VPS.

Each one has happened to me. Each one looks unrelated to Docker until you find it.

Where to deploy this

The Dockerfile doesn't change; the deploy target does.

Hetzner VPS + Coolify or Dokploy — cheapest, most control. What I'd pick for indie projects. Push the image to GitHub Container Registry; Coolify pulls and runs it.
DigitalOcean App Platform — push the Dockerfile, get a URL. Good middle ground.
Fly.io — global edge deploy, generous free tier for hobby work. fly launch auto-detects Next.js and writes a fly.toml for you.
AWS ECS / Fargate — enterprise default. More setup overhead, but the right call if you're already in AWS.

Each of these gets its own deploy walkthrough later in this series. The Dockerfile above works on all of them unchanged.

What's next

Two follow-ups in this series:

docker-compose for Next.js + NestJS local dev — the full dev-mode compose file with hot reload, Postgres, and Redis.
How I structure a NestJS project for production — the architecture conventions in the starter, with rationale.

If you've shipped this Dockerfile to a deploy target I didn't cover, I'd be curious what platform you picked and what bit you.

The full setup (Dockerfile, .dockerignore, docker-compose, GitHub Actions deploy pipeline, auth, testing) is in a production-grade Next.js + NestJS starter I'm building. Free for email subscribers — subscribe at mahmoud-mokaddem.com.

DEV Community: Mahmoud Mokaddem

docker-compose for Next.js + NestJS local dev

The compose file, up front

Why a separate .dev.yml

Service: web (Next.js)

The volume pattern that keeps hot reload working

WATCHPACK_POLLING

NEXT_PUBLIC_API_URL

depends_on

Service: api (NestJS)

DATABASE_URL and docker-network hostnames

depends_on with service_healthy

Service: db (Postgres)

The healthcheck

Optional services

Common gotchas

The everyday workflow

The full setup is in the starter

What's next

Dockerizing Next.js for production

The Dockerfile, up front

Why multi-stage

Stage 1 — Dependencies

Stage 2 — Builder

Build-time vs runtime env vars

Stage 3 — Runner

The .dockerignore file

Image size walkthrough

docker-compose for local dev

Common gotchas

Where to deploy this

What's next

Why a separate `.dev.yml`

Service: `web` (Next.js)

Service: `api` (NestJS)

Service: `db` (Postgres)