Méthodes de build

Kuploy propose plusieurs façons de transformer votre application en image de conteneur déployable. Choisissez celle qui correspond le mieux à votre projet.

Vue d'ensemble

Méthode	Pour quels projets	Configuration
Nixpacks	La plupart des applications	Aucune (détection automatique)
Dockerfile	Besoins particuliers	Vous fournissez le Dockerfile
Buildpacks	Une expérience à la Heroku	Minimale
Static	Sites HTML/CSS/JS	Aucune

Registre de conteneurs (indispensable pour builder)

Toute méthode de build — sauf le déploiement d'une image Docker déjà construite — produit une image de conteneur qui doit être poussée dans un registre avant que Kuploy puisse l'exécuter sur le cluster. Il n'existe aucun registre intégré par défaut : vous en fournissez un, et vous le rattachez à chaque service.

La configuration se fait en deux temps, et c'est l'oubli du second qui explique le plus souvent l'erreur Registry required ou Registry is required for Kubernetes builds au déploiement :

1. Déclarer un registre sur la plateforme — Settings → Registry → Add Registry. Renseignez :

   • Registry Name — le libellé de votre choix (par exemple kuploy)
   • Username / Password — les identifiants du registre (pour un compte robot Harbor, cela ressemble à robot$projet+nom)
   • Registry URL — le nom d'hôte seul, sans https:// ni chemin (par exemple registry.example.com)
   • Image Prefix — facultatif : l'espace de noms sous lequel les images sont poussées (par exemple kuploy)

   Servez-vous de Test Registry pour vérifier les identifiants avant d'enregistrer.

2. Rattacher le registre au service — ouvrez l'application, allez dans l'onglet Advanced → Build Registry, choisissez le registre que vous venez d'ajouter, puis Save.

Déclarer un registre ne suffit pas : il faut le rattacher à chaque service

Un registre ajouté dans Settings → Registry n'est qu'un identifiant que la plateforme connaît. Les builds poussent vers le registre rattaché au service (Advanced → Build Registry). Un service sans registre de build échoue au déploiement avec « Registry required », même si un registre existe bien dans les réglages. Rattachez-le à chaque application construite depuis Git — y compris à chaque composant d'une Stack.

Modifier le mot de passe d'un registre

Par sécurité, le mot de passe enregistré n'est jamais renvoyé au navigateur : le champ Password est donc vide quand vous modifiez un registre existant. Laissez-le vide pour conserver le mot de passe actuel ; ne saisissez une valeur que pour le changer (ou pour utiliser Test Registry, qui a besoin des identifiants réels).

Nixpacks (recommandé)

Nixpacks détecte seul votre langage et votre framework, installe les dépendances et construit une image de conteneur optimisée — sans aucune configuration pour la plupart des projets.

Langages pris en charge

• Node.js / JavaScript / TypeScript
• Python
• Go
• Rust
• Ruby
• PHP
• Java / Kotlin / Scala
• .NET / C# / F#
• Elixir
• Haskell
• Swift
• Zig
• et d'autres encore

Comment ça marche

1. Nixpacks analyse votre dépôt
2. Il reconnaît le langage et le framework (Next.js, Django, Rails…)
3. Il en déduit un plan de build optimisé
4. Il construit et met en cache les dépendances
5. Il produit une image de conteneur minimale

Personnalisation

Vous pouvez ajuster le build avec un fichier nixpacks.toml :

[phases.setup]
nixPkgs = ["...", "ffmpeg"]   # Ajouter des paquets système

[phases.build]
cmds = ["npm run build"]       # Commande de build personnalisée

[start]
cmd = "npm start"              # Commande de démarrage personnalisée

Ou passer par des variables d'environnement :

NIXPACKS_BUILD_CMD=npm run build
NIXPACKS_START_CMD=npm start
NIXPACKS_PKGS=ffmpeg,imagemagick

Quand l'utiliser

• Pour une application web classique, dans n'importe quel langage pris en charge
• Pour un projet qui suit une arborescence conventionnelle
• Quand vous voulez le chemin le plus court entre le code et le conteneur

Dockerfile

Fournissez votre propre Dockerfile quand vous avez besoin de maîtriser entièrement la construction.

Mise en place

1. Choisissez Dockerfile comme méthode de build dans les réglages de l'application
2. Indiquez le chemin du Dockerfile (par défaut : Dockerfile)
3. Précisez éventuellement le répertoire de contexte
4. Précisez éventuellement un Docker Build Stage pour cibler une étape d'un Dockerfile multi-étapes (vide = la dernière étape)

Déployer depuis un sous-répertoire (monorepo, dépôt d'exemples)

Lorsque vous renseignez un Build Path dans la section Provider (par exemple django-postgres), les champs Docker File et Docker Context Path sont résolus relativement à ce chemin. Le champ Docker File est obligatoire : pour un Dockerfile à la racine du sous-répertoire, saisissez Dockerfile (et non django-postgres/Dockerfile). Vous pouvez laisser Docker Context Path vide : il prend par défaut le répertoire du Dockerfile. C'est ainsi que se construisent les applications du dépôt kuploy/examples.

Exemple : Node.js

FROM node:20-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

EXPOSE 3000
CMD ["npm", "start"]

Exemple : Python

FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

EXPOSE 8000
CMD ["gunicorn", "app:app", "--bind", "0.0.0.0:8000"]

Builds multi-étapes

Les builds multi-étapes permettent de réduire la taille de l'image :

# Étape de construction
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Étape de production
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/index.js"]

Quand l'utiliser

• Vous avez besoin de dépendances système précises
• Vous construisez en plusieurs étapes
• Vous voulez maîtriser finement l'environnement du conteneur
• Votre projet a une arborescence inhabituelle

Buildpacks

Les Cloud Native Buildpacks offrent une expérience de build proche de celle de Heroku.

Mise en place

1. Choisissez Buildpacks comme méthode de build
2. Sélectionnez un fournisseur :
   • Heroku — le plus compatible avec des applications Heroku existantes
   • Paketo — moderne, activement maintenu
   • Google — orienté GCP

Procfile

Les buildpacks s'appuient sur un Procfile pour connaître la commande de démarrage :

web: npm start
worker: node worker.js

Quand l'utiliser

• Vous migrez depuis Heroku
• Vous travaillez déjà avec un Procfile
• Vous voulez des builds automatisés sans passer par Nixpacks

Sites statiques

Pour un site HTML/CSS/JS statique, Kuploy sert les fichiers directement, sans aucune étape de build.

Choisissez Static comme méthode de build et indiquez :

• Publish directory — le dossier qui contient vos fichiers statiques (dist, build, public…)

Sites générés par un framework

Pour les frameworks qui produisent un rendu statique (Vite, l'export statique de Next.js, Hugo…), construisez avec Nixpacks ou un Dockerfile, puis servez le résultat.

Conseils de build

Gardez un contexte de build réduit

Le contexte de build, c'est l'ensemble des fichiers envoyés au système de construction. Plus il est petit, plus le build est rapide et moins il consomme de minutes.

Placez un fichier .dockerignore à la racine de votre dépôt pour écarter ce qui ne sert pas au build :

# Dépendances (réinstallées pendant le build)
node_modules/
vendor/
.venv/
__pycache__/

# Résultats de build (régénérés pendant le build)
.next/
dist/
build/
out/

# Fichiers de développement
.git/
.env
.env.*
*.md
LICENSE
.vscode/
.idea/

# Tests et intégration continue
coverage/
.nyc_output/
__tests__/
*.test.*
*.spec.*
.github/

astuce

Les builds Nixpacks écartent déjà d'office les répertoires courants — node_modules, .next, dist, .cache, vendor — même sans .dockerignore. Pour un build par Dockerfile, en revanche, créez-en toujours un.

attention

Un contexte très volumineux (beaucoup de gros fichiers, des binaires versionnés…) ralentit le démarrage du build et peut le faire expirer. Si votre dépôt contient de gros fichiers, écartez-les via .dockerignore ou stockez-les ailleurs (dans du stockage objet, par exemple).

Minutes de build

Le temps de build est décompté des minutes de build de votre offre. Pour le réduire :

• utilisez un .dockerignore (voir ci-dessus) ;
• profitez du cache de couches : placez l'installation des dépendances (npm ci, pip install) avant la copie du code applicatif ;
• construisez en plusieurs étapes pour alléger l'image finale ;
• une image Docker déjà construite, déployée depuis un tag existant, ne consomme aucune minute de build.

Variables d'environnement au build

Les variables cochées Available at build time sont injectées pendant la construction. Voir Variables d'environnement.

Dépannage des builds

Symptôme	Cause probable	Solution
Le build démarre lentement	Contexte de build trop gros	Ajoutez un .dockerignore écartant node_modules, .git, etc.
Le build expire	Construction complexe ou envoi d'une image volumineuse	Simplifiez le Dockerfile, passez en multi-étapes, vérifiez votre réseau
« Dockerfile not found »	Mauvais chemin configuré	Vérifiez Dockerfile Path dans les réglages de l'application
Le build réussit mais l'application ne démarre pas	Mauvaise commande de démarrage ou mauvais port	Vérifiez CMD/ENTRYPOINT et la configuration du port
Nixpacks se trompe de langage	Arborescence ambiguë	Ajoutez un nixpacks.toml avec une configuration explicite