Exploitation
Où tournent les choses
| Site | https://music.spboucher.ai |
| App mld | sp-music, épinglée sur son nœud (mld status), port 8690 |
| Dépôt (source de vérité) | sur le nœud : ~/apps/sp-music ; origin spbgit sp-music.git |
| Processus PM2 | sp-music-web (tsx server.ts), sp-music-worker, sp-music-backup (cron 03:45) |
| Base | PostgreSQL 17 local, base sp_music, rôle spmusic_app |
| Bibliothèque | ~/data/sp-music/library (originaux, pochettes, rendus), mode 0700 |
| Sauvegardes | ~/backups/sp-music |
| Secrets | ~/apps/sp-music/.env (0600), ~/.config/sp-music/backup-passphrase |
Prérequis du domaine
- DNS :
A music.spboucher.ai → 51.161.112.61(passerelle BHS64). - HTTPS : certificat obtenu et renouvelé par Caddy ; HTTP redirigé vers HTTPS. Route posée par
mld deploy(tunnel.domain). - Le proxy transmet les corps en flux ; un morceau d'envoi fait 8 Mo (
UPLOAD_MAX_CHUNK_MBborne le serveur) : garder la limite de corps du proxy au-dessus. APP_URLdoit être exactementhttps://music.spboucher.ai: c'est l'origine que WebAuthn vérifie.
Première installation (faite par le déploiement, pour mémoire)
# sur le nœud
brew install ffmpeg # ffmpeg + ffprobe
createuser spmusic_app --pwprompt ; createdb -O spmusic_app sp_music
psql -d sp_music -c 'CREATE EXTENSION IF NOT EXISTS citext; CREATE EXTENSION IF NOT EXISTS pg_trgm;'
mkdir -p ~/data/sp-music/library ~/backups/sp-music ~/.config/sp-music && chmod 700 ~/data/sp-music ~/backups/sp-music ~/.config/sp-music
openssl rand -base64 48 > ~/.config/sp-music/backup-passphrase && chmod 600 ~/.config/sp-music/backup-passphrase
cp .env.example .env && chmod 600 .env # remplir APP_SECRET, DATABASE_URL, OWNER_EMAIL, chemins
# depuis le laptop
mld stage <dossier> sp-music && mld deploy sp-music # pnpm install, migrations, bootstrap, build, PM2, route HTTPSCréer le propriétaire et inscrire Face ID / Touch ID
- Le déploiement a créé le compte propriétaire et écrit un lien à usage unique (24 h) :
ssh <nœud> cat ~/data/sp-music/setup-url.txtLien expiré ?ssh <nœud>puiscd ~/apps/sp-music && node_modules/.bin/tsx scripts/setup-token.ts. - Ouvrir ce lien sur l'appareil à inscrire (iPhone, iPad ou Mac), dans Safari.
- « Créer la clé d'accès » : iOS / macOS affiche sa propre boîte de dialogue et demande Face ID ou Touch ID. Avec le trousseau iCloud activé, la clé est synchronisée sur vos autres appareils Apple.
- Noter les huit codes de récupération (affichés une seule fois) hors ligne.
- Autres appareils :
/compte→ Clés d'accès → Ajouter, depuis une session ouverte ; sur un appareil sans session, le navigateur propose d'utiliser un iPhone à proximité (QR code). - Installer en PWA : Safari → Partager → « Sur l'écran d'accueil ».
Auditeurs : /admin → Comptes → Nouveau compte → transmettre le lien (72 h, usage unique).
Mettre à jour (sur le nœud — remote-first)
ssh <nœud> ; cd ~/apps/sp-music
git pull --ff-only # ou éditer sur place
pnpm install --frozen-lockfile
node_modules/.bin/tsx scripts/migrate.ts
node_modules/.bin/next build
pm2 restart sp-music-web sp-music-worker
git add -A && git commit -m "…" && git push origin mainLes migrations sont transactionnelles et ne s'appliquent qu'une fois ; une migration appliquée puis modifiée fait échouer le déploiement (somme de contrôle). Ne jamais mld move sp-music sans déplacer la base et la bibliothèque (voir Restauration).
Paroles synchronisées (karaoké)
Les paroles sont transcrites sur le nœud à partir de l'audio (mlx-whisper, modèle whisper-large-v3-turbo), avec un
horodatage par mot ; rien n'est envoyé à un service externe et aucun site de paroles n'est interrogé.
uv venv ~/.venvs/whisper --python 3.12 && uv pip install -p ~/.venvs/whisper mlx-whisper # une fois
# .env : LYRICS=auto (ou manual), LYRICS_PYTHON=$HOME/.venvs/whisper/bin/python
node_modules/.bin/tsx scripts/lyrics.ts --missing --wait # toute la bibliothèque
node_modules/.bin/tsx scripts/lyrics.ts --album "Thriller" --lang en --overwriteLYRICS=automet aussi en file chaque nouvel import ;manuallaisse l'administrateur décider (/admin→ Bibliothèque → sélection → Paroles).- La transcription d'une voix chantée sur de la musique reste imparfaite (mots mal entendus, langue mal détectée quand une piste commence par une longue intro : préciser la langue). Chaque ligne se corrige dans
/admin→ Bibliothèque → icône Paroles de la piste ; une correction manuelle n'est jamais écrasée sans demande explicite. - Une piste sans voix est marquée « instrumental ». Les phrases inventées par le modèle sur du silence (« Thank you », « Sous-titrage… ») sont filtrées (
src/server/lyrics.ts).
Sauvegarde
scripts/backup.sh, chaque nuit (PM2 sp-music-backup) :
- Base :
pg_dumpchiffré AES-256 →~/backups/sp-music/db/sp-music-AAAAmmjj-HHMMSS.dump.enc(30 jours), relu parpg_restore --listà chaque exécution. - Bibliothèque : miroir
rsyncdes originaux et des pochettes →~/backups/sp-music/library/; ce qui disparaît de la bibliothèque va danstrash/<date>/pendantBACKUP_TRASH_DAYS(30). Les rendus et miniatures, dérivés, ne sont pas sauvegardés. last-backup.jsonalimente « Dernière sauvegarde » dans/admin→ Système.
À faire par le propriétaire : cette sauvegarde est sur le même disque que la bibliothèque. Elle protège d'une suppression accidentelle, pas d'une panne du disque. Copie hors nœud, depuis une autre machine :
rsync -a <nœud>:backups/sp-music/ /chemin/de/sauvegarde/sp-music/ (planifiable ; les processus PM2 du nœud ne peuvent pas joindre le réseau local). Conserver aussi backup-passphrase ailleurs : sans elle les dumps sont illisibles.
Restauration
createdb -O spmusic_app sp_music # base vide
scripts/restore.sh db ~/backups/sp-music/db/<fichier>.dump.enc "$DATABASE_URL"
scripts/restore.sh library ~/backups/sp-music/library ~/data/sp-music/library
node_modules/.bin/tsx scripts/rebuild-derived.ts # vérifie chaque original, refait les miniatures, remet les rendus en file
pm2 restart sp-music-web sp-music-workerrebuild-derived.ts sort en erreur et liste tout original manquant. Les clés d'accès sont liées au domaine, pas au nœud : elles restent valides après une restauration tant que APP_URL / RP ID ne changent pas. La procédure est exécutée par pnpm test à chaque passage.
Dépannage
| Symptôme | Cause probable / remède |
|---|---|
| « Clés d'accès indisponibles ici » | page ouverte en HTTP, par IP ou sur un autre hôte → ouvrir https://music.spboucher.ai |
| La boîte Face ID n'apparaît pas, « demande annulée » | aucune clé de ce site sur l'appareil (trousseau iCloud désactivé ?) → utiliser un autre appareil, un code de récupération, ou un nouveau lien |
| Connexion refusée après un changement de domaine | APP_URL ou WEBAUTHN_RP_ID modifiés : les clés existantes ne valent que pour l'ancien RP ID |
| Plus aucune clé ni code | sur le nœud : tsx scripts/setup-token.ts --recovery |
| Import bloqué sur « reçu » | worker arrêté : pm2 logs sp-music-worker, pm2 restart sp-music-worker ; /admin → Système indique « Traitement » |
| Import en erreur « type refusé » | le contenu n'est pas un format audio accepté (vérifié sur les octets, pas l'extension) |
| « Non lisible ici » sur une piste | DSD sans TRANSCODE_DSD=true, ou rendu AAC en préparation / en échec (/admin → Bibliothèque → Réanalyser) |
| La lecture ne démarre pas sur iPhone | iOS exige un geste : toucher Lecture. En arrière-plan, iOS garde la lecture d'un <audio> et les commandes de l'écran verrouillé ; le volume se règle par les boutons de l'appareil |
| 413 à l'envoi | fichier au-dessus de UPLOAD_MAX_FILE_MB, ou morceau au-dessus de la limite du proxy |
| Santé | curl https://music.spboucher.ai/api/health → {ok, db, storage, worker} |
Journaux : pm2 logs sp-music-web|sp-music-worker|sp-music-backup (aucun secret ni contenu audio n'y est écrit).