Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Conteneuriser une application NestJS avec Docker et Docker Compose (API + MySQL)

Cette leçon conteneurise une API NestJS. Après les notions d'image, de conteneur, de volume et de réseau, elle écrit un Dockerfile en deux étapes (compilation puis exécution), avec un utilisateur non ...

0 chapitres 0 QCM Accès gratuit
Conteneuriser une application NestJS avec Docker et Docker Compose (API + MySQL)

À propos de ce cours

Cette leçon conteneurise une API NestJS. Après les notions d'image, de conteneur, de volume et de réseau, elle écrit un Dockerfile en deux étapes (compilation puis exécution), avec un utilisateur non root, un contrôle de santé et un .dockerignore, et montre le cache des couches sur de vraies compilations. Docker Compose démarre ensuite l'API et MariaDB ensemble : variables d'environnement, attente de la base en bonne santé, volume persistant vérifié après un arrêt, migrations et premier administrateur dans le conteneur, nginx devant. Activités corrigées.

Objectifs de la leçon

  • Comprendre image, conteneur, volume et réseau.
  • Écrire un Dockerfile multi-étapes efficace et sûr pour NestJS.
  • Démarrer l'API et MariaDB avec Docker Compose.
  • Conserver les données et administrer l'application dans les conteneurs.

Versions: NestJS 12.5 (projet CommonJS), Node.js 24, npm 11, PM2 7.1, nginx 1.24 (Ubuntu 24.04 LTS), Docker 29 avec Compose 5, MariaDB 10.11. Toutes les commandes de ce chapitre ont été réellement exécutées sur un serveur de test Ubuntu 24.04 (adresse 192.0.2.2, utilisateur deploy), avec le projet api-securisee du chapitre 19, complété pour la production. Les sorties sont reproduites telles quelles ; seuls les secrets sont masqués.

Environnement de test: le registre Docker Hub n'était pas joignable depuis le serveur de test. Les images de base node:24-slim et mariadb:10.11 y ont donc été reconstruites localement (Node.js 24 et MariaDB 10.11 sur Ubuntu 24.04), avec le même comportement que les images officielles pour ce qui est utilisé ici. Chez vous, docker build téléchargera les images officielles : les empreintes sha256, les durées et les tailles affichées seront différentes.

Pourquoi Docker ?

Dans la leçon 20.2, le serveur devait être préparé à la main : la bonne version de Node.js, MariaDB, les dossiers… Le jour où vous changez de serveur, ou si un collègue a Node.js 22 au lieu de 24, les différences apparaissent. Docker emballe l'application avec son environnement :

  • une image est un modèle en lecture seule : un système minimal, Node.js, le code compilé et ses dépendances. Elle se construit à partir d'un Dockerfile;
  • un conteneur est une image en cours d'exécution, isolée des autres ; on peut en lancer plusieurs à partir d'une image ;
  • un volume conserve des données en dehors du conteneur (la base) : supprimer le conteneur ne les efface pas ;
  • un réseau relie les conteneurs entre eux, qui se trouvent par leur nom.

Docker et Docker Compose

Le Dockerfile produit une image ; Docker Compose lance l'API et MariaDB sur un réseau privé, avec un volume.

Installation sur Ubuntu : curl -fsSL https://get.docker.com | sh (Docker Engine et le plugin Compose), puis usermod -aG docker deploy. Sous Windows et macOS : Docker Desktop.

Le Dockerfile

📄 Dockerfile

# ---------- Étape 1 : compilation (avec les outils de développement) ----------
FROM node:24-slim AS build
WORKDIR /app
# d'abord les fichiers de dépendances : cette couche reste en cache tant qu'ils ne changent pas
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --omit=dev

# ---------- Étape 2 : exécution (seulement le nécessaire) ----------
FROM node:24-slim
ENV NODE_ENV=production
WORKDIR /app
COPY --from=build --chown=node:node /app/package.json ./
COPY --from=build --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/dist ./dist
# ne jamais exécuter l'application en root
USER node
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --start-period=20s --retries=3 \
  CMD node -e "fetch('http://127.0.0.1:3000/api/sante').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"
CMD ["node", "--enable-source-maps", "dist/main.js"]
  • Deux étapes (multi-stage). L'étape build installe tout, compile, puis retire les dépendances de développement (npm prune --omit=dev). L'image finale repart d'une image propre et ne copie que package.json, node_modules et dist: ni code source, ni TypeScript, ni CLI.
  • L'ordre des instructions compte: package.json et package-lock.json sont copiés et installés avant le reste du code. Tant qu'ils ne changent pas, Docker réutilise la couche npm ci en cache.
  • node:24-slim (Debian allégée) plutôt qu'alpine: bcrypt est un module natif ; avec la bibliothèque C d'Alpine (musl), il faut parfois le recompiler.
  • USER node: l'utilisateur non privilégié fourni par l'image officielle. Une faille dans l'application ne donne pas les droits root dans le conteneur.
  • HEALTHCHECK: Docker interroge /api/sante toutes les 30 secondes et marque le conteneur healthy ou unhealthy. On utilise fetch, intégré à Node.js 24 : inutile d'installer curl dans l'image.
  • CMD sous forme de tableau : node est le processus principal (PID 1) et reçoit directement le signal d'arrêt de Docker ; enableShutdownHooks() (chapitre 19) ferme proprement les connexions.

📄 .dockerignore

node_modules
dist
coverage
.git
.env
.env.*
!.env.docker.example
*.log

Le .dockerignore évite d'envoyer à Docker le node_modules du poste (330 Mo, et compilé pour un autre système), dist, l'historique Git… et surtout les .env: un secret copié dans une image s'y retrouve pour toujours, chez quiconque récupère l'image.

Construire l'image

Résultat réellement obtenu :

$ docker build -t api-securisee:1.1.0 .
#1 [internal] load build definition from Dockerfile
#1 DONE 0.0s
#2 [internal] load metadata for docker.io/library/node:24-slim
#2 DONE 0.0s
#3 [internal] load .dockerignore
#3 DONE 0.0s
#4 [build 1/6] FROM docker.io/library/node:24-slim@sha256:80b636185ac0bdbdcb0796b31361e31fc77c2c94572bba39579bcf46e85fd8cf
#4 DONE 0.0s
#5 [internal] load build context
#5 DONE 0.0s
#6 [build 2/6] WORKDIR /app
#6 DONE 0.0s
#7 [build 3/6] COPY package.json package-lock.json ./
#7 DONE 0.0s
#8 [build 4/6] RUN npm ci
#8 15.55 added 657 packages, and audited 658 packages in 15s
#8 DONE 16.5s
#9 [build 5/6] COPY . .
#9 DONE 0.2s
#10 [build 6/6] RUN npm run build && npm prune --omit=dev
#10 11.99 removed 469 packages, and audited 189 packages in 7s
#10 DONE 12.1s
#11 [stage-1 3/5] COPY --from=build --chown=node:node /app/package.json ./
#11 DONE 0.1s
#12 [stage-1 4/5] COPY --from=build --chown=node:node /app/node_modules ./node_modules
#12 DONE 3.1s
#13 [stage-1 5/5] COPY --from=build --chown=node:node /app/dist ./dist
#13 DONE 0.1s
#14 naming to docker.io/library/api-securisee:1.1.0 done
#14 DONE 5.8s

La sortie complète contient aussi les messages de npm ; on voit ici les étapes. L'image ne contient que le nécessaire et s'exécute sous l'utilisateur node:

Résultat réellement obtenu :

$ docker run --rm api-securisee:1.1.0 id
uid=1000(node) gid=1000(node) groups=1000(node)
$ docker run --rm api-securisee:1.1.0 ls -A
dist
node_modules
package.json
$ docker run --rm api-securisee:1.1.0 node dist/main.js 2>&1 | head -5
[Nest] 1  - 11/15/2026, 7:25:13 PM     LOG [NestFactory] Starting Nest application...
[Nest] 1  - 11/15/2026, 7:25:13 PM   ERROR [ExceptionHandler] Error: Configuration invalide :
 - PORT must be an integer number
 - DB_HOTE must be a string
 - DB_PORT must be an integer number

Lancée sans aucune variable d'environnement, l'API refuse de démarrer et liste ce qui manque : c'est la validation de la configuration du chapitre 19. L'image ne contient aucune configuration ; on la fournit au lancement. Modifions maintenant un fichier de src et reconstruisons :

Résultat réellement obtenu :

$ docker build -t api-securisee:1.1.0 .     # après avoir modifié un fichier de src/
#1 [internal] load build definition from Dockerfile
#1 DONE 0.0s
#2 [internal] load metadata for docker.io/library/node:24-slim
#2 DONE 0.0s
#3 [internal] load .dockerignore
#3 DONE 0.0s
#4 [build 1/6] FROM docker.io/library/node:24-slim@sha256:80b636185ac0bdbdcb0796b31361e31fc77c2c94572bba39579bcf46e85fd8cf
#4 DONE 0.0s
#5 [internal] load build context
#5 DONE 0.0s
#6 [build 3/6] COPY package.json package-lock.json ./
#6 CACHED
#7 [build 2/6] WORKDIR /app
#7 CACHED
#8 [build 4/6] RUN npm ci
#8 CACHED
#9 [build 5/6] COPY . .
#9 DONE 0.0s
#10 [build 6/6] RUN npm run build && npm prune --omit=dev
#10 DONE 11.1s
#11 [stage-1 4/5] COPY --from=build --chown=node:node /app/node_modules ./node_modules
#11 CACHED
#12 [stage-1 3/5] COPY --from=build --chown=node:node /app/package.json ./
#12 CACHED
#13 [stage-1 5/5] COPY --from=build --chown=node:node /app/dist ./dist
#13 CACHED
#14 DONE 0.1s

Les couches de npm ci sont CACHED: seule la compilation est refaite. Dans ce cas précis, la modification était un commentaire, que la compilation supprime : le dist obtenu étant identique, Docker a même réutilisé les couches de l'image finale.

Docker Compose : l'API et la base ensemble

Lancer et relier plusieurs conteneurs à la main demande de longues commandes. Docker Compose décrit l'ensemble dans un fichier :

📄 docker-compose.yml

# docker compose up -d --build
name: api-securisee           # préfixe des conteneurs, du réseau et du volume
services:
  db:
    image: mariadb:10.11
    restart: unless-stopped
    env_file: .env.docker          # MARIADB_ROOT_PASSWORD, MARIADB_DATABASE, MARIADB_USER, MARIADB_PASSWORD
    volumes:
      - donnees-db:/var/lib/mysql  # les données survivent à la suppression du conteneur
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  api:
    build: .
    image: api-securisee:1.1.0
    restart: unless-stopped
    env_file: .env.docker
    environment:
      DB_HOTE: db                  # le nom du service = son nom d'hôte sur le réseau Compose
      HOTE: 0.0.0.0                # écouter sur toutes les interfaces du conteneur
    ports:
      - "127.0.0.1:3000:3000"      # publié pour nginx uniquement, pas pour Internet
    depends_on:
      db:
        condition: service_healthy # attendre que MariaDB soit prête

volumes:
  donnees-db:

📄 .env.docker.example

# Copier en .env.docker (jamais versionné) et remplacer les valeurs
# --- MariaDB (image officielle) ---
MARIADB_ROOT_PASSWORD=changer-ce-mot-de-passe-root
MARIADB_DATABASE=api_securisee
MARIADB_USER=api
MARIADB_PASSWORD=changer-ce-mot-de-passe
# --- API (mêmes valeurs que ci-dessus) ---
NODE_ENV=production
PORT=3000
DB_PORT=3306
DB_NOM=api_securisee
DB_UTILISATEUR=api
DB_MOT_DE_PASSE=changer-ce-mot-de-passe
JWT_SECRET=remplacer-par-au-moins-32-caracteres-aleatoires
CORS_ORIGINES=https://stagiaires.exemple.tn
# Docker : nginx (sur l hôte) arrive par le réseau privé de Docker
TRUST_PROXY=loopback,uniquelocal
LOG_FORMAT=json
LOG_NIVEAUX=log
  • name: préfixe des conteneurs, du réseau et du volume (sinon le nom du dossier).
  • Le réseau: Compose crée un réseau privé ; l'API joint la base par le nom de son service, db (DB_HOTE: db). La base n'a aucun port publié : elle est inaccessible depuis l'extérieur.
  • ports: "127.0.0.1:3000:3000": le port de l'API n'est publié que pour la machine elle-même (nginx). Écrire "3000:3000" l'ouvrirait sur Internet, et Docker contourne les règles du pare-feu ufw.
  • HOTE: 0.0.0.0: dans le conteneur, l'API doit écouter sur toutes les interfaces, sinon Docker ne peut pas lui transmettre les requêtes.
  • depends_on + condition: service_healthy: l'API ne démarre que lorsque le contrôle de santé de MariaDB réussit (healthcheck.sh est fourni par l'image officielle).
  • TRUST_PROXY=loopback,uniquelocal: nginx, installé sur la machine, atteint le conteneur par le réseau privé de Docker (adresse en 172.x), pas par 127.0.0.1.
  • restart: unless-stopped: Docker relance les conteneurs après un plantage ou un redémarrage du serveur ; PM2 n'est plus nécessaire.

Résultat réellement obtenu :

$ docker compose up -d --build
 Image api-securisee:1.1.0 Building 
 Image api-securisee:1.1.0 Built 
 Network api-securisee_default Creating 
 Network api-securisee_default Creating 
 Volume api-securisee_donnees-db Creating 
 Volume api-securisee_donnees-db Creating 
 Volume api-securisee_donnees-db Created 
 Volume api-securisee_donnees-db Created 
 Network api-securisee_default Created 
 Network api-securisee_default Created 
 Container api-securisee-db-1 Creating 
 Container api-securisee-db-1 Created 
 Container api-securisee-api-1 Creating 
 Container api-securisee-api-1 Created 
 Container api-securisee-db-1 Starting 
 Container api-securisee-db-1 Started 
 Container api-securisee-db-1 Waiting 
 Container api-securisee-db-1 Healthy 
 Container api-securisee-api-1 Starting 
 Container api-securisee-api-1 Started 
$ docker compose ps
NAME                  IMAGE                 COMMAND                  SERVICE   CREATED          STATUS                    PORTS
api-securisee-api-1   api-securisee:1.1.0   "node --enable-sourc…"   api       31 seconds ago   Up 25 seconds (healthy)   127.0.0.1:3000->3000/tcp
api-securisee-db-1    mariadb:10.11         "docker-entrypoint.sh"   db        31 seconds ago   Up 30 seconds (healthy)   3306/tcp
$ docker compose logs api --tail 3
api-1  | {"level":"log","pid":1,"timestamp":1794771412963,"message":"Nest application successfully started","context":"NestApplication"}
api-1  | {"level":"log","pid":1,"timestamp":1794771412964,"message":"API prête sur http://localhost:3000/api (production)","context":"Demarrage"}
api-1  | {"level":"log","pid":1,"timestamp":1794771417313,"message":"GET /api/sante 200 5ms","context":"HTTP","params":{"requete":"997776e2","ip":"127.0.0.1","utilisateur":null}}

Docker a attendu que la base soit Healthy avant de démarrer l'API ; les deux conteneurs sont en bonne santé. Comme en 20.1, il reste à créer le schéma et le premier administrateur, cette fois dans le conteneur de l'API avec docker compose exec:

Résultat réellement obtenu :

$ docker compose exec api npm run migration:run
> api-securisee@1.1.0 migration:run
> typeorm -d dist/data-source.js migration:run

0 migrations are already loaded in the database.
1 migrations were found in the source code.
1 migrations are new migrations must be executed.
Migration Initialisation1794763018768 has been executed successfully.
$ docker compose exec -e ADMIN_EMAIL=direction@exemple.tn -e ADMIN_MOT_DE_PASSE='Direction-2026-Prod' api npm run admin:creer
> api-securisee@1.1.0 admin:creer
> node dist/scripts/creer-admin.js

Compte administrateur direction@exemple.tn créé
$ curl -s -X POST http://127.0.0.1:3000/api/auth/connexion -H 'Content-Type: application/json' -d '{"email":"direction@exemple.tn","motDePasse":"Direction-2026-Prod"}' | cut -c1-60
{"jeton":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEsI
Les données survivent aux conteneurs

Résultat réellement obtenu :

$ docker compose down
 Container api-securisee-api-1 Stopping 
 Container api-securisee-api-1 Stopped 
 Container api-securisee-api-1 Removing 
 Container api-securisee-api-1 Removed 
 Container api-securisee-db-1 Stopping 
 Container api-securisee-db-1 Stopped 
 Container api-securisee-db-1 Removing 
 Container api-securisee-db-1 Removed 
 Network api-securisee_default Removing 
 Network api-securisee_default Removed 
$ docker volume ls --filter name=api-securisee
DRIVER    VOLUME NAME
local     api-securisee_donnees-db
$ docker compose up -d
 Network api-securisee_default Creating 
 Network api-securisee_default Creating 
 Network api-securisee_default Created 
 Network api-securisee_default Created 
 Container api-securisee-db-1 Creating 
 Container api-securisee-db-1 Created 
 Container api-securisee-api-1 Creating 
 Container api-securisee-api-1 Created 
 Container api-securisee-db-1 Starting 
 Container api-securisee-db-1 Started 
 Container api-securisee-db-1 Waiting 
 Container api-securisee-db-1 Healthy 
 Container api-securisee-api-1 Starting 
 Container api-securisee-api-1 Started 
$ curl -s -X POST http://127.0.0.1:3000/api/auth/connexion -H 'Content-Type: application/json' -d '{"email":"direction@exemple.tn","motDePasse":"Direction-2026-Prod"}' | cut -c1-60
{"jeton":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEsI

docker compose down supprime les conteneurs et le réseau, mais pas le volume : après up, l'administrateur existe toujours. Seul docker compose down -v supprime aussi les volumes, donc la base : à n'utiliser qu'en connaissance de cause. Sauvegardez régulièrement la base : docker compose exec db mariadb-dump -uroot -p"$MARIADB_ROOT_PASSWORD" api_securisee > sauvegarde.sql.

Et nginx ?

La configuration nginx de la leçon 20.2 ne change pas : elle transmet toujours à 127.0.0.1:3000, désormais publié par Docker. Le journal du conteneur reçoit bien l'adresse réelle du client :

Résultat réellement obtenu :

$ curl -sk --resolve api.exemple.tn:443:192.0.2.2 https://api.exemple.tn/api/demandes -o /dev/null -w "%{http_code}\n"
$ docker compose logs api --tail 1
401
api-1  | {"level":"warn","pid":1,"timestamp":1794771481856,"message":"GET /api/demandes 401 2ms","context":"HTTP","params":{"requete":"ab460644","ip":"192.0.2.2","utilisateur":null}}
Commandes utiles
CommandeRôle
docker compose up -d --buildconstruire si besoin et démarrer en arrière-plan
docker compose psétat et santé des conteneurs
docker compose logs -f apijournaux en direct
docker compose exec api shouvrir un terminal dans le conteneur
docker compose downarrêter et supprimer les conteneurs (les volumes restent)
docker image prunesupprimer les anciennes images inutilisées

Mise à jour sur le serveur : git pull, docker compose up -d --build, puis docker compose exec api npm run migration:run. Dans les entreprises, l'image est plutôt construite par la CI (leçon 20.4), publiée dans un registre (GitHub Container Registry, Docker Hub) et seulement téléchargée par le serveur.

Activités

Activité 1 Image ou conteneur ?

Vrai ou faux ? (a) Modifier un fichier dans un conteneur modifie l'image. (b) Deux conteneurs peuvent tourner à partir de la même image. (c) docker compose down efface la base de données. (d) Le .env doit être copié dans l'image pour que l'API le lise. (e) Le conteneur de l'API joint la base avec localhost.

Voir le corrigé

(a) Faux : l'image est en lecture seule ; la modification est perdue à la suppression du conteneur. (b) Vrai. (c) Faux : le volume est conservé (sauf avec -v). (d) Faux et dangereux : la configuration est fournie au lancement (env_file, environment). (e) Faux : localhost désigne le conteneur de l'API lui-même ; il faut le nom du service, db.

Activité 2 Optimiser l'ordre

Ce Dockerfile reconstruit toutes les dépendances à chaque modification du code. Pourquoi ? Corrigez-le.

FROM node:24-slim
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build
CMD ["npm", "run", "start:prod"]
Voir le corrigé

COPY . . avant l'installation : toute modification d'un fichier invalide le cache de cette couche et de toutes les suivantes. Il faut copier package*.json d'abord, puis npm ci, puis le code. Autres défauts : npm install au lieu de npm ci, dépendances de développement dans l'image finale (une seule étape), exécution en root, npm comme processus principal (il transmet mal les signaux d'arrêt), pas de .dockerignore. La correction est le Dockerfile de la leçon.

Activité 3 Conteneuriser votre API

Ajoutez à votre projet (TP 8 ou 9) un Dockerfile, un .dockerignore, un docker-compose.yml et un .env.docker.example. Vérifiez : santé des deux conteneurs, migrations, connexion, persistance après down/up. Le .env.docker ne doit pas être versionné.

Voir le corrigé

Ajoutez .env.docker au .gitignore et vérifiez avec git status avant le commit. Si l'API reste unhealthy, lisez docker compose logs api: souvent une variable manquante ou DB_HOTE=localhost. Si votre API sert des fichiers téléversés (chapitre 15), ajoutez un second volume pour le dossier d'upload. Commit : feat(docker): Dockerfile et Docker Compose.

Activité 4 Adminer pour le développement

Ajoutez au docker-compose.yml un service adminer (image adminer, interface web de base de données sur le port 8080), accessible seulement depuis votre machine, et connectez-vous à la base. Pourquoi ne faut-il pas le laisser en production ?

Voir le corrigé
  adminer:
    image: adminer
    ports:
      - "127.0.0.1:8080:8080"
    depends_on: [db]

Sur http://localhost:8080 : serveur db, utilisateur et mot de passe de .env.docker. En production, c'est une porte d'entrée supplémentaire vers toutes les données : on le met dans un fichier séparé (docker-compose.dev.yml, utilisé avec -f) ou on passe par un tunnel SSH.

À retenir

  • Image (modèle) → conteneur (exécution) ; volume pour les données ; réseau privé entre services.
  • Dockerfile en deux étapes, package*.json avant le code, USER node, HEALTHCHECK, CMD ["node", …].
  • .dockerignore: jamais de node_modules ni de .env dans l'image.
  • Compose : DB_HOTE=db, depends_on … service_healthy, port publié sur 127.0.0.1, restart: unless-stopped.
  • docker compose exec api npm run migration:run; down garde les volumes, down -v les efface.

Cet article vous a-t-il aidé ?