Docker pour Node.js : la configuration production-ready dont personne ne parle | Akousa

dockerfile

# Étape 1 : Image de base avec configuration commune
FROM node:20-slim AS base
 
# Définir le répertoire de travail
WORKDIR /app
 
# Installer dumb-init pour une gestion correcte des signaux
RUN apt-get update && apt-get install -y --no-install-recommends dumb-init \
    && rm -rf /var/lib/apt/lists/*
 
# Étape 2 : Installer les dépendances
FROM base AS deps
 
# Copier les fichiers de dépendances en premier (cache de couche)
COPY package.json package-lock.json ./
 
# Installer TOUTES les dépendances (y compris dev pour le build)
RUN npm ci --ignore-scripts
 
# Étape 3 : Builder
FROM deps AS builder
 
# Copier le code source
COPY . .
 
# Générer le build
RUN npm run build
 
# Supprimer les devDependencies après le build
RUN npm prune --production
 
# Étape 4 : Image de production
FROM base AS runner
 
# Créer un utilisateur non-root
RUN groupadd --system --gid 1001 nodejs \
    && useradd --system --uid 1001 --gid nodejs nodejs
 
# Copier uniquement ce qui est nécessaire depuis le builder
COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nodejs:nodejs /app/package.json ./package.json
 
# Passer à l'utilisateur non-root
USER nodejs
 
# Exposer le port
EXPOSE 3000
 
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD node -e "fetch('http://localhost:3000/health').then(r => { if (!r.ok) throw new Error(); })"
 
# Utiliser dumb-init comme PID 1
ENTRYPOINT ["dumb-init", "--"]
 
# Démarrer l'application
CMD ["node", "dist/server.js"]

dockerfile

# Alpine utilise musl libc au lieu de glibc
# Cela entraîne des différences subtiles de comportement :
 
# 1. La résolution DNS fonctionne différemment
# Alpine n'utilise pas nsswitch.conf, ce qui peut causer des problèmes
# avec le DNS Kubernetes ou Docker Compose.
 
# 2. Les modules natifs nécessitent une compilation différente
# bcrypt, sharp, canvas — tous doivent être compilés pour musl
# Parfois cela fonctionne. Parfois vous obtenez des erreurs de segfault.
 
# 3. Les performances peuvent être moins bonnes
# musl alloue la mémoire différemment que glibc.
# Pour les charges de travail Node.js, c'est rarement significatif,
# mais le profilage peut montrer des différences inattendues.

bash

# Vous envoyez SIGTERM au conteneur (c'est ce que fait docker stop)
docker stop mon-conteneur
 
# Docker envoie SIGTERM au PID 1 (votre processus Node.js)
# Mais le PID 1 reçoit un traitement spécial des signaux par le noyau :
# - Les processus normaux ont des gestionnaires de signaux par défaut
# - Le PID 1 N'A PAS de gestionnaires de signaux par défaut
# - Sauf si votre code gère explicitement SIGTERM, il est ignoré
 
# Docker attend 10 secondes (le délai par défaut)
# Rien ne se passe parce que Node.js a ignoré le signal
 
# Docker envoie SIGKILL (arrêt forcé non interceptable)
# Votre application s'arrête immédiatement sans nettoyage
# - Pas de fermeture propre des connexions à la base de données
# - Pas de fin des requêtes en cours
# - Pas de vidage des tampons d'écriture

javascript

// Gestion propre de l'arrêt
process.on("SIGTERM", async () => {
  console.log("SIGTERM reçu. Arrêt propre...");
 
  // Arrêter d'accepter de nouvelles connexions
  server.close();
 
  // Attendre la fin des requêtes en cours (avec timeout)
  await Promise.race([waitForConnections(), new Promise((resolve) => setTimeout(resolve, 10000))]);
 
  // Fermer les connexions à la base de données
  await db.end();
 
  process.exit(0);
});

dockerfile

# ❌ Mauvais : chaque changement de fichier invalide le cache de npm install
COPY . .
RUN npm install
 
# ✅ Bon : les fichiers de dépendances changent rarement
COPY package.json package-lock.json ./
RUN npm ci
COPY . .

bash

# Sans cache de couche approprié :
# Chaque build : npm ci → 30-60 secondes
 
# Avec cache de couche approprié :
# Build quand les dépendances changent : 30-60 secondes
# Build quand seul le code change : 2-5 secondes (cache npm utilisé)

bash

# npm install :
# - Lit package.json
# - Résout les dépendances (peut obtenir des versions différentes selon le moment)
# - Met à jour package-lock.json s'il y a des écarts
# - Installe les packages
 
# npm ci :
# - Lit package-lock.json (et UNIQUEMENT package-lock.json)
# - Installe exactement les versions spécifiées
# - Supprime node_modules existant d'abord
# - Échoue si package-lock.json est désynchronisé avec package.json
# - Plus rapide car pas de résolution de dépendances

dockerfile

# Ignorer les scripts de packages pendant l'installation
RUN npm ci --ignore-scripts
 
# Si certains packages ont réellement besoin de scripts d'installation
# (par exemple, bcrypt qui doit être compilé), exécutez-les sélectivement :
RUN npm ci --ignore-scripts \
    && npm rebuild bcrypt

dockerfile

# Créer un groupe et un utilisateur système
RUN groupadd --system --gid 1001 nodejs \
    && useradd --system --uid 1001 --gid nodejs nodejs
 
# Changer la propriété des fichiers de l'application
COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
 
# Passer à l'utilisateur non-root
USER nodejs

bash

# Avec l'utilisateur par défaut (root) :
# - Le processus peut lire/écrire n'importe quel fichier du conteneur
# - Si un attaquant exploite une vulnérabilité, il a un accès root
# - Les montages de volumes ont des permissions root
 
# Avec l'utilisateur nodejs :
# - Le processus ne peut lire/écrire que les fichiers appartenant à nodejs
# - L'impact d'une vulnérabilité est limité
# - Les montages de volumes doivent avoir les permissions appropriées
 
# Vérifier que ça fonctionne :
docker exec mon-conteneur whoami
# nodejs
 
docker exec mon-conteneur id
# uid=1001(nodejs) gid=1001(nodejs) groups=1001(nodejs)

dockerfile

# Créer le répertoire temporaire avec les bonnes permissions
RUN mkdir -p /app/tmp && chown nodejs:nodejs /app/tmp
 
# Ou si vous avez besoin du répertoire de logs
RUN mkdir -p /app/logs && chown nodejs:nodejs /app/logs

javascript

app.get("/health", async (req, res) => {
  const checks = {
    uptime: process.uptime(),
    timestamp: Date.now(),
    status: "ok",
  };
 
  try {
    // Vérifier la connexion à la base de données
    await db.query("SELECT 1");
    checks.database = "connected";
  } catch (error) {
    checks.database = "disconnected";
    checks.status = "degraded";
  }
 
  try {
    // Vérifier la connexion Redis
    await redis.ping();
    checks.redis = "connected";
  } catch (error) {
    checks.redis = "disconnected";
    checks.status = "degraded";
  }
 
  const statusCode = checks.status === "ok" ? 200 : 503;
  res.status(statusCode).json(checks);
});

yaml

# kubernetes-deployment.yaml
spec:
  containers:
    - name: app
      livenessProbe:
        httpGet:
          path: /health
          port: 3000
        initialDelaySeconds: 10
        periodSeconds: 30
      readinessProbe:
        httpGet:
          path: /health
          port: 3000
        initialDelaySeconds: 5
        periodSeconds: 10

dockerfile

# ❌ Les secrets dans ENV sont visibles dans docker inspect
ENV DATABASE_URL=postgres://user:password@host:5432/db
 
# ❌ Les secrets dans les arguments de build sont dans l'historique de l'image
ARG DATABASE_PASSWORD
RUN echo $DATABASE_PASSWORD > /app/.env
 
# ❌ Copier des fichiers .env les incorpore dans les couches de l'image
COPY .env .env

dockerfile

# Le Dockerfile ne contient aucun secret
# Les secrets sont passés au moment de l'exécution :
 
# Via les secrets Docker Swarm
docker service create \
    --secret db_password \
    --secret api_key \
    mon-app
 
# Via les secrets Kubernetes
kubectl create secret generic app-secrets \
    --from-literal=db-password=motdepasse \
    --from-literal=api-key=clé
 
# Via les fichiers d'environnement Docker Compose (non commités)
docker compose up  # avec env_file dans docker-compose.yml

dockerfile

# syntax=docker/dockerfile:1
 
FROM node:20-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
 
# Monter le secret au moment du build — il n'est jamais stocké dans les couches de l'image
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN=$(cat /run/secrets/npm_token) \
    npm ci --ignore-scripts
 
# Construire avec :
# DOCKER_BUILDKIT=1 docker build --secret id=npm_token,src=.npmrc .

dockerfile

# Taille sans multi-stage : ~600 Mo
# Taille avec multi-stage : ~150 Mo
 
# La différence vient de la non-inclusion de :
# - devDependencies (~200 Mo typiquement)
# - Code source (seul le code compilé est copié)
# - Outils de build, TypeScript, etc.
# - Fichiers de test, documentation

dockerfile

# Après le build, supprimer les devDependencies
RUN npm prune --production
 
# Cela supprime des éléments comme :
# - typescript
# - eslint et plugins
# - vitest/jest
# - prettier
# - @types/*
# - Le code de tout outil de build

dockerignore

# Dépendances
node_modules
 
# Contrôle de version
.git
.gitignore
 
# IDE
.vscode
.idea
*.swp
*.swo
 
# Tests et couverture
coverage
.nyc_output
*.test.ts
*.spec.ts
__tests__
 
# Documentation
*.md
LICENSE
 
# Environnement
.env
.env.*
 
# OS
.DS_Store
Thumbs.db
 
# Sortie de build (on reconstruit dans Docker)
dist
build
.next

bash

# Voir les tailles des images
docker images mon-app
# REPOSITORY   TAG       IMAGE ID       CREATED         SIZE
# mon-app      latest    abc123def456   2 minutes ago   147MB
 
# Plonger dans ce qui prend de la place
docker history mon-app:latest
 
# Pour une analyse détaillée, utilisez dive
# https://github.com/wagoodman/dive
dive mon-app:latest

yaml

# docker-compose.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: deps # S'arrêter à l'étape des dépendances, pas au runner de production
    volumes:
      - .:/app # Monter le code source pour le rechargement à chaud
      - /app/node_modules # Mais NE PAS monter node_modules (utiliser ceux du conteneur)
    ports:
      - "3000:3000"
      - "9229:9229" # Port de débogage Node.js
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgres://postgres:postgres@db:5432/myapp
      - REDIS_URL=redis://redis:6379
    command: npm run dev
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
 
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: myapp
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5
 
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data
 
volumes:
  pgdata:
  redisdata:

yaml

# docker-compose.override.yml (chargé automatiquement)
services:
  app:
    environment:
      - DEBUG=app:*
      - LOG_LEVEL=debug
    # Activer le débogage Node.js
    command: node --inspect=0.0.0.0:9229 --watch src/server.ts

bash

# Le scan intégré de Docker
docker scout cves mon-app:latest
 
# Ou utilisez Trivy (open source, très complet)
trivy image mon-app:latest
 
# Dans la CI, faites échouer le build sur les vulnérabilités critiques
trivy image --exit-code 1 --severity CRITICAL mon-app:latest

yaml

# .github/workflows/docker.yml
name: Docker Build and Push
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
jobs:
  build:
    runs-on: ubuntu-latest
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Configurer Docker Buildx
        uses: docker/setup-buildx-action@v3
 
      - name: Se connecter au registre
        if: github.event_name == 'push'
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
 
      - name: Extraire les métadonnées
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=sha,prefix=
            type=ref,event=branch
            type=semver,pattern={{version}}
 
      - name: Build et push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: ${{ github.event_name == 'push' }}
          tags: ${{ steps.meta.outputs.tags }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
 
      - name: Scanner les vulnérabilités
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: ghcr.io/${{ github.repository }}:${{ github.sha }}
          format: "sarif"
          output: "trivy-results.sarif"
          severity: "CRITICAL,HIGH"
 
      - name: Uploader les résultats du scan
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: "trivy-results.sarif"

dockerfile

# Définir la mémoire du tas Node.js explicitement
CMD ["node", "--max-old-space-size=384", "dist/server.js"]
 
# Ou utiliser la détection automatique (Node.js 20+)
CMD ["node", "--max-old-space-size=$(( $(cat /sys/fs/cgroup/memory.max) / 1024 / 1024 * 75 / 100 ))", "dist/server.js"]

yaml

# docker-compose.yml
services:
  app:
    deploy:
      resources:
        limits:
          memory: 512M
        reservations:
          memory: 256M
    environment:
      - NODE_OPTIONS=--max-old-space-size=384

dockerfile

# syntax=docker/dockerfile:1
 
# --- Étape de base ---
FROM node:20-slim AS base
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends dumb-init \
    && rm -rf /var/lib/apt/lists/*
 
# --- Étape des dépendances ---
FROM base AS deps
COPY package.json package-lock.json ./
RUN npm ci --ignore-scripts
 
# --- Étape de build ---
FROM deps AS builder
COPY . .
RUN npm run build \
    && npm prune --production
 
# --- Étape de production ---
FROM base AS runner
 
# Métadonnées
LABEL org.opencontainers.image.source="https://github.com/votre-utilisateur/votre-repo"
LABEL org.opencontainers.image.description="Application Node.js de production"
 
# Utilisateur non-root
RUN groupadd --system --gid 1001 nodejs \
    && useradd --system --uid 1001 --gid nodejs nodejs
 
# Copier les artefacts de build
COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nodejs:nodejs /app/package.json ./package.json
 
# Passer à l'utilisateur non-root
USER nodejs
 
# Définir l'environnement
ENV NODE_ENV=production
ENV PORT=3000
 
# Exposer le port
EXPOSE $PORT
 
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
    CMD node -e "fetch('http://localhost:3000/health').then(r => { if (!r.ok) throw new Error(); })"
 
# Utiliser dumb-init comme PID 1
ENTRYPOINT ["dumb-init", "--"]
 
# Démarrer avec les bonnes options mémoire
CMD ["node", "--max-old-space-size=384", "dist/server.js"]

Docker pour Node.js : la configuration production-ready dont personne ne parle

Pourquoi votre Dockerfile actuel est probablement mauvais

Exécution en root

Images énormes

Pas de cache de couche

Pas de health checks

Secrets dans les variables d'environnement

La configuration multi-étapes

Pourquoi `node:20-slim` et non `node:20` ou `node:20-alpine`

Le problème du PID 1

Le cache de couche qui compte vraiment

`npm ci` vs `npm install`

Configuration utilisateur non-root

Health checks qui fonctionnent réellement

Gestion des secrets

Les secrets au runtime (la bonne approche)

Les secrets au moment du build (quand il le faut)

Optimisation de la taille de l'image

Le build multi-étapes est le plus gros gain

Prune de production

L'instruction `.dockerignore`

Vérification de la taille de l'image

Docker Compose pour le développement

Override pour le développement

Sécurité au-delà des bases

Scan de l'image pour les vulnérabilités

Filesystem en lecture seule

Limitation des capacités

La configuration CI/CD

Gestion de la mémoire dans les conteneurs

Le Dockerfile final de production

Articles similaires

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

YAML Validator Guide: Catch Config Errors Before Deploy

Pourquoi votre Dockerfile actuel est probablement mauvais

Exécution en root

Images énormes

Pas de cache de couche

Pas de health checks

Secrets dans les variables d'environnement

La configuration multi-étapes

Pourquoi node:20-slim et non node:20 ou node:20-alpine

Le problème du PID 1

Le cache de couche qui compte vraiment

npm ci vs npm install

Configuration utilisateur non-root

Health checks qui fonctionnent réellement

Gestion des secrets

Les secrets au runtime (la bonne approche)

Les secrets au moment du build (quand il le faut)

Optimisation de la taille de l'image

Le build multi-étapes est le plus gros gain

Prune de production

L'instruction .dockerignore

Vérification de la taille de l'image

Docker Compose pour le développement

Override pour le développement

Sécurité au-delà des bases

Scan de l'image pour les vulnérabilités

Filesystem en lecture seule

Limitation des capacités

La configuration CI/CD

Gestion de la mémoire dans les conteneurs

Le Dockerfile final de production

Articles similaires

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

YAML Validator Guide: Catch Config Errors Before Deploy

Pourquoi `node:20-slim` et non `node:20` ou `node:20-alpine`

`npm ci` vs `npm install`

L'instruction `.dockerignore`