Docker voor Node.js: De Productie-Klare Setup Waar Niemand Over Praat | Akousa

10 november 202524 min leestijd

Docker voor Node.js: De Productie-Klare Setup Waar Niemand Over Praat

Multi-stage builds, non-root users, health checks, secrets management en image-optimalisatie. De Docker-patronen die ik gebruik voor elke Node.js-productiedeployment.

De meeste Node.js Dockerfiles in productie zijn slecht. Niet "een beetje suboptimaal" slecht. Ik bedoel draaien als root, 600MB images shippen met devDependencies erin gebakken, geen health checks, en secrets hardcoded in environment variables die iedereen met docker inspect kan lezen.

Ik weet het omdat ik die Dockerfiles schreef. Jarenlang. Ze werkten, dus ik stelde ze nooit ter discussie. Toen markeerde een security audit op een dag dat onze container als PID 1 root draaide met schrijftoegang tot het hele bestandssysteem, en besefte ik dat "werkt" en "productie-klaar" heel verschillende drempels zijn.

This setup is a production-tested baseline for Node.js services. Every pattern here exists because the weaker alternative tends to fail under real traffic.

Waarom Je Huidige Dockerfile Waarschijnlijk Fout Is

Laat me raden hoe je Dockerfile eruitziet:

dockerfile

# Single stage: ~600MB
FROM node:20
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "server.js"]
 
# Multi-stage: ~150MB
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
CMD ["node", "dist/server.js"]

Aanpak	Image-grootte
`node:20` + `npm install`	1,1 GB
`node:20-slim` + `npm install`	420 MB
`node:20-alpine` + `npm ci`	280 MB
Multi-stage + alpine + alleen productie-deps	150 MB
Multi-stage + alpine + opgeschoonde deps	95 MB

dockerfile

# ============================================
# Stage 1: Dependencies installeren
# ============================================
FROM node:20-alpine AS deps
 
# Beveiliging: maak een werkdirectory aan voordat je iets anders doet
WORKDIR /app
 
# Installeer dependencies op basis van het lockfile
# Kopieer ALLEEN package-bestanden eerst — dit is cruciaal voor layer caching
COPY package.json package-lock.json ./
 
# ci is beter dan install: het is sneller, strikter en reproduceerbaar
# --omit=dev sluit devDependencies uit van deze stage
RUN npm ci --omit=dev
 
# ============================================
# Stage 2: De applicatie bouwen
# ============================================
FROM node:20-alpine AS builder
 
WORKDIR /app
 
# Kopieer package-bestanden en installeer ALLE dependencies (inclusief dev)
COPY package.json package-lock.json ./
RUN npm ci
 
# NU broncode kopieren — wijzigingen hier invalideren de npm ci-cache niet
COPY . .
 
# Bouw de applicatie (TypeScript-compilatie, Next.js build, etc.)
RUN npm run build
 
# ============================================
# Stage 3: Productie-runner
# ============================================
FROM node:20-alpine AS runner
 
# Voeg labels toe voor image-metadata
LABEL maintainer="your-email@example.com"
LABEL org.opencontainers.image.source="https://github.com/yourorg/yourrepo"
 
# Beveiliging: installeer dumb-init voor correcte PID 1-signaalafhandeling
RUN apk add --no-cache dumb-init
 
# Beveiliging: stel NODE_ENV in voordat je iets anders doet
ENV NODE_ENV=production
 
# Beveiliging: gebruik non-root user
# Het node-image bevat al een 'node'-gebruiker (uid 1000)
USER node
 
# Maak app-directory aan eigendom van node-gebruiker
WORKDIR /app
 
# Kopieer productie-dependencies vanuit de deps-stage
COPY --from=deps --chown=node:node /app/node_modules ./node_modules
 
# Kopieer gebouwde applicatie vanuit de builder-stage
COPY --from=deps --chown=node:node /app/package.json ./
COPY --from=builder --chown=node:node /app/dist ./dist
 
# Stel de poort bloot (alleen documentatie — publiceert het niet)
EXPOSE 3000
 
# Health check: curl is niet beschikbaar in alpine, gebruik node
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"
 
# Gebruik dumb-init als PID 1 om signalen correct af te handelen
ENTRYPOINT ["dumb-init", "--"]
 
# Start de applicatie
CMD ["node", "dist/server.js"]

javascript

// server.js
const server = app.listen(3000);
 
process.on("SIGTERM", () => {
  console.log("SIGTERM received, shutting down gracefully");
  server.close(() => {
    console.log("HTTP server closed");
    // Sluit databaseverbindingen, flush logs, etc.
    process.exit(0);
  });
});

# .dockerignore
node_modules
npm-debug.log*
.git
.gitignore
.env
.env.*
!.env.example
Dockerfile
docker-compose*.yml
.dockerignore
README.md
LICENSE
.github
.vscode
.idea
coverage
.nyc_output
*.test.ts
*.test.js
*.spec.ts
*.spec.js
__tests__
test
tests
docs
.husky
.eslintrc*
.prettierrc*
tsconfig.json
jest.config.*
vitest.config.*

dockerfile

# syntax=docker/dockerfile:1
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
 
# Mount het secret tijdens build — het wordt nooit opgeslagen in het image
RUN --mount=type=secret,id=npmrc,target=/app/.npmrc \
    npm ci
 
COPY . .
RUN npm run build

yaml

# docker-compose.yml (Swarm mode)
version: "3.8"
services:
  api:
    image: myapp:latest
    secrets:
      - db_password
      - api_key
 
secrets:
  db_password:
    external: true
  api_key:
    external: true

javascript

import { readFileSync } from "fs";
 
function getSecret(name) {
  try {
    return readFileSync(`/run/secrets/${name}`, "utf8").trim();
  } catch {
    // Fallback naar environment variable voor lokale ontwikkeling
    return process.env[name.toUpperCase()];
  }
}
 
const dbPassword = getSecret("db_password");

dockerfile

HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"

javascript

// healthcheck.js
const http = require("http");
 
const options = {
  hostname: "localhost",
  port: 3000,
  path: "/health",
  timeout: 5000,
};
 
const req = http.request(options, (res) => {
  process.exit(res.statusCode === 200 ? 0 : 1);
});
 
req.on("error", () => process.exit(1));
req.on("timeout", () => {
  req.destroy();
  process.exit(1);
});
 
req.end();

javascript

app.get("/health", async (req, res) => {
  const checks = {
    uptime: process.uptime(),
    timestamp: Date.now(),
    status: "ok",
  };
 
  try {
    // Controleer databaseverbinding
    await db.query("SELECT 1");
    checks.database = "connected";
  } catch (err) {
    checks.database = "disconnected";
    checks.status = "degraded";
  }
 
  try {
    // Controleer Redis-verbinding
    await redis.ping();
    checks.redis = "connected";
  } catch (err) {
    checks.redis = "disconnected";
    checks.status = "degraded";
  }
 
  const statusCode = checks.status === "ok" ? 200 : 503;
  res.status(statusCode).json(checks);
});

yaml

# docker-compose.dev.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
      args:
        NODE_VERSION: "20"
    ports:
      - "3000:3000"
      - "9229:9229" # Node.js debugger
    volumes:
      # Mount broncode voor hot reload
      - .:/app
      # Anoniem volume om node_modules van het image te behouden
      # Dit voorkomt dat de node_modules van de host die van de container overschrijft
      - /app/node_modules
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgres://postgres:devpassword@db:5432/myapp_dev
      - REDIS_URL=redis://redis:6379
    env_file:
      - .env.local
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    command: npm run dev
 
  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: myapp_dev
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: devpassword
    volumes:
      # Named volume voor persistente data tussen container-herstarts
      - pgdata:/var/lib/postgresql/data
      # Initialisatiescripts
      - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
 
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data
    command: redis-server --appendonly yes
 
  # Optioneel: database admin-UI
  adminer:
    image: adminer:latest
    ports:
      - "8080:8080"
    depends_on:
      - db
 
volumes:
  pgdata:
  redisdata:

dockerfile

# Dockerfile.dev
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine
 
WORKDIR /app
 
# Installeer alle dependencies (inclusief devDependencies)
COPY package*.json ./
RUN npm ci
 
# Broncode wordt via volume gemount, niet gekopieerd
# Maar we hebben het nog steeds nodig voor de eerste build
COPY . .
 
EXPOSE 3000 9229
 
CMD ["npm", "run", "dev"]

yaml

# docker-compose.prod.yml
services:
  app:
    image: ghcr.io/yourorg/myapp:${TAG:-latest}
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    env_file:
      - .env.production
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          cpus: "0.25"
          memory: 128M
      replicas: 2
    healthcheck:
      test:
        [
          "CMD",
          "node",
          "-e",
          "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode === 200 ? 0 : 1))",
        ]
      interval: 30s
      timeout: 10s
      start_period: 40s
      retries: 3
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    networks:
      - internal
      - web
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
 
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 1G
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - internal
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
 
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: >
      redis-server
      --appendonly yes
      --maxmemory 256mb
      --maxmemory-policy allkeys-lru
    volumes:
      - redisdata:/data
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 512M
    networks:
      - internal
    logging:
      driver: "json-file"
      options:
        max-size: "5m"
        max-file: "3"
 
volumes:
  pgdata:
    driver: local
  redisdata:
    driver: local
 
networks:
  internal:
    driver: bridge
  web:
    external: true

dockerfile

# ============================================
# Stage 1: Dependencies installeren
# ============================================
FROM node:20-alpine AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
 
COPY package.json package-lock.json ./
RUN npm ci
 
# ============================================
# Stage 2: De applicatie bouwen
# ============================================
FROM node:20-alpine AS builder
WORKDIR /app
 
COPY --from=deps /app/node_modules ./node_modules
COPY . .
 
# Schakel Next.js-telemetrie uit tijdens build
ENV NEXT_TELEMETRY_DISABLED=1
 
RUN npm run build
 
# ============================================
# Stage 3: Productie-runner
# ============================================
FROM node:20-alpine AS runner
WORKDIR /app
 
RUN apk add --no-cache dumb-init
 
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
 
# Non-root gebruiker
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
 
# Kopieer publieke assets
COPY --from=builder /app/public ./public
 
# Stel de standalone output-directory in
# Maakt automatisch gebruik van output traces om de image-grootte te verkleinen
# https://nextjs.org/docs/advanced-features/output-file-tracing
RUN mkdir .next
RUN chown nextjs:nodejs .next
 
# Kopieer de standalone server en statische bestanden
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
ENV HOSTNAME="0.0.0.0"
 
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/api/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"
 
ENTRYPOINT ["dumb-init", "--"]
CMD ["node", "server.js"]

myapp:latest (alpine 3.19.1)
=============================
Total: 0 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 0, CRITICAL: 0)

Node.js (node_modules/package-lock.json)
=========================================
Total: 2 (UNKNOWN: 0, LOW: 0, MEDIUM: 1, HIGH: 1, CRITICAL: 0)

┌──────────────┬────────────────┬──────────┬────────┬───────────────┐
│   Library    │ Vulnerability  │ Severity │ Status │ Fixed Version │
├──────────────┼────────────────┼──────────┼────────┼───────────────┤
│ semver       │ CVE-2022-25883 │ HIGH     │ fixed  │ 7.5.4         │
│ word-wrap    │ CVE-2023-26115 │ MEDIUM   │ fixed  │ 1.2.4         │
└──────────────┴────────────────┴──────────┴────────┴───────────────┘

yaml

# .github/workflows/docker.yml
- name: Build image
  run: docker build -t myapp:${{ github.sha }} .
 
- name: Scan image
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: myapp:${{ github.sha }}
    exit-code: 1
    severity: CRITICAL,HIGH
    ignore-unfixed: true

yaml

# .github/workflows/docker.yml
name: Build and Push Docker Image
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
 
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      security-events: write
 
    steps:
      - name: Checkout
        uses: actions/checkout@v4
 
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
 
      - name: Log in to Container Registry
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
 
      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=sha
            type=ref,event=branch
            type=semver,pattern={{version}}
 
      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
 
      - name: Scan image with Trivy
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:sha-${{ github.sha }}
          exit-code: 1
          severity: CRITICAL,HIGH
          ignore-unfixed: true
 
      - name: Upload Trivy results
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: trivy-results.sarif

dockerfile

# Build-time configuratie
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine
 
# Runtime configuratie
ENV PORT=3000
 
# FOUT: Dit maakt het secret zichtbaar in het image
ARG API_KEY
ENV API_KEY=${API_KEY}
 
# GOED: Geef secrets mee tijdens runtime
# docker run -e API_KEY=secret myapp

yaml

# docker-compose.monitoring.yml
services:
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    ports:
      - "9090:9090"
    networks:
      - internal
 
  grafana:
    image: grafana/grafana:latest
    volumes:
      - grafana_data:/var/lib/grafana
    ports:
      - "3001:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
    networks:
      - internal
 
volumes:
  prometheus_data:
  grafana_data:

javascript

import { collectDefaultMetrics, Registry, Histogram } from "prom-client";
 
const register = new Registry();
collectDefaultMetrics({ register });
 
const httpRequestDuration = new Histogram({
  name: "http_request_duration_seconds",
  help: "Duration of HTTP requests in seconds",
  labelNames: ["method", "route", "status_code"],
  buckets: [0.01, 0.05, 0.1, 0.5, 1, 5],
  registers: [register],
});
 
// Middleware
app.use((req, res, next) => {
  const end = httpRequestDuration.startTimer();
  res.on("finish", () => {
    end({ method: req.method, route: req.route?.path || req.path, status_code: res.statusCode });
  });
  next();
});
 
// Metrics endpoint
app.get("/metrics", async (req, res) => {
  res.set("Content-Type", register.contentType);
  res.end(await register.metrics());
});

Aanpak	Image-grootte
`node:20` + volledige `node_modules` + `.next`	1,4 GB
`node:20-alpine` + volledige `node_modules` + `.next`	600 MB
`node:20-alpine` + standalone output	120 MB

Waarom Je Huidige Dockerfile Waarschijnlijk Fout Is

Draaien als Root

devDependencies Installeren in Productie

Alles Kopieren

Geen Health Checks

Geen Layer Caching-Strategie

Multi-Stage Builds: De Grootste Winst

Echte Groottevergelijkingen

Waarom Alpine?

De Complete Productie-Dockerfile

Waarom Drie Stages in Plaats van Twee?

Waarom dumb-init?

Het .dockerignore-Bestand

Layer Caching: Stop Met 3 Minuten Wachten Per Build

De Verkeerde Volgorde

De Juiste Volgorde

Cache Mount voor npm

ARG Gebruiken voor Cache Busting

Secrets Management: Stop Met Secrets in Je Dockerfile Zetten

De Drie Niveaus van Secrets

.env-Bestanden en Docker

Health Checks: Laat Docker Weten Dat Je App Echt Werkt

De HEALTHCHECK-Instructie

Waarom Geen curl?

Het Health Endpoint

Waarom Health Checks Belangrijk Zijn voor Orchestrators

docker-compose voor Ontwikkeling

Belangrijke Ontwikkelpatronen

De Ontwikkel-Dockerfile

Productie Docker Compose

Wat Anders Is Dan Ontwikkeling

Next.js Specifiek: De Standalone Output

De Next.js Productie-Dockerfile

Groottevergelijking voor Next.js

Statische Bestandsafhandeling

Sharp voor Image-Optimalisatie

Image Scanning en Beveiliging

Trivy: Scan Je Images

Alleen-Lezen Bestandssysteem

Alle Capabilities Verwijderen

Pin Je Base Image Digest

CI/CD-Integratie: Alles Samenbrengen

BuildKit Cache in CI

Veelvoorkomende Valkuilen en Hoe Ze Te Vermijden

Het node_modules Binnenin het Image vs Host-Conflict

SIGTERM-Afhandeling in TypeScript-Projecten

Geheugenlimieten en Node.js

Tijdzoneproblemen

Build Arguments vs Environment Variables

Monitoring in Productie

De Checklist

Gerelateerde artikelen

Monorepos in 2026: Nx, Turborepo, and the Lessons Nobody Shares

YAML Validator Guide: Catch Config Errors Before Deploy