Docker pro Node.js: Produkční setup, o kterém se nemluví | Akousa

10. listopadu 202522 min čtení

Docker pro Node.js: Produkční setup, o kterém se nemluví

Multi-stage buildy, non-root uživatelé, health checky, správa secrets a optimalizace velikosti image. Docker patterny, které používám pro každý produkční Node.js deployment.

Většina Node.js Dockerfilů v produkci je špatná. Ne "mírně suboptimální" špatná. Mám na mysli běh jako root, odesílání 600MB imagí s devDependencies zapečenými uvnitř, žádné health checky a secrets natvrdo zakódované v proměnných prostředí, které si kdokoliv s docker inspect může přečíst.

Vím to, protože jsem takhle ty Dockerfily psal. Celé roky. Fungovaly, takže jsem je nikdy nezpochybňoval. Pak jednoho dne bezpečnostní audit označil náš kontejner běžící jako PID 1 root s přístupem pro zápis do celého filesystému a já si uvědomil, že "funguje" a "připravené na produkci" jsou velmi odlišné laťky.

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.

Proč je váš současný Dockerfile pravděpodobně špatně

Hádám, jak vypadá váš Dockerfile:

dockerfile

# Jedna 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"]

Přístup	Velikost Image
`node:20` + `npm install`	1,1 GB
`node:20-slim` + `npm install`	420 MB
`node:20-alpine` + `npm ci`	280 MB
Multi-stage + alpine + pouze produkční deps	150 MB
Multi-stage + alpine + prořezané deps	95 MB

dockerfile

# ============================================
# Stage 1: Instalace závislostí
# ============================================
FROM node:20-alpine AS deps
 
# Bezpečnost: vytvoření pracovního adresáře před čímkoliv jiným
WORKDIR /app
 
# Instalace závislostí na základě lockfile
# Nejprve zkopírujte POUZE package soubory — to je kritické pro layer caching
COPY package.json package-lock.json ./
 
# ci je lepší než install: je rychlejší, přísnější a reprodukovatelný
# --omit=dev vylučuje devDependencies z této stage
RUN npm ci --omit=dev
 
# ============================================
# Stage 2: Sestavení aplikace
# ============================================
FROM node:20-alpine AS builder
 
WORKDIR /app
 
# Zkopírujte package soubory a nainstalujte VŠECHNY závislosti (včetně dev)
COPY package.json package-lock.json ./
RUN npm ci
 
# TEĎ zkopírujte zdrojový kód — změny zde neinvalidují npm ci cache
COPY . .
 
# Sestavte aplikaci (TypeScript kompilace, Next.js build, atd.)
RUN npm run build
 
# ============================================
# Stage 3: Produkční runner
# ============================================
FROM node:20-alpine AS runner
 
# Přidejte labely pro metadata image
LABEL maintainer="your-email@example.com"
LABEL org.opencontainers.image.source="https://github.com/yourorg/yourrepo"
 
# Bezpečnost: nainstalujte dumb-init pro správné zpracování signálů PID 1
RUN apk add --no-cache dumb-init
 
# Bezpečnost: nastavte NODE_ENV před čímkoliv jiným
ENV NODE_ENV=production
 
# Bezpečnost: použijte non-root uživatele
# Node image již obsahuje uživatele 'node' (uid 1000)
USER node
 
# Vytvořte adresář aplikace vlastněný uživatelem node
WORKDIR /app
 
# Zkopírujte produkční závislosti z deps stage
COPY --from=deps --chown=node:node /app/node_modules ./node_modules
 
# Zkopírujte sestavenou aplikaci z builder stage
COPY --from=deps --chown=node:node /app/package.json ./
COPY --from=builder --chown=node:node /app/dist ./dist
 
# Exponujte port (pouze dokumentace — nepublikuje ho)
EXPOSE 3000
 
# Health check: curl není v alpine k dispozici, použijte 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) })"
 
# Použijte dumb-init jako PID 1 pro správné zpracování signálů
ENTRYPOINT ["dumb-init", "--"]
 
# Spusťte aplikaci
CMD ["node", "dist/server.js"]

javascript

// server.js
const server = app.listen(3000);
 
process.on("SIGTERM", () => {
  console.log("SIGTERM přijat, korektní vypínání");
  server.close(() => {
    console.log("HTTP server uzavřen");
    // Uzavřete databázová spojení, vyprázdněte logy, atd.
    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 ./
 
# Připojte secret v době buildu — nikdy se neuloží do image
RUN --mount=type=secret,id=npmrc,target=/app/.npmrc \
    npm ci
 
COPY . .
RUN npm run build

yaml

# docker-compose.yml (Swarm mód)
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 {
    // Záloha na proměnnou prostředí pro lokální vývoj
    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 {
    // Kontrola databázového připojení
    await db.query("SELECT 1");
    checks.database = "connected";
  } catch (err) {
    checks.database = "disconnected";
    checks.status = "degraded";
  }
 
  try {
    // Kontrola Redis připojení
    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:
      # Připojení zdrojového kódu pro hot reload
      - .:/app
      # Anonymní volume pro zachování node_modules z image
      # Zabraňuje tomu, aby host node_modules přepsal kontejnerový
      - /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 pro perzistentní data mezi restarty kontejneru
      - pgdata:/var/lib/postgresql/data
      # Inicializační skripty
      - ./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
 
  # Volitelné: administrační UI databáze
  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
 
# Nainstalujte všechny závislosti (včetně devDependencies)
COPY package*.json ./
RUN npm ci
 
# Zdrojový kód je připojen přes volume, ne kopírován
# Ale stále ho potřebujeme pro úvodní 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: Instalace závislostí
# ============================================
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: Sestavení aplikace
# ============================================
FROM node:20-alpine AS builder
WORKDIR /app
 
COPY --from=deps /app/node_modules ./node_modules
COPY . .
 
# Vypněte telemetrii Next.js během buildu
ENV NEXT_TELEMETRY_DISABLED=1
 
RUN npm run build
 
# ============================================
# Stage 3: Produkční 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 uživatel
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
 
# Zkopírujte veřejné assety
COPY --from=builder /app/public ./public
 
# Nastavte adresář standalone výstupu
# Automaticky využívá output traces ke snížení velikosti image
# https://nextjs.org/docs/advanced-features/output-file-tracing
RUN mkdir .next
RUN chown nextjs:nodejs .next
 
# Zkopírujte standalone server a statické soubory
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

# Konfigurace v době buildu
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}-alpine
 
# Konfigurace za běhu
ENV PORT=3000
 
# ŠPATNĚ: Toto zpřístupní secret v image
ARG API_KEY
ENV API_KEY=${API_KEY}
 
# SPRÁVNĚ: Předejte secrets za běhu
# 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: "Doba trvání HTTP požadavků v sekundách",
  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();
});
 
// Endpoint pro metriky
app.get("/metrics", async (req, res) => {
  res.set("Content-Type", register.contentType);
  res.end(await register.metrics());
});

Přístup	Velikost Image
`node:20` + plné `node_modules` + `.next`	1,4 GB
`node:20-alpine` + plné `node_modules` + `.next`	600 MB
`node:20-alpine` + standalone výstup	120 MB

Proč je váš současný Dockerfile pravděpodobně špatně

Běh jako Root

Instalace devDependencies v produkci

COPY všeho

Žádné Health Checky

Žádná strategie Layer Cachingu

Multi-Stage Buildy: Jediná největší výhra

Reálné porovnání velikostí

Proč Alpine?

Kompletní produkční Dockerfile

Proč tři stage místo dvou?

Proč dumb-init?

Soubor .dockerignore

Layer Caching: Přestaňte čekat 3 minuty na každý build

Špatné pořadí

Správné pořadí

Cache Mount pro npm

Použití ARG pro Cache Busting

Správa Secrets: Přestaňte dávat secrets do Dockerfilu

Tři úrovně Secrets

Soubory .env a Docker

Health Checky: Dejte Dockeru vědět, že vaše aplikace skutečně funguje

Instrukce HEALTHCHECK

Proč nepoužít curl?

Health Endpoint

Proč záleží na Health Checkech pro orchestrátory

docker-compose pro vývoj

Klíčové vývojové patterny

Vývojový Dockerfile

Produkční Docker Compose

Co je jinak oproti vývoji

Next.js specifické: Standalone výstup

Produkční Dockerfile pro Next.js

Porovnání velikostí pro Next.js

Zpracování statických souborů

Sharp pro optimalizaci obrázků

Skenování image a bezpečnost

Trivy: Skenujte vaše image

Read-Only Filesystem

Odebrání všech Capabilities

Připnutí digestu základního image

CI/CD integrace: Sestavení celku

BuildKit cache v CI

Časté problémy a jak se jim vyhnout

Konflikt node_modules uvnitř image vs host

Zpracování SIGTERM v TypeScript projektech

Paměťové limity a Node.js

Problémy s časovým pásmem

Build Arguments vs proměnné prostředí

Monitoring v produkci

Kontrolní seznam

Související články

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

YAML Validator Guide: Catch Config Errors Before Deploy