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** :
```bash
git clone https://git.benoitsz.com/benoit/Audio-Classifier.git
cd Audio-Classifier
```

2. **Configurer le chemin audio** (optionnel) :
```bash
# Créer un fichier .env
echo "AUDIO_LIBRARY_PATH=/chemin/vers/votre/musique" > .env
```

3. **Démarrer** :
```bash
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)

```bash
# 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 :
```yaml
# Dans docker-compose.yml
services:
  backend:
    ports:
      - "VOTRE_PORT:8000"
```

## 🔄 Mise à jour

```bash
# 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
```bash
# Tous les services
docker-compose logs -f

# Backend uniquement
docker-compose logs -f backend

# Frontend uniquement
docker-compose logs -f frontend
```

### Statut des containers
```bash
docker-compose ps
```

### Santé de l'API
```bash
curl http://localhost:8001/health
```

## 🗄️ Gestion de la base de données

### Backup
```bash
docker-compose exec postgres pg_dump -U audio_user audio_classifier > backup.sql
```

### Restore
```bash
docker-compose exec -T postgres psql -U audio_user audio_classifier < backup.sql
```

### Reset complet
```bash
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
```bash
curl -X POST http://localhost:8001/api/library/scan
```

### Via CLI (dans le container)
```bash
docker-compose exec backend python -m src.cli.scanner /audio
```

### Statut du scan
```bash
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** :
```bash
git clone <votre-repo>
cd Audio-Classifier
```

3. **Configurer .env** :
```bash
# 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** :
```bash
docker-compose up -d
```

5. **Configurer reverse proxy** (Nginx/Caddy) :
```nginx
# 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** :
```bash
docker tag audio-classifier-backend:latest votrecompte/audio-classifier-backend:latest
docker push votrecompte/audio-classifier-backend:latest
```

2. **Sur le serveur** :
```yaml
# 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
```bash
# 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
```bash
# 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
```bash
# Vérifier les permissions du dossier audio
docker-compose exec backend ls -la /audio

# Devrait être accessible en écriture
```

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

### Port déjà utilisé
```bash
# Changer le port dans docker-compose.yml
services:
  backend:
    ports:
      - "8002:8000"  # Au lieu de 8001
```

## 📚 Ressources

- [Documentation Essentia](https://essentia.upf.edu/)
- [FastAPI Docs](https://fastapi.tiangolo.com/)
- [Next.js Docs](https://nextjs.org/docs)
- [Docker Compose](https://docs.docker.com/compose/)

## 💡 Conseil

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

```bash
# 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 ! 🚀
```