Aller au contenu

TP : Conteneurisation de votre application Node.js et intégration dans GitLab CI

Ce TP a pour objectif de vous faire pratiquer la création d'images Docker pour une application Node.js et l'automatisation de sa construction dans GitLab CI

Objectifs du TP

  • Rédiger un Dockerfile pour une application Node.js
  • Optimiser une image Docker avec le multi-stage build
  • Construire une image dans GitLab CI avec BuildKit en mode rootless, sans démon Docker
  • Accélérer les builds avec un cache distant stocké dans le registre
  • Automatiser la création et la publication de l'image dans le pipeline CI

Étape 1 : Création du Dockerfile basique

Nous allons créer une image Docker pour l'application Node.js développée au TP précédent

  1. À la racine de votre projet, créez un fichier nommé Dockerfile
  2. Utilisez l'image de base node:24-alpine (plus légère que l'image node standard)
  3. Définissez le répertoire de travail dans le conteneur avec WORKDIR (par exemple /usr/src/app)
  4. Copiez les fichiers package.json et package-lock.json ou yarn.lock
  5. Exécutez la commande d'installation des dépendances avec RUN npm ci
  6. Copiez le reste de votre code source dans le conteneur
  7. Exposez le port 3000 utilisé par votre application avec EXPOSE
  8. Définissez la commande de démarrage de votre application avec CMD
  9. N'oubliez pas d'ajouter un fichier .dockerignore contenant node_modules et .git pour ne pas alourdir le contexte de build

Étape 2 : Test de l'image localement (Optionnel)

Si vous disposez de Docker sur votre machine, vous pouvez vérifier que l'image se construit correctement avant de l'envoyer sur GitLab

  1. Construisez votre image en lui donnant un nom avec la commande docker build -t mon-app-node .
  2. Lancez un conteneur à partir de cette image avec docker run -p 3000:3000 mon-app-node
  3. Vérifiez dans votre navigateur que l'application répond sur http://localhost:3000

Étape 3 : Optimisation avec le Multi-stage Build

Pour avoir une image de production la plus légère possible, nous allons séparer l'étape de build de l'étape d'exécution

  1. Modifiez votre Dockerfile pour introduire une première étape nommée builder (ex: FROM node:24-alpine AS builder)
  2. Dans cette étape builder, installez toutes les dépendances et générez les fichiers nécessaires au bon fonctionnement de votre application
  3. Créez une seconde étape en utilisant à nouveau node:24-alpine
  4. Définissez la variable d'environnement NODE_ENV à production
  5. Utilisez l'instruction COPY --from=builder pour ne récupérer que le code compilé et les dossiers nécessaires depuis l'étape précédente
  6. Pour des raisons de sécurité (principe du moindre privilège), configurez le conteneur pour s'exécuter en tant qu'utilisateur non-privilégié en ajoutant la directive USER node juste avant l'instruction CMD (l'utilisateur node est déjà présent dans les images officielles node, y compris les variantes Alpine)
  7. Observez la réduction de taille de l'image finale si vous la buildez localement

Étape 4 : Automatisation de la construction de l'image sur GitLab CI

Maintenant que le Dockerfile est prêt, nous allons demander à GitLab CI de construire notre image Docker à chaque modification du code

Nous utiliserons BuildKit, le moteur de build de Docker, en mode rootless : aucun démon Docker à lancer, et un build qui s'exécute en utilisateur non-root

  1. Dans votre fichier .gitlab-ci.yml, ajoutez une étape build_image à vos stages existants
  2. Créez un job build:image rattaché à cette nouvelle étape
  3. Utilisez l'image moby/buildkit:v0.34.0-rootless avec l'entrypoint vide [""]
  4. Définissez la variable BUILDKITD_FLAGS à --oci-worker-no-process-sandbox
  5. Dans le before_script, créez le fichier d'authentification ~/.docker/config.json à partir des variables prédéfinies du registre GitLab :

    mkdir -p ~/.docker
    echo "{\"auths\":{\"$CI_REGISTRY\":{\"auth\":\"$(printf '%s:%s' "$CI_REGISTRY_USER" "$CI_REGISTRY_PASSWORD" | base64 | tr -d '\n')\"}}}" > ~/.docker/config.json
    
  6. Dans le script, lancez le build et le push sans démon avec buildctl-daemonless.sh :

    buildctl-daemonless.sh build \
      --frontend dockerfile.v0 \
      --local context=. \
      --local dockerfile=. \
      --output type=image,name=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA,push=true
    
  7. Commitez vos changements et vérifiez dans l'interface GitLab que le pipeline réussit et que l'image est bien présente dans Deploy > Container Registry

Rootless ne veut pas dire sans aucun droit

BuildKit rootless crée un user namespace, ce que le profil seccomp par défaut de Docker interdit. Les runners hébergés de GitLab.com autorisent le mode privilégié (c'est ce qui permet d'y faire du Docker-in-Docker) : le job fonctionne tel quel. Sur un runner auto-hébergé non privilégié, le conteneur de build doit tourner avec seccomp et AppArmor en unconfined, sinon le job échoue avec rootlesskit ... operation not permitted

Et Kaniko ?

Kaniko (GoogleContainerTools), longtemps l'outil de référence pour builder sans démon, est archivé depuis juin 2025. Un fork communautaire maintenu existe : vous pourrez le comparer à BuildKit dans le bonus de l'étape 8

Pour aller plus loin

Plutôt qu'un BuildKit lancé à chaque job, un service BuildKit peut tourner en permanence dans Kubernetes et être appelé par les jobs via Buildx : voir l'article optimiser les builds Docker sur Kubernetes avec BuildKit

Étape 5 : Validation de la qualité et de la sécurité (Linting)

Pour garantir la qualité et la sécurité de notre Dockerfile dans un cadre industriel, nous allons ajouter une étape de validation automatique dans notre pipeline CI. Trois approches courantes sont possibles (vous pouvez choisir l'une d'entre elles) :

Option A : Hadolint (Linter historique et spécialisé)

  1. Dans votre .gitlab-ci.yml, ajoutez une étape lint au tout début de vos stages existants
  2. Créez un job nommé lint_hadolint rattaché à cette étape
  3. Utilisez l'image officielle hadolint/hadolint:v2.15.1-alpine
  4. Dans la section script, lancez la commande hadolint Dockerfile

Option B : Trivy (Scanner de vulnérabilités et de conformité)

Trivy permet de scanner le Dockerfile pour y détecter des failles de sécurité ou des non-conformités

  1. Créez un job nommé lint_trivy rattaché à l'étape lint
  2. Utilisez l'image aquasec/trivy:0.76.0 avec l'entrypoint vide [""] (l'image définit trivy comme entrypoint)
  3. Dans la section script, lancez la commande trivy config Dockerfile (ou trivy config . pour scanner tout le projet)

Épinglez la version de Trivy

En mars 2026, l'écosystème Trivy a subi une attaque supply chain : des images vérolées ont été publiées sous les tags 0.69.4, 0.69.5, 0.69.6 et latest (détails sur le blog Docker). N'utilisez jamais latest pour un outil de sécurité : épinglez une version vérifiée, idéalement par digest (aquasec/trivy:<version>@sha256:<digest>)

Option C : Docker build --check (Validation native)

Docker permet de vérifier la syntaxe et le respect des bonnes pratiques directement via la CLI sans construire l'image

  1. Créez un job nommé lint_docker_check rattaché à l'étape lint
  2. Utilisez l'image docker:29 avec le service docker:29-dind
  3. Définissez les variables DOCKER_HOST à tcp://docker:2375 et DOCKER_TLS_CERTDIR à "" (TLS désactivé, comme dans les slides)
  4. Dans la section script, lancez la commande docker build --check .

Exercice : Choisissez et configurez l'une des méthodes ci-dessus, puis poussez vos modifications et vérifiez le résultat dans GitLab CI. Si des alertes sont remontées, corrigez votre Dockerfile en conséquence

Étape 6 : Cache distant BuildKit et stratégie de Tagging

Dans un contexte professionnel, il est crucial de réduire le temps d'exécution des pipelines et d'adopter un nommage clair et structuré de nos images Docker. Les runners étant éphémères, chaque job repart sans aucune couche en cache : on stocke donc le cache dans le registre

  1. Ajoutez à votre commande buildctl l'export et l'import du cache dans le registre GitLab :

      --export-cache type=registry,ref=$CI_REGISTRY_IMAGE:buildcache,mode=max \
      --import-cache type=registry,ref=$CI_REGISTRY_IMAGE:buildcache
    
  2. Lancez le pipeline deux fois de suite sans modifier le Dockerfile : au second passage, les étapes apparaissent en CACHED dans les logs et le job est plus rapide. Au tout premier build, une erreur sur l'import du cache est normale et ne fait pas échouer le job : le cache n'existe pas encore

  3. Poussez deux tags à chaque build : l'image avec le SHA court du commit ($CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA) et une image avec le nom de la branche ($CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG). Avec buildctl, les noms se séparent par une virgule dans name=, entre guillemets échappés :

      --output "type=image,\"name=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA,$CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG\",push=true"
    
  4. Optionnel : Ajoutez une règle de pipeline (rules) pour que l'image soit tagguée avec la version de la release ($CI_REGISTRY_IMAGE:$CI_COMMIT_TAG) uniquement lorsqu'un tag Git (ex: v1.0.0) est créé

Le même cache avec Docker Buildx

--export-cache et --import-cache sont les options de buildctl. Avec docker buildx build, le même mécanisme s'écrit --cache-to type=registry,ref=...,mode=max et --cache-from type=registry,ref=...

Étape 7 : Publication sur un registre externe privé (Docker Hub)

Dans de nombreux projets industriels, les images ne sont pas stockées sur le registre GitLab intégré, mais sur un registre externe d'entreprise (Docker Hub, Harbor, AWS ECR, etc.). Nous allons configurer notre pipeline pour pousser sur Docker Hub

  1. Créez un compte gratuit sur Docker Hub si vous n'en avez pas déjà un
  2. Générez un jeton d'accès personnel (Personal Access Token - PAT) dans les paramètres de votre compte Docker Hub (Account settings > Personal access tokens)
  3. Dans GitLab, allez dans Settings > CI/CD > Variables et ajoutez deux variables masquées :
    • DOCKER_HUB_USER : Votre nom d'utilisateur Docker Hub
    • DOCKER_HUB_TOKEN : Le jeton d'accès généré (ne jamais utiliser votre mot de passe en clair dans la CI)
  4. Ajoutez une seconde entrée dans le fichier ~/.docker/config.json de votre job BuildKit pour Docker Hub (l'URL du registre par défaut est https://index.docker.io/v1/) : un même fichier peut contenir plusieurs registres dans auths, ce qui permet de garder le cache sur le registre GitLab
  5. Modifiez le nom de l'image dans --output pour cibler votre dépôt Docker Hub : docker.io/<votre_utilisateur_dockerhub>/<nom_du_depot>:$CI_COMMIT_SHORT_SHA
  6. Lancez le pipeline et vérifiez que l'image est bien présente sur votre compte Docker Hub

Étape 8 : Bonus - Comparer avec d'autres outils de build

Pour élargir votre culture outillage, configurez un job de build avec l'une des alternatives suivantes, puis comparez-la à BuildKit : temps de build, simplicité de configuration, droits nécessaires sur le runner

Option A : Utilisation de Buildah

  1. Créez un job build_buildah dans votre .gitlab-ci.yml
  2. Utilisez l'image quay.io/buildah/stable:v1.43
  3. Définissez la variable STORAGE_DRIVER à vfs (Buildah ne peut pas empiler son overlayfs sur celui du conteneur)
  4. Dans la section script, connectez-vous au registre GitLab avec echo "$CI_REGISTRY_PASSWORD" | buildah login -u "$CI_REGISTRY_USER" --password-stdin $CI_REGISTRY
  5. Lancez la construction de l'image avec buildah build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA . (buildah bud en est l'ancien alias)
  6. Poussez l'image avec buildah push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA

Option B : Utilisation de Kaniko via son fork maintenu

Kaniko, archivé par Google en juin 2025, est repris par la communauté dans le fork osscontainertools/kaniko, qui maintient les dépendances à jour, corrige les bugs et publie des images publiques

  1. Créez un job build_kaniko dans votre .gitlab-ci.yml
  2. Utilisez l'image ghcr.io/osscontainertools/kaniko:v1.29.0-debug avec l'entrypoint vide [""] (la variante debug contient un shell, indispensable pour GitLab CI ; la même image est publiée sur Docker Hub sous martizih/kaniko)
  3. Créez le fichier d'authentification /kaniko/.docker/config.json, avec le même contenu que pour BuildKit
  4. Lancez la construction et le push avec /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile --destination $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA-kaniko
  5. Activez le cache avec --cache=true --cache-repo=$CI_REGISTRY_IMAGE/kaniko-cache et comparez les temps de build avec ceux de BuildKit

Et le fork de Chainguard ?

Chainguard maintient aussi un fork (chainguard-dev/kaniko), mais ne publie aucune image de conteneur publique : ses images sont réservées à ses clients, sinon il faut les construire soi-même depuis les sources

Option C : Utilisation de Cloud Native Buildpacks (Zéro Dockerfile)

Les Buildpacks permettent de construire une image sans écrire ni maintenir de Dockerfile, en détectant automatiquement la pile technologique (Node.js)

  1. Créez un job build_buildpack dans votre .gitlab-ci.yml
  2. Utilisez l'image buildpacksio/pack:0.40.9-base avec l'entrypoint vide [""] (la variante par défaut est distroless, sans shell) et déclarez le service docker:29-dind (la CLI pack a besoin d'un démon Docker pour lancer le build)
  3. Définissez les variables DOCKER_HOST à tcp://docker:2375 et DOCKER_TLS_CERTDIR à ""
  4. Configurez le fichier d'authentification ~/.docker/config.json avec vos identifiants de registre (l'image ne contient pas la CLI docker, pack lit directement ce fichier)
  5. Lancez la construction et la publication automatique avec la commande : pack build $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA --builder paketobuildpacks/builder-jammy-base --publish