Guide de contribution Docker

​

Prérequis

​

Référence rapide

# Build toutes les images
docker compose build

# Build un seul service
docker compose build platform

# Smoke tests conteneurs (ports non conflictuels)
bun run docker:test

# Validation d'image (pas de secrets, labels OCI, budgets de taille)
bun run docker:test:image

# Scan de vulnérabilités (nécessite Trivy)
bun run docker:test:vulnerability

# Développement local avec hot-reload
docker compose -f compose.yml -f compose.dev.yml up --build

​

Conventions Dockerfile

​

Multi-stage builds

1. Stage builder — installer toutes les deps de build, compiler les paquets natifs.
2. Stage runtime — copier uniquement les artefacts runtime dans une image base propre.
3. Stage squash — FROM scratch + COPY --from=runtime / / pour aplatir les layers.

Important : Avec FROM scratch, toutes les ENV des stages précédents sont perdues et doivent être redéclarées. Les mountpoints de volume doivent aussi être pré-créés dans le stage runtime avant le squash.

​

Cache de layers

# Bon : les deps changent moins souvent que le code app
COPY pyproject.toml .
RUN uv pip install --system --no-cache-dir .
COPY app/ ./app/

​

Flags no-cache

RUN apt-get update && apt-get install -y --no-install-recommends curl \
    && rm -rf /var/lib/apt/lists/*
RUN uv pip install --system --no-cache-dir .

​

Labels OCI

ARG VERSION=dev
LABEL org.opencontainers.image.version="${VERSION}"

​

Health checks

HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
    CMD curl -f http://localhost:8001/health || exit 1

​

Budgets de taille d’image

​

Causes courantes d’augmentation

1. Nouvelle dépendance Python — vérifie si elle tire de grosses deps transitives.
2. Nouveaux paquets apt — utiliser --no-install-recommends et nettoyer après.
3. Strip oublié dans builder — retirer __pycache__, .pyc, répertoires de test, symboles debug .so.
4. Pas de multi-stage — les outils de build doivent rester en stage builder.

​

Réduire la taille

# Voir ce qui prend de la place
docker run --rm -it <image> du -sh /* 2>/dev/null | sort -rh | head -20

# Vérifier les paquets Python
docker run --rm <image> pip list 2>/dev/null || \
docker run --rm <image> python -c "import pkg_resources; [print(f'{p.key}: {p.location}') for p in pkg_resources.working_set]"

# Dive : analyse visuelle des layers
# Installer : https://github.com/wagoodman/dive
dive <image>

​

Workflow de test

​

1. Build et smoke test

bun run docker:test

• build les 5 images ;
• démarre les services sur des ports non conflictuels (15432, 18001, 18002, etc.) ;
• attend les health checks ;
• valide les endpoints HTTP ;
• teste la connectivité inter-services ;
• tear down tout (y compris les volumes).

​

2. Validation d’image

bun run docker:test:image

• label OCI org.opencontainers.image.version ;
• user non-root (requis pour platform) ;
• pas de secrets embarqués dans l’env ou le filesystem ;
• instruction HEALTHCHECK présente ;
• taille dans le budget.

​

3. Scan de vulnérabilités

bun run docker:test:vulnerability

CVE-2023-12345    # false positive: function not reachable

​

Pipeline CI/CD

​

Sur les pull requests (build.yml)

​

Sur les tags de release (release.yml)

​

Pièges courants

​

”parent snapshot does not exist”

docker builder prune -f

​

Port déjà utilisé

docker compose -f compose.yml -f compose.test.yml --env-file .env.test -p tale-test up -d

​

Paquet Python introuvable à l’exécution

1. Que tu copies depuis le bon chemin : COPY --from=builder /usr/local/lib/python3.11/site-packages ....
2. Que .dist-info du paquet n’est pas supprimé si quelque chose dépend des métadonnées à l’exécution.
3. Que le strip ne retire pas des .so requis.

​

Module Node.js introuvable à l’exécution

1. S’il est listé en dependencies (pas devDependencies) dans package.json.
2. Si le pruner le retire explicitement dans son rm -rf.