🎬 jellyfin-node
Serveur Jellyfin du cluster MacLustr — trois scripts shell idempotents pour installer, lancer et configurer un Jellyfin portable sur macOS arm64, publié derrière la session de SP TV.
Sommaire
- Présentation
- Ce que fait le dépôt
- Architecture
- Pile technique
- Arborescence
- Emplacements sur le nœud
- Installation et démarrage
- Configuration
- Scripts en détail
- Accès
- Bibliothèques
- Déploiement (MacLustr,
mld) - Mise à niveau
- Sauvegarde
- Sécurité
- État et limites
- Auteur et licence
📺 Présentation
Serveur Jellyfin du cluster MacLustr, déployé par mld (app jellyfin) sur m4mn, port 8096, URL de base
/jellyfin.
Le dépôt ne contient pas Jellyfin lui-même : il contient la recette pour l'installer et l'exploiter sur un Mac Apple
Silicon, en trois scripts shell sans dépendance autre que curl, tar, python3 et ffmpeg. Il sert de bibliothèque
multimédia à SP TV (https://tv.spboucher.ai), qui la lit par son connecteur Jellyfin
(Admin → Sources).
✨ Ce que fait le dépôt
- Binaire : build portable officiel macOS arm64, hors du dépôt, dans
~/opt/jellyfin/<version>(install.sh). - Données, configuration, journaux :
~/data/jellyfin/. Mot de passe administrateur :~/.config/jellyfin/admin-password. - Processus PM2 :
jellyfin(start.sh). ffmpeg de Homebrew, encodage matériel VideoToolbox. - Publication sous un préfixe : Jellyfin est servi sous
/jellyfin(fichiernetwork.xmlécrit parinstall.sh) afin de pouvoir se placer derrière un autre site — SP TV — sur le même nom d'hôte. - Premier démarrage automatisé (
setup.sh) par l'API de Jellyfin : compte administrateur, bibliothèques, encodage matériel, langue et pays des métadonnées (français, Canada). - Idempotence : chaque script peut être relancé sans effet de bord (version déjà installée conservée, assistant déjà terminé laissé tel quel, bibliothèques existantes non dupliquées).
🏗 Architecture
flowchart LR
subgraph Internet
U[Appareil<br/>navigateur / téléviseur]
end
subgraph Passerelle["Passerelle MacLustr Tunnel"]
C[Caddy HTTPS]
end
subgraph m4mn["Nœud m4mn"]
TV["SP TV · Next.js<br/>port 8670<br/>contrôle de session"]
JF["Jellyfin · PM2 « jellyfin »<br/>port 8096 · /jellyfin"]
FF[ffmpeg Homebrew<br/>VideoToolbox]
D[("~/data/jellyfin<br/>data · cache · config · log")]
M[("Dossiers de médias")]
end
LAN[Réseau de la maison] -->|"http · /jellyfin/web/"| JF
U -->|"https://tv.spboucher.ai/jellyfin/"| C --> TV
TV -->|"réécriture JELLYFIN_PROXY"| JF
TV -.->|"connecteur Jellyfin (API)"| JF
JF --> FF
JF --> D
JF --> M
Jellyfin n'a aucun nom de domaine propre. De l'extérieur, il n'est joignable qu'à travers SP TV, donc en HTTPS et seulement avec une session SP TV ouverte.
🧰 Pile technique
| Rôle | Technologie | Version / remarque |
|---|---|---|
| Serveur multimédia | Jellyfin, build portable officiel macOS arm64 | 12.4 par défaut (JELLYFIN_VERSION dans install.sh) |
| Scripts | Bash (set -euo pipefail) |
3 scripts, 64 lignes |
| Appels d'API | curl |
API REST de Jellyfin |
| Analyse JSON | python3 -I (bibliothèque standard) |
aucune dépendance installée |
| Transcodage | ffmpeg de Homebrew |
accélération matérielle Apple VideoToolbox |
| Gestionnaire de processus | PM2 | processus jellyfin |
| Orchestration | mld (maclustr-dispatch) |
app jellyfin, install.sh en crochet post_sync |
🗂 Arborescence
jellyfin/
├── install.sh # télécharge et installe Jellyfin hors du dépôt, prépare la configuration réseau (26 lignes)
├── start.sh # lance le serveur au premier plan ; PM2 le maintient en vie (6 lignes)
├── setup.sh # premier démarrage par l'API : compte, bibliothèques, encodage matériel (32 lignes)
├── README.md
└── .gitignore📍 Emplacements sur le nœud
| Chemin | Contenu |
|---|---|
~/apps/jellyfin |
ce dépôt (clone git déployé par mld) |
~/opt/jellyfin/<version> |
binaire portable de Jellyfin, un dossier par version |
~/opt/jellyfin/current |
lien symbolique vers la version active |
~/data/jellyfin/data |
base et données de Jellyfin |
~/data/jellyfin/cache |
cache |
~/data/jellyfin/config |
configuration (dont network.xml) |
~/data/jellyfin/log |
journaux |
~/.config/jellyfin/admin-password |
mot de passe administrateur (hors dépôt) |
~/data/jellyfin est créé en mode 700.
🚀 Installation et démarrage
# 1. Installer le binaire et préparer la configuration (idempotent)
./install.sh
# 2. Lancer le serveur sous PM2
pm2 start ./start.sh --name jellyfin
# 3. Premier démarrage : compte administrateur, bibliothèques, encodage matériel
./setup.sh sp ~/.config/jellyfin/admin-password "Films:movies:/chemin/vers/films" "Séries:tvshows:/chemin/vers/series"Prérequis : macOS sur Apple Silicon, curl, tar (avec prise en charge de xz), python3, ffmpeg (Homebrew), PM2.
⚙️ Configuration
| Variable | Script | Rôle | Défaut |
|---|---|---|---|
JELLYFIN_VERSION |
install.sh |
version de Jellyfin à installer | 12.4 |
JELLYFIN_URL |
setup.sh |
adresse de l'API de Jellyfin utilisée par la configuration | http://127.0.0.1:8096/jellyfin |
Côté SP TV, la variable JELLYFIN_PROXY (lue au next build de SP TV) publie ce serveur sous /jellyfin du site.
🔧 Scripts en détail
install.sh
Installe le serveur Jellyfin (build portable officiel macOS arm64) hors du dossier de l'application et prépare sa
configuration. Exécuté par mld deploy (crochet post_sync) et utilisable à la main.
- crée
~/opt/jellyfinet~/data/jellyfin/{data,cache,config,log}; - si la version demandée n'est pas déjà présente, télécharge l'archive
jellyfin_<version>-arm64.tar.xzdepuisrepo.jellyfin.orget l'extrait dans~/opt/jellyfin/<version>; - pointe le lien
~/opt/jellyfin/currentsur cette version ; - écrit
config/network.xmlavec<BaseUrl>/jellyfin</BaseUrl>s'il n'existe pas encore.
start.sh
Lance Jellyfin au premier plan (exec), avec --datadir, --cachedir, --configdir, --logdir sous ~/data/jellyfin
et --ffmpeg pointant sur le ffmpeg trouvé dans le PATH (à défaut /opt/homebrew/bin/ffmpeg).
setup.sh
setup.sh <utilisateur-admin> <fichier-mot-de-passe> [nom:type:chemin ...] type = movies | tvshows | homevideos| Étape | Appel à l'API de Jellyfin | Effet |
|---|---|---|
| État de l'assistant | GET /System/Info/Public |
un assistant déjà terminé est laissé tel quel |
| Langue et pays | POST /Startup/Configuration |
interface en français, métadonnées fr / CA |
| Compte administrateur | GET puis POST /Startup/User |
compte créé avec le mot de passe lu dans le fichier |
| Accès distant | POST /Startup/RemoteAccess |
accès distant activé, pas de redirection de port automatique |
| Fin de l'assistant | POST /Startup/Complete |
— |
| Connexion | POST /Users/AuthenticateByName |
jeton de session temporaire |
| Bibliothèques | GET / POST /Library/VirtualFolders |
une bibliothèque par argument ; existante ou dossier absent : ignorée avec un message |
| Encodage | GET / POST /System/Configuration/encoding |
HardwareAccelerationType = videotoolbox, encodage matériel activé |
| Déconnexion | POST /Sessions/Logout |
le jeton temporaire est fermé |
Le mot de passe est lu depuis un fichier et transmis à curl par l'entrée standard (-d @-) : il n'apparaît pas dans la
liste des processus.
🌐 Accès
- depuis SP TV, partout :
https://tv.spboucher.ai/jellyfin/— publié par SP TV lui-même (variableJELLYFIN_PROXYde SP TV), donc en HTTPS et seulement avec une session SP TV ouverte ; - à la maison, interface d'administration :
http://<ip-de-m4mn>:8096/jellyfin/web/.
SP TV lit cette bibliothèque par son connecteur Jellyfin (Admin → Sources).
📚 Bibliothèques
Les bibliothèques sont créées par setup.sh (voir la commande ci-dessus). Pour en ajouter : interface de Jellyfin, ou
./setup.sh sp ~/.config/jellyfin/admin-password "Nom:movies:/chemin"| Type | Contenu |
|---|---|
movies |
films |
tvshows |
séries |
homevideos |
vidéos personnelles |
Chaque bibliothèque est créée avec les métadonnées en français (pays CA) et une analyse immédiate (refreshLibrary=true).
🚢 Déploiement (MacLustr, mld)
| Élément | Valeur |
|---|---|
App mld |
jellyfin |
| Nœud | m4mn, dossier ~/apps/jellyfin (clone git, origin = spbgit jellyfin.git) |
| Port | 8096, URL de base /jellyfin |
| Processus PM2 | jellyfin (start.sh) |
| Crochet de déploiement | install.sh (post_sync) |
| Domaine public | aucun — publié sous https://tv.spboucher.ai/jellyfin/ par SP TV |
mld deploy jellyfin --node m4mn # synchronisation, install.sh, PM2
mld status --live | grep jellyfin # état vu de la passerelle⬆️ Mise à niveau
JELLYFIN_VERSION=x.y ./install.sh && pm2 restart jellyfinL'ancienne version reste dans ~/opt/jellyfin/<ancienne-version> ; seul le lien current change.
💾 Sauvegarde
À sauvegarder : ~/data/jellyfin/data et ~/data/jellyfin/config (non sauvegardés automatiquement à ce jour).
🔒 Sécurité
- Aucun secret dans le dépôt : le mot de passe administrateur vit dans
~/.config/jellyfin/admin-password, hors du clone. - Pas d'exposition directe sur Internet : l'accès extérieur passe par SP TV, en HTTPS, derrière sa session.
~/data/jellyfinen mode700.python3 -I(mode isolé) pour analyser les réponses JSON ;set -euo pipefaildans les trois scripts.
🧭 État et limites
- En service sur m4mn (dépôt adopté comme source de vérité le 2026-11-17, « remote-first »).
- Sauvegarde automatique des données : à faire.
- Pas de tests automatisés (dépôt de trois scripts).
👤 Auteur et licence
Simon-Pierre Boucher — contact@spboucher.ai · forge : git.spboucher.ai
Scripts de ce dépôt : tous droits réservés. Jellyfin est un logiciel libre distribué séparément par son projet (jellyfin.org) ; il n'est pas inclus dans ce dépôt.