pmomusic/DOCKER.md

Docker Deployment Guide for PMOMusic

Ce guide explique comment construire et déployer PMOMusic avec Docker.

Architecture

Le Dockerfile utilise une approche multi-stage pour créer une image minimale :

1. Stage 1 (webapp-builder) : Compile l'application Vue.js avec Node.js
2. Stage 2 (rust-builder) : Compile le binaire Rust avec toutes ses dépendances
3. Stage 3 (runtime) : Image finale minimale Debian Slim avec uniquement le binaire et les bibliothèques runtime

Avantages

• Binaire auto-contenu : L'application web est embarquée dans le binaire Rust
• Image minimale : ~200-300MB (vs plusieurs GB pour les images de build)
• Sécurité : Exécution en tant qu'utilisateur non-root
• Reproductibilité : Build complet et déterministe

Build de l'image

Option 1 : Build manuel avec Docker

# Build l'image
docker build -t pmomusic:latest .

# Le build prend environ 10-15 minutes selon votre machine

Option 2 : Build avec docker-compose

# Build et démarre le conteneur
docker-compose up --build

# Ou juste build
docker-compose build

Build optimisé avec cache

Pour accélérer les builds successifs, Docker réutilise les couches en cache :

# Build avec cache
docker build -t pmomusic:latest .

# Build sans cache (force rebuild complet)
docker build --no-cache -t pmomusic:latest .

Exécution du conteneur

Option 1 : Avec docker-compose (recommandé)

# Démarrer en arrière-plan
docker-compose up -d

# Voir les logs
docker-compose logs -f

# Arrêter
docker-compose down

# Redémarrer
docker-compose restart

Option 2 : Avec docker run

# Run en mode interactif
docker run -it --rm \
  --name pmomusic \
  --network host \
  -v $(pwd)/config:/home/pmomusic/.pmomusic \
  -v $(pwd)/cache:/home/pmomusic/cache \
  pmomusic:latest

# Run en mode détaché
docker run -d \
  --name pmomusic \
  --network host \
  --restart unless-stopped \
  -v $(pwd)/config:/home/pmomusic/.pmomusic \
  -v $(pwd)/cache:/home/pmomusic/cache \
  pmomusic:latest

Configuration

Ports

Par défaut, PMOMusic écoute sur le port 8080. Vous pouvez modifier cela :

• Dans docker-compose.yml : modifier la section ports
• Avec docker run : utiliser -p 8080:8080

Volumes

Deux volumes sont recommandés pour la persistance :

• Configuration : /home/pmomusic/.pmomusic - Fichiers de configuration
• Cache : /home/pmomusic/cache - Cache audio et métadonnées

Variables d'environnement

Configurable via docker-compose.yml ou -e avec docker run :

# Niveau de logs Rust
RUST_LOG=debug

# Autres variables (selon votre configuration)
# ...

Réseau

Pour UPnP/DLNA, utilisez network_mode: host pour permettre :

• La découverte multicast
• La communication avec les devices UPnP sur le réseau local

Note : Le mode host ne fonctionne que sur Linux. Sur macOS/Windows avec Docker Desktop, utilisez le mapping de ports standard.

Gestion de l'image

Taille de l'image

# Voir la taille de l'image
docker images pmomusic:latest

# Résultat attendu : ~200-300MB

Nettoyage

# Supprimer l'image
docker rmi pmomusic:latest

# Nettoyer les images de build intermédiaires
docker builder prune

# Nettoyer tous les caches Docker (libère beaucoup d'espace)
docker system prune -a

Build multi-plateforme

Pour builder pour différentes architectures (ARM64, AMD64) :

# Créer un builder multi-plateforme
docker buildx create --name multiarch --use

# Build pour AMD64 et ARM64
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t pmomusic:latest \
  --push \
  .

# Note : nécessite un registry Docker (Docker Hub, GHCR, etc.)

Déploiement en production

1. Avec docker-compose (simple)

# Sur le serveur de production
git clone <votre-repo>
cd pmomusic
docker-compose up -d

2. Avec un registry Docker (recommandé)

# Sur votre machine de dev
docker build -t yourregistry.com/pmomusic:v1.0.0 .
docker push yourregistry.com/pmomusic:v1.0.0

# Sur le serveur de production
docker pull yourregistry.com/pmomusic:v1.0.0
docker run -d ... yourregistry.com/pmomusic:v1.0.0

3. Avec un orchestrateur (Kubernetes, Docker Swarm)

Créer un fichier de déploiement approprié selon votre orchestrateur.

Debugging

Logs du conteneur

# Logs en temps réel
docker logs -f pmomusic

# Logs avec docker-compose
docker-compose logs -f

Entrer dans le conteneur

# Shell interactif (bash n'est pas disponible, utiliser sh)
docker exec -it pmomusic sh

# Vérifier les processus
docker exec -it pmomusic ps aux

# Vérifier les fichiers
docker exec -it pmomusic ls -la /home/pmomusic

Health check

Le conteneur inclut un health check. Vérifier l'état :

# Voir l'état de santé
docker inspect --format='{{.State.Health.Status}}' pmomusic

Troubleshooting

Le build échoue

1. Erreur de dépendances npm :

   • Vérifier que pmoapp/webapp/package.json est correct
   • Essayer docker build --no-cache

2. Erreur de compilation Rust :

   • Vérifier que tous les fichiers Cargo.toml sont présents
   • Vérifier les dépendances système (libsoxr, libasound2)

3. Out of memory :

   • Augmenter la mémoire allouée à Docker Desktop (settings)
   • Utiliser --memory pour limiter la mémoire du build

Le conteneur ne démarre pas

1. Port déjà utilisé :

   # Vérifier quel processus utilise le port 8080
   sudo lsof -i :8080
   

2. Permissions :

   • Vérifier les permissions des volumes montés
   • Le conteneur s'exécute en tant qu'utilisateur pmomusic (UID 1000)

3. Configuration manquante :

   • Créer les répertoires de configuration avant de démarrer :

     mkdir -p config cache
     

UPnP ne fonctionne pas

1. Network mode :

   • Sur Linux : utiliser network_mode: host
   • Sur macOS/Windows : UPnP peut ne pas fonctionner correctement avec Docker Desktop

2. Firewall :

   • Vérifier que les ports UPnP ne sont pas bloqués
   • Autoriser le multicast sur le réseau

Performance

Optimisations du build

1. Build cache : Docker réutilise les couches en cache
2. Multi-stage build : Réduit la taille de l'image finale
3. Strip des symboles : Le binaire est strippé pour réduire sa taille

Optimisations runtime

1. Resource limits : Définir des limites CPU/mémoire dans docker-compose.yml
2. Volumes : Utiliser des volumes pour les données persistantes
3. Logs : Configurer la rotation des logs Docker

Sécurité

• ✅ Exécution en tant qu'utilisateur non-root
• ✅ Image minimale (surface d'attaque réduite)
• ✅ Pas de secrets dans l'image
• ✅ Health checks activés
• ✅ Certificats CA inclus pour HTTPS

Références

• Dockerfile
• docker-compose.yml
• .dockerignore
• Documentation Rust