Build — du code à l'image Docker

📍 Où trouver ça dans l'UI — Infra → onglet Builds (liste globale de tous les builds de l'app)

C'est quoi un Build ? L'opération qui prend ton code Git et en fait une image Docker — un paquet exécutable et reproductible que K8s peut lancer.

Le pipeline d'un Build

textCopier
Repository (code source)
     ↓
   git checkout <branch / tag / commit>
     ↓
   docker build (Dockerfile)
     ↓
   Image Docker dans le registry privé Wakastart
     ↓
   Disponible pour déploiement

Statuts d'un build

Comment déclencher un build

Une fois SUCCEEDED, l'image est disponible : tu peux la déployer dans un environnement via une ServiceInstance.

Nom des images

Chaque build produit une image au nom unique. La date et l'heure sont en UTC.

• <sha7> : les 7 premiers caractères du commit.
• Un build de commit qui n'est rattaché à aucune branche commence par commit : commit-20261009-143012-3f9a2c1.
• Le nom de la branche est mis en minuscules, et les caractères non autorisés sont remplacés par - : feature/Login donne feature-login.
• Le tag git garde sa casse : seuls les caractères interdits dans un tag Docker sont remplacés par -, et les . ou - en tête sont retirés. release/V1.0 donne release-V1.0.
• C'est toujours Wakastart qui choisit le nom. Un nom d'image envoyé par l'API à la création du build est ignoré.

Cache de build

Chaque build repart de zéro : la plateforme ne réutilise aucune couche d'un build précédent. Il n'y a plus d'option « Sans cache ».

Le champ noCache est encore accepté par l'API, pour ne pas casser les appels existants, mais il n'a plus d'effet.

Conservation des images (purge automatique)

Chaque build réussi laisse une image dans le registre de l'app. Sans purge, ces images s'accumulent. La purge automatique supprime les images des builds les plus anciens, en gardant toujours celles qui servent encore.

Activer la purge

La purge est désactivée par défaut. Elle se règle app par app :

1. Ouvre Infra → Builds, carte Purge automatique des builds.
2. Active Purge automatique.
3. Règle Builds gardés par branche : 10 par défaut, entre 3 et 500.
4. Clique sur Enregistrer, puis confirme.

Avant d'enregistrer, l'écran indique combien d'images partiraient à la prochaine purge avec la valeur saisie. C'est un maximum : au moment de la purge, d'autres images peuvent encore être épargnées.

Une confirmation t'est demandée quand tu actives la purge, et aussi quand tu baisses le nombre de builds gardés. Le bouton de confirmation ne devient actif qu'une fois calculé le nombre d'images concernées ; si ce calcul échoue, la fenêtre le signale et tu peux quand même confirmer.

Seuls les gestionnaires de l'app peuvent modifier ces réglages : par défaut, les profils qui ont déjà le droit de supprimer des builds. Les autres utilisateurs les voient sans pouvoir les changer.

Ce qui est gardé

Les builds sont rangés par groupe. Dans chaque groupe, les N plus récents sont gardés (N = le nombre choisi) :

Seuls les builds réussis sont concernés. Un build en cours ou en échec n'est jamais touché.

Ce qui n'est jamais supprimé

Même au-delà des N plus récents, une image est toujours gardée si :

• elle tourne dans un environnement de l'app ;
• elle a été déployée il y a moins de 90 jours, y compris l'image remplacée par ce déploiement (pour pouvoir revenir en arrière) ;
• elle est partagée avec un build gardé ;
• elle est utilisée par une tâche planifiée ;
• elle est encore référencée dans le cluster, par exemple dans l'historique d'un déploiement.

Dans le doute, rien n'est supprimé : si la plateforme ne peut pas vérifier ce qu'utilise le cluster, la purge de la nuit n'a pas lieu.

Quand et comment

• La purge passe chaque nuit à 03:30.
• Elle supprime 100 images au plus par nuit, pour toute la plateforme. Une première purge importante peut donc s'étaler sur plusieurs nuits.
• Une image supprimée ne peut pas être récupérée. Le build correspondant ne peut plus être déployé. Pour retrouver cette version, relance un build du même commit.
• La place n'est libérée qu'au nettoyage hebdomadaire du registre, le dimanche à 00:00 UTC. Le stockage affiché baisse donc au plus tard une semaine après la purge.
• La carte affiche la date de la dernière purge et le nombre d'images supprimées.

Purge en simulation

La plateforme peut faire tourner la purge en simulation. Dans ce cas, rien n'est supprimé : la purge calcule seulement les images qui seraient parties. La carte l'indique par un message qui commence par « La purge tourne actuellement en simulation », suivi de la date de la dernière simulation et du nombre d'images qui auraient été supprimées. « Dernière purge » ne concerne que les purges réelles. Ce message n'apparaît que si la purge est activée sur l'app. La purge traite au plus 100 images par nuit pour toute la plateforme : le nombre affiché peut donc être inférieur au total.

Badges de la liste des builds

Quota du registre

Un administrateur de la plateforme peut fixer un quota de stockage pour une app. Par défaut, il n'y en a pas.

La carte Registre

La carte Registre, en haut de Infra → Builds, affiche :

• le stockage occupé par les images de l'app, et la date du relevé ;
• s'il y a un quota : le stockage utilisé sur le quota, avec une jauge.

Le stockage est relevé toutes les 15 minutes, et après chaque build réussi.

Une alerte s'affiche à 80 % du quota. À 100 %, les nouveaux builds sont refusés.

Quand le quota est atteint

Wakastart refuse de lancer un nouveau build de l'app, qu'il soit lancé depuis la console, par l'API ou automatiquement. Le message est :

Quota du registre atteint : X Go utilisés sur Y Go. Libérez de la place (purge automatique, suppression de builds) ou demandez un relèvement du quota.

X est donné avec une décimale, séparée par un point (par exemple 41.2), et Y est un nombre entier de Go.

Par l'API, la réponse a le statut 409.

À savoir :

• Le quota est vérifié au lancement du build. Un build déjà lancé va jusqu'au bout, même s'il fait dépasser le quota.
• Déployer une image déjà construite reste possible.
• Rien n'est limité dans le registre lui-même : c'est Wakastart qui refuse de lancer le build.

Libérer de la place

Active la purge automatique (voir ci-dessus). Attention : la place d'une image purgée n'est libérée qu'au nettoyage hebdomadaire du registre, le dimanche à 00:00 UTC. D'ici là, le stockage affiché ne baisse pas et les nouveaux builds restent refusés.

Si tu ne peux pas attendre, demande à un administrateur de la plateforme de relever le quota.

Diagnostiquer un build en échec

Si un build Wakastart termine en FAILED, le premier réflexe est de reproduire l'erreur localement avec docker build. Le builder Wakastart exécute exactement la même commande que toi en local — si elle passe en local, elle passe sur la plateforme.

Pour un diagnostic fiable, cloner le repo dans un dossier neuf avant de lancer le build :

bashCopier
git clone <url-du-repo> /tmp/build-check
cd /tmp/build-check
git checkout <branche-ou-commit-qui-échoue>
docker build -f <dockerfilePath> <buildContext>

C'est important parce qu'un dépôt de travail contient typiquement des artefacts qui n'existent pas côté Wakastart et qui peuvent masquer l'erreur :

• un node_modules/ installé localement (et qui contredit ce que pnpm install produit dans le Dockerfile)
• un dossier dist/ ou .next/ issu d'un build précédent
• un fichier .env local qui injecte des variables manquantes côté plateforme
• des binaires Prisma générés (@prisma/client) qui pourraient compenser un prisma generate oublié dans le Dockerfile
• un lockfile désynchronisé (pnpm-lock.yaml modifié mais non commité)

Un build dans un repo fraîchement cloné reproduit exactement le contexte du builder Wakastart : seuls les fichiers versionnés sont présents, rien d'autre. Si l'erreur ne se reproduit pas dans ces conditions, c'est qu'elle vient d'un artefact local, pas du code committé.

💡 Un .dockerignore bien écrit (excluant node_modules, .next, dist, .env*) protège déjà contre la plupart des fuites d'artefacts vers le contexte Docker — mais ne dispense pas du test en repo neuf si un doute persiste.