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

```bash
# 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)

```bash
# 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
```bash
cd backend
docker build -f Dockerfile.base -t audio-classifier-base:local .
```

### Build de l'image app (utilise l'image de base)
```bash
# 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 :
```bash
# 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`**
   ```bash
   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 :
   ```bash
   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é :
```yaml
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`.