Audio-Classifier/backend/DOCKER_BUILD.md

Docker Build Optimization

Cette configuration utilise une approche en 2 images pour accélérer les builds backend de 15-25 minutes à 30 secondes - 2 minutes.

Architecture

Image 1 : Base (audio-classifier-base)

Contient toutes les dépendances système et Python qui changent rarement :

• Python 3.9 + apt packages (ffmpeg, libsndfile, etc.)
• numpy, scipy, essentia-tensorflow
• Toutes les dépendances de requirements.txt

Build : ~15 minutes (1 fois par semaine ou quand requirements.txt change)

Image 2 : App (audio-classifier-backend)

Hérite de l'image de base et ajoute uniquement le code applicatif :

• Code source (src/)
• Fichiers de configuration (alembic.ini)
• Modèles Essentia (models/)

Build : ~30 secondes - 2 minutes (à chaque commit)

Workflows CI/CD

1. Build de l'image de base (.gitea/workflows/docker-base.yml)

Se déclenche automatiquement quand :

• backend/requirements.txt est modifié
• backend/Dockerfile.base est modifié
• Déclenchement manuel via l'interface Gitea

# Image produite :
git.benoitsz.com/benoit/audio-classifier-base:latest
git.benoitsz.com/benoit/audio-classifier-base:sha-<commit>

2. Build de l'image app (.gitea/workflows/docker.yml)

Se déclenche à chaque push sur main :

• Utilise l'image de base comme FROM
• Copie uniquement le code source
• Build rapide (~30s-2min)

# Image produite :
git.benoitsz.com/benoit/audio-classifier-backend:dev
git.benoitsz.com/benoit/audio-classifier-backend:dev-<commit>

Utilisation en local

Build de l'image de base

cd backend
docker build -f Dockerfile.base -t audio-classifier-base:local .

Build de l'image app (utilise l'image de base)

# Depuis la racine du projet
docker build \
  --build-arg BASE_IMAGE=audio-classifier-base:local \
  -f backend/Dockerfile \
  -t audio-classifier-backend:local \
  .

Build direct (sans image de base) - pour tests

Si tu veux tester un build complet sans dépendre de l'image de base :

# Revenir temporairement au Dockerfile original
git show HEAD~1:backend/Dockerfile > backend/Dockerfile.monolithic
docker build -f backend/Dockerfile.monolithic -t audio-classifier-backend:monolithic .

Mise à jour des dépendances

Quand tu modifies requirements.txt :

1. Push les changements sur main

   git add backend/requirements.txt
   git commit -m "Update dependencies"
   git push
   

2. Le workflow docker-base.yml se déclenche automatiquement

   • Build de la nouvelle image de base (~15 min)
   • Push vers git.benoitsz.com/benoit/audio-classifier-base:latest

3. Les prochains builds backend utiliseront la nouvelle base

   • Builds futurs rapides (~30s-2min)

Déclenchement manuel

Pour rebuild l'image de base manuellement (sans modifier requirements.txt) :

1. Va sur Gitea : https://git.benoitsz.com/benoit/audio-classifier/actions
2. Sélectionne le workflow "Build Base Docker Image"
3. Clique sur "Run workflow"

Monitoring

Vérifie les builds dans Gitea Actions :

• Base image : .gitea/workflows/docker-base.yml
• App image : .gitea/workflows/docker.yml

Les logs montrent la durée de build pour chaque étape.

Gains de performance attendus

Scénario	Avant	Après	Gain
Build normal (code change)	15-25 min	30s-2min	90-95%
Build après update deps	15-25 min	15-25 min (base) + 30s-2min (app)	0% (1ère fois)
Builds suivants	15-25 min	30s-2min	90-95%

Troubleshooting

Erreur "base image not found"

L'image de base n'existe pas encore dans le registry. Solutions :

1. Trigger le workflow docker-base.yml manuellement
2. Ou build localement et push :

   docker build -f backend/Dockerfile.base -t git.benoitsz.com/benoit/audio-classifier-base:latest backend/
   docker push git.benoitsz.com/benoit/audio-classifier-base:latest
   

Build app lent malgré l'image de base

Vérifie que le build-arg BASE_IMAGE est bien passé :

build-args: |
  BASE_IMAGE=${{ env.REGISTRY }}/${{ gitea.repository_owner }}/audio-classifier-base:latest

Dépendances Python pas à jour dans l'app

L'image de base doit être rebuildée. Trigger docker-base.yml.