À propos de ce cours
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.
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
buildinstalle 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 quepackage.json,node_modulesetdist: ni code source, ni TypeScript, ni CLI. - L'ordre des instructions compte:
package.jsonetpackage-lock.jsonsont copiés et installés avant le reste du code. Tant qu'ils ne changent pas, Docker réutilise la couchenpm cien 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 droitsrootdans le conteneur.HEALTHCHECK: Docker interroge/api/santetoutes les 30 secondes et marque le conteneurhealthyouunhealthy. On utilisefetch, intégré à Node.js 24 : inutile d'installer curl dans l'image.CMDsous forme de tableau :nodeest 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-feuufw.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.shest 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 par127.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
| Commande | Rôle |
|---|---|
docker compose up -d --build | construire si besoin et démarrer en arrière-plan |
docker compose ps | état et santé des conteneurs |
docker compose logs -f api | journaux en direct |
docker compose exec api sh | ouvrir un terminal dans le conteneur |
docker compose down | arrêter et supprimer les conteneurs (les volumes restent) |
docker image prune | supprimer 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*.jsonavant le code,USER node,HEALTHCHECK,CMD ["node", …]. .dockerignore: jamais denode_modulesni de.envdans l'image.- Compose :
DB_HOTE=db,depends_on … service_healthy, port publié sur127.0.0.1,restart: unless-stopped. docker compose exec api npm run migration:run;downgarde les volumes,down -vles efface.
Cet article vous a-t-il aidé ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !