Déploiement — MacLustr
SP TV est déployée par mld (maclustr-dispatch) comme les autres applications du cluster. Rien d'autre n'a été modifié
sur le cluster.
| Élément | Valeur |
|---|---|
| URL | https://tv.spboucher.ai |
App mld |
sp-tv (manifeste M1M32:~/dispatch/apps/sp-tv.json) |
| Nœud | m4mn (Mac mini M4 Pro, épinglé), dossier ~/apps/sp-tv = clone git, origin = spbgit sp-tv.git |
| Port | 8670 (HTTP, écoute sur toutes les interfaces ; seul le tunnel y accède de l'extérieur) |
| Reverse proxy HTTPS | Caddy sur la passerelle BHS64 (certificat Let's Encrypt automatique, HTTP → HTTPS), route posée par mld deploy, trafic acheminé par WireGuard (wg1) |
| DNS | A tv.spboucher.ai → 51.161.112.61 (déjà en place le 2026-11-16, vérifié avant le déploiement) |
| Processus PM2 | sp-tv-web (next start), sp-tv-worker (tsx), sp-tv-backup (cron 03:50) |
| Données | ~/data/sp-tv/sp-tv.db (SQLite, WAL), ~/data/sp-tv/epg-grabber/ (outil IPTV-org, ~260 Mo), ~/data/sp-tv/epg/, ~/data/sp-tv/transcode/ (conversions vidéo, borné à 30 Go par défaut), ~/data/sp-tv/thumbs/ |
| Bibliothèque | ~/media/sp-tv/ (films libres de démonstration) ; NAS : voir ci-dessous |
| Sauvegardes | ~/backups/sp-tv/sp-tv-AAAAMMJJ-HHMMSS.db.gz, 14 jours |
| Secrets | ~/apps/sp-tv/.env (600) ; copie : laptop ~/Desktop/Cluster/secrets/sp-tv/ |
| Dépendances | Node.js ≥ 24 (26 installé ; node:sqlite), pnpm, pm2, git + npm (pour le grabber EPG), /usr/bin/sqlite3 (sauvegarde), ffmpeg + ffprobe (brew install ffmpeg, installés le 2026-11-16 ; analyse et conversion de la bibliothèque) |
Redémarrage automatique : PM2 (autorestart), pm2 resurrect à l'ouverture de session du nœud, et mld heal toutes les
5 minutes depuis la passerelle (relance PM2, tunnel et route si nécessaire).
Première installation (déjà faite le 2026-11-16)
# 1. secrets sur le nœud
ssh m4mn 'mkdir -p ~/apps/sp-tv ~/data/sp-tv ~/backups/sp-tv && cd ~/apps/sp-tv && cp .env.example .env && chmod 600 .env' # puis remplir APP_SECRET, DATA_DIR, BACKUP_DIR
# 2. manifeste M1M32:~/dispatch/apps/sp-tv.json, puis
mld stage ~/Desktop/Cluster/projets/sp-tv sp-tv
mld deploy sp-tv --node m4mn # rsync, pnpm install, bootstrap, next build, PM2, route tunnel, santé
mld adopt sp-tv # le dossier déployé devient un clone gitscripts/bootstrap.ts (hook de déploiement, idempotent) crée la base et, s'il n'y en a pas, un mot de passe aléatoire
écrit une seule fois dans ~/data/sp-tv/initial-password.txt (600). Le worker lance la première synchronisation au démarrage.
Mettre à jour (remote-first : sur le nœud)
ssh m4mn
cd ~/apps/sp-tv && export PATH=/opt/homebrew/bin:$PATH
# … modifier, ou git pull …
pnpm install --frozen-lockfile
node_modules/.bin/next build
pm2 restart sp-tv-web sp-tv-worker
git add -A && git commit -m "…" && git push origin mainLes migrations de la base (MIGRATIONS dans src/server/db.ts) s'appliquent seules au démarrage ; ne jamais modifier une
migration déjà appliquée, en ajouter une.
Bibliothèque et NAS Ugreen
État constaté le 2026-11-16 : les deux NAS Ugreen sont injoignables (aucun montage ~/nas_clustr / ~/nas2_clustr sur
m4mn ni sur les autres nœuds vérifiés, port SMB fermé aux adresses 192.168.2.173 et .175, aucune adresse MAC 6c:1f:f7:…
sur le réseau local). m4mn n'a pas non plus les scripts de montage automatique des anciens nœuds. La bibliothèque a donc
été validée avec un dossier local (~/media/sp-tv, films Blender sous licence Creative Commons).
Pour brancher un NAS quand il sera rallumé :
- Monter le partage sur m4mn (Finder → Se connecter au serveur
smb://<ip-du-nas>/clustr, ou le script~/bin/nas_automount.shdes autres nœuds) : il apparaît sous/Volumes/clustrou~/nas_clustr. - Admin → Bibliothèque → Ajouter un dossier (ex.
/Volumes/clustr/media/movies, type Films). Seuls les emplacements sous~/media,~/nas_clustr,~/nas2_clustret/Volumessont acceptés (variableLIBRARY_ROOTSpour en changer). - L'analyse démarre aussitôt puis toutes les 15 minutes. Si le NAS s'éteint, le dossier passe « inaccessible » et son catalogue est conservé.
Non vérifié : la lecture depuis un vrai partage SMB (débit, droits macOS d'accès aux volumes réseau pour un processus PM2).
Jellyfin (installé le 2026-11-17)
App mld jellyfin sur m4mn, port 8096, URL de base /jellyfin (dépôt jellyfin.git, dossier ~/apps/jellyfin :
install.sh, start.sh, setup.sh). Binaire officiel portable dans ~/opt/jellyfin/12.4, données dans ~/data/jellyfin,
mot de passe administrateur dans ~/.config/jellyfin/admin-password (copie : laptop ~/Desktop/Cluster/secrets/jellyfin/).
- Publication : pas de nom de domaine propre. SP TV le publie sous
https://tv.spboucher.ai/jellyfin/par une réécriture (JELLYFIN_PROXY=http://127.0.0.1:8096dans.env, lue aunext build) ;src/proxy.tspassant avant, Jellyfin n'est joignable qu'avec une session SP TV ouverte, en HTTPS. - Administration de Jellyfin à la maison :
http://192.168.2.93:8096/jellyfin/web/(comptesp). L'interface web de Jellyfin à travers SP TV n'a pas été validée (elle n'est pas nécessaire : SP TV lit la bibliothèque par l'API). - Bibliothèques : « Films » et « Séries » sur
~/media/sp-tv/…(films libres de démonstration), « Mes films » et « Mes séries » sur~/media/jellyfin/filmset~/media/jellyfin/series(vides : déposez-y vos fichiers). Après un dépôt de fichiers, Jellyfin les indexe à son rythme ; SP TV les reprend à l'actualisation quotidienne des sources (ou Admin → Sources → Actualiser). - Dans SP TV : source « Jellyfin (m4mn) » (Admin → Sources), adresse interne
http://127.0.0.1:8096/jellyfin, adresse vue par les appareilshttps://tv.spboucher.ai/jellyfin. - Les quatre titres de démonstration existent donc deux fois dans SP TV (bibliothèque intégrée et Jellyfin) : retirez l'un des deux (Admin → Bibliothèque, ou désactivez la source Jellyfin) selon l'outil que vous préférez.
- Mise à niveau :
JELLYFIN_VERSION=x.y ./install.sh && pm2 restart jellyfin. Non sauvegardé automatiquement.
Relay Engine (installé le 2026-11-17)
Processus PM2 sp-tv-relay (scripts/relay-start.sh : génère ~/data/sp-tv/relay/mediamtx.yml puis lance
~/opt/mediamtx/mediamtx, installé par scripts/relay-install.sh). Ports 8672 à 8675, boucle locale uniquement.
FFmpeg vient de Homebrew. Le manifeste mld (M1M32:~/dispatch/apps/sp-tv.json) contient le processus, les ports et
l'installation de MediaMTX en post_sync. Exploitation et réglages : RELAY.md.
TMDB
TMDB_API_KEY dans .env (ajoutée le 2026-11-17). Passe d'enrichissement à la fin de l'import hebdomadaire des films, ou
à la main : node_modules/.bin/tsx scripts/run-job.ts tmdb. Mention d'attribution affichée sur les fiches concernées et
dans Paramètres.
Exploitation
mld status --live | grep sp-tv # état vu de la passerelle
mld logs sp-tv # journaux PM2
ssh m4mn 'pm2 logs sp-tv-worker --lines 100 --nostream'
ssh m4mn 'pm2 logs sp-tv-web --lines 100 --nostream'
curl -s https://tv.spboucher.ai/api/healthLes journaux applicatifs (synchronisations, guide, lots de tests, connexions, erreurs) sont aussi dans Admin → Journaux
(30 jours conservés) ; les fichiers PM2 sont dans ~/.pm2/logs/sp-tv-*.log.
Tâches manuelles sur le nœud (dans ~/apps/sp-tv) :
node_modules/.bin/tsx scripts/run-job.ts sync # synchronisation immédiate
node_modules/.bin/tsx scripts/run-job.ts epg # guide TV
node_modules/.bin/tsx scripts/run-job.ts check 50 # teste 50 flux, détail à l'écran
node_modules/.bin/tsx scripts/run-job.ts vod # films et séries libres
node_modules/.bin/tsx scripts/run-job.ts library # analyse de la bibliothèque
node_modules/.bin/tsx scripts/set-password.ts # nouveau mot de passe aléatoire, ferme toutes les sessionsSauvegarde et restauration
sp-tv-backup exécute scripts/backup.sh chaque nuit à 03:50 : copie cohérente à chaud (sqlite3 .backup), contrôle
d'intégrité, gzip, purge après 14 jours. Lancer à la main : ssh m4mn 'cd ~/apps/sp-tv && bash scripts/backup.sh'.
# restauration
pm2 stop sp-tv-web sp-tv-worker
gunzip -c ~/backups/sp-tv/sp-tv-AAAAMMJJ-HHMMSS.db.gz > ~/data/sp-tv/sp-tv.db
rm -f ~/data/sp-tv/sp-tv.db-wal ~/data/sp-tv/sp-tv.db-shm
pm2 start sp-tv-web sp-tv-workerLimite : les sauvegardes sont sur le même disque que la base. Seul l'état personnel (favoris, listes, masquées, paramètres, clés d'accès) est irremplaçable ; le catalogue et le guide se reconstruisent par synchronisation.
Ne pas faire mld move sp-tv sans copier ~/data/sp-tv/sp-tv.db : la base ne suit pas l'application.
Dépannage
| Symptôme | Vérifier |
|---|---|
| Admin affiche « Le worker ne répond pas » | pm2 describe sp-tv-worker, pm2 logs sp-tv-worker ; pm2 restart sp-tv-worker |
| Synchronisation en échec | Admin → Aperçu → Tâches récentes (erreur par source) ; curl -I https://iptv-org.github.io/iptv/index.m3u depuis le nœud |
| Guide vide | Admin → Journaux, composant epg ; ls ~/data/sp-tv/epg-grabber ; relancer run-job.ts epg ; supprimer epg-grabber/ force une réinstallation |
| Site injoignable | mld health sp-tv, mld tunnel status, mld heal |
| Un fichier de la bibliothèque ne se lit pas | Admin → Bibliothèque (mode de lecture, erreurs d'analyse) ; pm2 logs sp-tv-web (erreur ffmpeg) ; rm -rf ~/data/sp-tv/transcode/<id>-a0 force une nouvelle conversion |
| Films absents | Admin → Films et séries → Mettre à jour ; Journaux, composant vod (Wikidata ou Wikipédia peuvent limiter le débit : relancer plus tard) |
| Mot de passe perdu | scripts/set-password.ts sur le nœud |
| Trop de tentatives de connexion | attendre 15 min, ou sqlite3 ~/data/sp-tv/sp-tv.db 'DELETE FROM login_attempts' |
| Tout marque « indisponible » | le nœud a-t-il Internet ? run-job.ts check 20 montre la cause par flux |