Audio-Classifier/DEPLOYMENT.md

Déploiement Audio Classifier

🚀 Déploiement Autonome

Le système est 100% autonome - aucune action manuelle requise ! Les modèles Essentia sont intégrés dans l'image Docker.

Prérequis

• Docker + Docker Compose
• 2 GB RAM minimum
• Port 3000 (frontend) et 8001 (backend) disponibles

Démarrage Rapide

1. Cloner le projet :

git clone https://git.benoitsz.com/benoit/Audio-Classifier.git
cd Audio-Classifier

2. Configurer le chemin audio (optionnel) :

# Créer un fichier .env
echo "AUDIO_LIBRARY_PATH=/chemin/vers/votre/musique" > .env

3. Démarrer :

docker-compose up -d

4. Accéder à l'interface :

• Frontend : http://localhost:3000
• API : http://localhost:8001
• Docs API : http://localhost:8001/docs

C'est tout ! 🎉

Note : Les images Docker sont automatiquement téléchargées depuis git.benoitsz.com. Aucun build nécessaire !

Premier Scan

1. Ouvrir http://localhost:3000
2. Cliquer sur le bouton "Rescan" dans le header
3. Attendre que le scan se termine (progression affichée)
4. Profiter !

📦 Ce qui est inclus dans l'image

✅ Modèles Essentia (28 MB) :

• discogs-effnet-bs64-1.pb (18 MB) - Embedding model
• genre_discogs400-discogs-effnet-1.pb (2 MB) - Genre classifier
• mtg_jamendo_moodtheme-discogs-effnet-1.pb (2.7 MB) - Mood classifier
• mtg_jamendo_instrument-discogs-effnet-1.pb (2.6 MB) - Instrument classifier

✅ Dépendances Python :

• FastAPI, Uvicorn
• Essentia-TensorFlow
• Librosa, SQLAlchemy
• FFmpeg (pour transcodage)

✅ Base de données :

• PostgreSQL avec pgvector
• Migrations Alembic auto-appliquées

⚙️ Configuration

Variables d'environnement (.env)

# Audio Library
AUDIO_LIBRARY_PATH=/chemin/vers/musique  # Défaut: ./audio_samples

# Database
POSTGRES_USER=audio_user
POSTGRES_PASSWORD=audio_password
POSTGRES_DB=audio_classifier

# CORS (pour déploiement distant)
CORS_ORIGINS=http://localhost:3000,http://votre-domaine.com

Ports

Par défaut :

• Frontend : 3000
• Backend API : 8001
• PostgreSQL : 5433 (mapping host)

Pour changer :

# Dans docker-compose.yml
services:
  backend:
    ports:
      - "VOTRE_PORT:8000"

🔄 Mise à jour

# Arrêter les containers
docker-compose down

# Pull les dernières modifications
git pull

# Rebuild et redémarrer
docker-compose up -d --build

📊 Monitoring

Logs en temps réel

# Tous les services
docker-compose logs -f

# Backend uniquement
docker-compose logs -f backend

# Frontend uniquement
docker-compose logs -f frontend

Statut des containers

docker-compose ps

Santé de l'API

curl http://localhost:8001/health

🗄️ Gestion de la base de données

Backup

docker-compose exec postgres pg_dump -U audio_user audio_classifier > backup.sql

Restore

docker-compose exec -T postgres psql -U audio_user audio_classifier < backup.sql

Reset complet

docker-compose down -v  # ATTENTION : supprime toutes les données !
docker-compose up -d

🎵 Scan de bibliothèque

Via l'interface web

Cliquez sur "Rescan" dans le header.

Via l'API

curl -X POST http://localhost:8001/api/library/scan

Via CLI (dans le container)

docker-compose exec backend python -m src.cli.scanner /audio

Statut du scan

curl http://localhost:8001/api/library/scan/status

📁 Structure des fichiers générés

Lors du scan, deux dossiers sont créés automatiquement :

/votre/musique/
├── fichier1.mp3
├── fichier2.flac
├── transcoded/              # MP3 128kbps pour streaming
│   ├── fichier1.mp3
│   └── fichier2.mp3
└── waveforms/               # JSON pré-calculés
    ├── fichier1.waveform.json
    └── fichier2.waveform.json

🚢 Déploiement Production

Sur un serveur distant

1. Installer Docker sur le serveur

2. Cloner et configurer :

git clone <votre-repo>
cd Audio-Classifier

3. Configurer .env :

# Chemin vers musique
AUDIO_LIBRARY_PATH=/mnt/musique

# URL publique de l'API (IMPORTANT pour le frontend)
# Cette URL est utilisée par le navigateur pour accéder à l'API
# Remplacer par votre domaine ou IP publique + port 8001
NEXT_PUBLIC_API_URL=https://votre-serveur.com:8001

# Domaine public pour CORS (doit inclure l'URL du frontend)
CORS_ORIGINS=https://votre-domaine.com,https://votre-domaine.com:3000

# Credentials BDD (sécurisés !)
POSTGRES_PASSWORD=motdepasse_fort_aleatoire

Important : Le frontend utilise maintenant une configuration runtime, ce qui signifie que vous pouvez changer NEXT_PUBLIC_API_URL dans le fichier .env et redémarrer les containers sans avoir à rebuilder les images.

4. Démarrer :

docker-compose up -d

5. Configurer reverse proxy (Nginx/Caddy) :

# Exemple Nginx
server {
    server_name votre-domaine.com;

    location / {
        proxy_pass http://localhost:3000;
    }

    location /api/ {
        proxy_pass http://localhost:8001/api/;
    }
}

Avec Docker Hub

1. Tag et push :

docker tag audio-classifier-backend:latest votrecompte/audio-classifier-backend:latest
docker push votrecompte/audio-classifier-backend:latest

2. Sur le serveur :

# docker-compose.yml
services:
  backend:
    image: votrecompte/audio-classifier-backend:latest
    # ... reste de la config

🔒 Sécurité

Recommandations

✅ Changer les mots de passe par défaut ✅ Utiliser HTTPS en production (Let's Encrypt) ✅ Restreindre CORS_ORIGINS aux domaines autorisés ✅ Ne pas exposer PostgreSQL publiquement ✅ Backups réguliers de la BDD

Firewall

# Autoriser uniquement ports nécessaires
ufw allow 80/tcp   # HTTP
ufw allow 443/tcp  # HTTPS
ufw allow 22/tcp   # SSH
ufw enable

❓ Troubleshooting

Les modèles ne se chargent pas

# Vérifier que les modèles sont dans l'image
docker-compose exec backend ls -lh /app/models

# Devrait afficher 28 MB de modèles

Le scan ne démarre pas

# Vérifier les permissions du dossier audio
docker-compose exec backend ls -la /audio

# Devrait être accessible en écriture

Erreur de mémoire

# Augmenter la mémoire Docker
# Docker Desktop > Settings > Resources > Memory : 4 GB minimum

Port déjà utilisé

# Changer le port dans docker-compose.yml
services:
  backend:
    ports:
      - "8002:8000"  # Au lieu de 8001

📚 Ressources

• Documentation Essentia
• FastAPI Docs
• Next.js Docs
• Docker Compose

💡 Conseil

Pour un déploiement vraiment autonome sur un nouveau serveur :

# Tout en une commande !
git clone <repo> && \
cd Audio-Classifier && \
echo "AUDIO_LIBRARY_PATH=/mnt/musique" > .env && \
docker-compose up -d

# Attendre 30 secondes puis ouvrir http://serveur:3000
# Cliquer sur "Rescan" et c'est parti ! 🚀