Audio-Classifier/DOCKER.md

Dockerisation du projet Audio Classifier

🐳 Architecture Docker

Le projet est entièrement dockerisé avec deux configurations distinctes :

1. Production (docker-compose.yml) - Version optimisée pour le déploiement
2. Développement (docker-compose.dev.yml) - Version avec hot-reload pour le développement

📁 Structure des Services

services:
  postgres:     # Base de données PostgreSQL avec pgvector
  backend:      # API FastAPI (Python 3.11)
  frontend:     # Interface Next.js (Node.js 20)

🚀 Commandes de déploiement

Mode Production

# Démarrer tous les services
docker-compose up -d

# Arrêter tous les services
docker-compose down

# Voir les logs
docker-compose logs

Mode Développement

# Démarrer tous les services en mode dev
docker-compose -f docker-compose.dev.yml up -d

# Arrêter tous les services
docker-compose -f docker-compose.dev.yml down

# Voir les logs
docker-compose -f docker-compose.dev.yml logs

🏗 Construction des images

Backend (Production)

• Base : python:3.9-slim (pour compatibilité Essentia)
• Dépendances système : ffmpeg, libsndfile, etc.
• Dépendances Python : Toutes les dépendances du fichier requirements.txt
• Optimisation : Multi-stage build pour réduire la taille

Backend (Développement)

• Base : python:3.11-slim
• Dépendances : Version minimale sans Essentia
• Hot-reload : Montage du code source pour développement

Frontend (Production)

• Base : node:20-alpine
• Build : Application Next.js compilée
• Optimisation : Image légère Alpine Linux

Frontend (Développement)

• Base : node:20-alpine
• Hot-reload : Montage du code source
• Dépendances : Installation des modules Node

⚙️ Configuration des environnements

Variables d'environnement

Les variables sont définies dans les fichiers .env et peuvent être surchargées :

Base de données :

• POSTGRES_USER - Utilisateur PostgreSQL
• POSTGRES_PASSWORD - Mot de passe PostgreSQL
• POSTGRES_DB - Nom de la base de données
• DATABASE_URL - URL de connexion complète

Backend :

• CORS_ORIGINS - Origines autorisées pour CORS
• ANALYSIS_USE_CLAP - Activation des embeddings CLAP
• ANALYSIS_NUM_WORKERS - Nombre de workers d'analyse
• ESSENTIA_MODELS_PATH - Chemin vers les modèles Essentia

Frontend :

• NEXT_PUBLIC_API_URL - URL de l'API backend

Volumes Docker

Base de données :

• postgres_data - Persistance des données PostgreSQL

Backend :

• ${AUDIO_LIBRARY_PATH}:/audio:ro - Montage de la bibliothèque audio (lecture seule)
• ./backend/models:/app/models - Montage des modèles Essentia

Frontend :

• ./frontend:/app (dev) - Montage du code source
• /app/node_modules (dev) - Persistance des modules Node

🔄 Flux de développement

1. Développement backend :

   • Modifier le code dans backend/src/
   • Hot-reload automatique avec docker-compose.dev.yml

2. Développement frontend :

   • Modifier le code dans frontend/
   • Hot-reload automatique avec Next.js

3. Déploiement :

   • Construire les images avec docker-compose build
   • Démarrer les services avec docker-compose up -d

🔧 Maintenance et debugging

Accéder au conteneur backend

docker exec -it audio_classifier_api sh

Accéder au conteneur frontend

docker exec -it audio_classifier_ui sh

Accéder à la base de données

docker exec -it audio_classifier_db psql -U audio_user -d audio_classifier

Réinitialiser la base de données

docker-compose down -v
docker-compose up -d

📈 Performance et optimisation

Backend

• Utilisation de --platform=linux/amd64 pour compatibilité Essentia
• Installation des dépendances Python par étapes pour meilleur cache
• Montage des modèles Essentia pour persistance

Frontend

• Utilisation d'Alpine Linux pour image légère
• Installation des dépendances avant copie du code
• Exclusion de node_modules du contexte de build

🔒 Sécurité

• Conteneurs non-root par défaut
• Montage lecture-seule de la bibliothèque audio
• Mise à jour régulière des images de base
• Utilisation de versions spécifiques des dépendances

🆘 Problèmes courants

Essentia non disponible sur ARM

Solution : Utiliser --platform=linux/amd64 dans le Dockerfile

Permissions de fichiers

Solution : Vérifier les permissions du dossier audio monté

CORS errors

Solution : Vérifier la configuration CORS_ORIGINS

📚 Références

• Docker Documentation
• Docker Compose Documentation
• PostgreSQL avec pgvector
• Next.js Dockerisation