Documentation

Installer et configurer

Installer#

Essayé sur des systèmes vierges avec un vrai systemd : Debian 13 et Ubuntu 24.04 (deploy/package/test/run.sh). La lecture y est faite par le processeur : aucune accélération matérielle n'y est validée.

Le paquet, l'archive et l'image apportent le FFmpeg de ProtoFlix (ADR 0041) : rien à installer à part. Ils demandent une distribution récente (glibc 2.36) : Debian 12 et 13, Ubuntu 24.04 et plus récents. Sur Ubuntu 22.04, passez par l'image Docker.

Un FFmpeg du système reste accepté à partir de la 5.1, celle de Debian 12, avec PROTOFLIX_FFMPEG_PATH et PROTOFLIX_FFPROBE_PATH. Avec un FFmpeg trop ancien, le serveur démarre, l'écrit dans son journal et n'analyse ni ne convertit rien, sans toucher à ce qu'il connaît déjà.

Avec un FFmpeg du système antérieur à la 6.1, deux différences :

• Le fichier est rouvert. Avant FFmpeg 6.0, le moteur ne sait pas lire le fichier que le serveur lui a ouvert : il le rouvre par /dev/fd/3, et seuls les formats de fichiers multimédias lui sont permis. Sous le compte séparé du service média (ADR 0028), ce compte doit pouvoir lire la bibliothèque.
• Le démarrage est un peu plus lent. La conversion ne prend pas d'avance au démarrage : elle travaille aussi vite qu'elle peut, mise en pause quand elle a trop d'avance sur le lecteur.

Les tests du moteur passent sous FFmpeg 5.1, Debian 12, VAAPI compris. Le paquet lui-même n'a pas encore été installé sur un Debian 12 vierge.

Debian, Ubuntu#

sudo apt install ./protoflix_<version>_amd64.deb

Le paquet apporte son FFmpeg, crée l'utilisateur protoflix (dans les groupes video et render), démarre le service et donne l'adresse à ouvrir pour créer le compte administrateur.

• Premier compte : sa création demande un code que le serveur écrit dans son journal, nouveau à chaque démarrage (journalctl -u protoflix), et n'est possible que depuis le réseau local. PROTOFLIX_SETUP_TOKEN le fixe d'avance.
• Vos films doivent être lisibles par l'utilisateur protoflix, et hors de /var/lib.
• Réglages : /etc/protoflix/protoflix.env, gardés lors des mises à jour.
• Mise à jour : la même commande avec le nouveau paquet. La base est migrée au démarrage, après une sauvegarde vérifiée.
• Retrait : sudo apt remove protoflix garde la base. sudo apt purge protoflix efface aussi la base et les réglages. Vos films ne sont jamais touchés.
• Journal : journalctl -u protoflix.

Autres systèmes avec systemd#

tar xzf protoflix-<version>-linux-amd64.tar.gz
cd protoflix-<version>-linux-amd64
sudo sh install.sh

Il faut systemd. L'archive apporte son FFmpeg ; s'il ne démarre pas, il manque libva2 et libva-drm2. sudo sh install.sh --remove retire le service et garde la base.

Docker#

docker compose -f deploy/docker/compose.yaml up -d --build

Indiquez d'abord vos dossiers dans compose.yaml. Dans l'interface, ajoutez la bibliothèque sous son chemin dans le conteneur (/media/films). L'image contient le FFmpeg de ProtoFlix (ADR 0041) : avant de la diffuser hors de votre serveur, voir risks.md.

• Mise à jour : comme pour le paquet, en un clic ou automatiquement, depuis Administration › Mises à jour. Le conteneur updater installe la version signée dans le volume protoflix-app, relance le serveur dessus, et revient en arrière s'il ne répond pas (ADR 0027, « Sous Docker »). Aucun des deux conteneurs n'a accès au socket Docker. Tirer ou reconstruire une image plus récente met aussi à jour : la plus récente des deux versions démarre.
• Sans mises à jour intégrées : retirez le service updater et PROTOFLIX_SELF_UPDATE ; l'image se met alors à jour seulement en la remplaçant.

Carte graphique#

Le serveur essaie au démarrage ce que la machine sait faire, et n'utilise que ce qui a fonctionné. Si ça échoue en cours de route, le processeur prend le relais.

• Nvidia : installez le pilote de la carte, avec la bibliothèque libnvidia-encode. En Docker, décommentez gpus dans compose.yaml. Mesuré sur une GTX 1080 par le pilote Windows dans Docker ; pas encore essayé sur un vrai Linux, le service systemd avec ses protections compris. Voir docs/testing/benchmarks/nvidia-gtx1080.md.
• Intel et AMD (VAAPI) : la partie graphique intégrée décode le H.264 et le HEVC (10 bits compris), réduit l'image et l'encode en H.264. Il faut le pilote VAAPI de la carte : intel-media-va-driver-non-free pour Intel, mesa-va-drivers pour AMD ; le paquet met déjà l'utilisateur du service dans le groupe render. Mesuré sur un Intel UHD 750 : six conversions 4K vers 1080p tiennent ensemble le temps réel, la limite est fixée à quatre (docs/testing/benchmarks/vaapi-intel-uhd750.md), et les tons HDR se calculent sur la carte. Les Radeon n'ont pas encore été essayées sur du vrai matériel.

Port#

Le paquet et l'image écoutent sur le port 8097, car 8096 est celui de Jellyfin et les deux peuvent tourner côte à côte. Le binaire lancé seul reste sur 127.0.0.1:8096.

Construire les paquets#

sh deploy/package/build.sh <version>
sh deploy/package/test/run.sh <version>

Ils sortent dans dist/, depuis le dernier commit. Il faut seulement git et Docker.

1. Plateformes#

Dépendances d'exécution :

• aucune base de données à installer : la base est un fichier SQLite embarqué dans le binaire (ADR 0019), protoflix.db dans PROTOFLIX_DATA_DIR. DATA_DIR doit être sur un disque local : le serveur refuse de démarrer si la base est sur un montage SMB ou NFS, car le verrouillage de SQLite n'y est pas fiable ;
• FFmpeg et ffprobe, version 5.1 ou plus, vérifiée au démarrage ;
• pour l'accélération matérielle : pilotes et périphériques exposés (/dev/dri pour VA-API/QSV, runtime NVIDIA pour NVENC/NVDEC). Aucune combinaison n'est déclarée supportée avant test (docs/media/).

Pas de serveur de base de données, pas de Redis, pas de broker, pas de moteur de recherche externe (ADR 0013, 0019).

2. Configuration#

Configuration validée au démarrage : une combinaison invalide arrête le processus avec un message explicite. Valeurs par défaut sûres.

Les noms définitifs seront figés avec l'implémentation de internal/platform/config ; ce tableau est la référence de départ.

3. Répertoires#

Recommandation : TRANSCODE_DIR sur un disque rapide distinct ou un tmpfs de taille bornée, jamais sur le même système de fichiers que DATA_DIR sans quota : une saturation du disque bloquerait les écritures de la base.

4. Service systemd natif#

Utilisateur dédié sans shell ni répertoire personnel :

sudo useradd --system --no-create-home --shell /usr/sbin/nologin protoflix

Unité proposée (deploy/systemd/protoflix.service, à créer et tester) :

[Unit]
Description=ProtoFlix media server
After=network-online.target
Wants=network-online.target

[Service]
Type=notify
User=protoflix
Group=protoflix
# Accès GPU uniquement si l'accélération est activée :
# SupplementaryGroups=render video
EnvironmentFile=/etc/protoflix/protoflix.env
ExecStart=/usr/bin/protoflix serve
Restart=on-failure
TimeoutStopSec=30

StateDirectory=protoflix
CacheDirectory=protoflix
# Bibliothèques en lecture seule :
ReadOnlyPaths=/srv/media

NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectControlGroups=yes
RestrictSUIDSGID=yes
LockPersonality=yes
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
# À tester avec l'accélération matérielle avant activation :
# PrivateDevices=yes   (incompatible avec /dev/dri sans DeviceAllow=)
# SystemCallFilter=@system-service
MemoryMax=8G
TasksMax=512
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Type=notify suppose que le binaire signale sa disponibilité (sd_notify) une fois la base ouverte et les migrations appliquées ; sinon Type=exec (choix actuel de deploy/systemd/protoflix.service). À trancher à l'implémentation.

Le fichier protoflix.db est créé avec les permissions 0600, propriétaire protoflix (StateDirectoryMode=0750, UMask=0027). Il n'existe pas de mot de passe de base : la protection de la base repose sur les permissions du fichier et du répertoire.

5. Docker Compose#

Docker est une option, pas une obligation (accès GPU et montages parfois plus simples en natif).

Le fichier de référence est deploy/docker/compose.yaml : un conteneur server sans privilèges ni capacités, un conteneur updater pour les mises à jour (ADR 0027), et les volumes protoflix-data (base, images, sauvegardes) et protoflix-app (versions installées). Pour une carte Intel ou AMD, décommentez devices et group_add, avec le GID du groupe render de l'hôte. Pour Nvidia, décommentez gpus.

Points à vérifier : volume protoflix-data sur un disque local de l'hôte (pas un montage réseau), GID render différent selon l'hôte, montages SMB/NFS des bibliothèques déjà montés sur l'hôte puis exposés en :ro. Un seul coordinateur doit ouvrir le volume de données : ne jamais lancer deux conteneurs protoflix coordinateurs sur le même protoflix.db.

6. Reverse proxy#

Le serveur n'assure pas TLS lui-même en V1 : il écoute en HTTP sur loopback (ou un réseau Docker privé) derrière un reverse proxy.

Exigences :

• TLS terminé au proxy ; HSTS côté proxy une fois la configuration stable.
• PROTOFLIX_TRUSTED_PROXIES restreint à l'adresse du proxy ; sinon X-Forwarded-For est ignoré.
• Pas de mise en mémoire tampon des réponses de streaming et de SSE.
• Délais longs pour SSE ; requêtes Range transmises telles quelles.
• Taille maximale de corps modeste, sauf sur les routes d'envoi de « Ma bibliothèque » (envoi reprenable par morceaux, ADR 0018) : la taille de morceau est à fixer, et le proxy doit l'accepter.

Caddy#

media.example.org {
    reverse_proxy 127.0.0.1:8096 {
        flush_interval -1          # SSE et streaming sans tampon
        transport http {
            read_timeout 0         # flux longs
        }
    }
    request_body {
        max_size 10MB
    }
}

nginx#

server {
    listen 443 ssl;
    http2 on;
    server_name media.example.org;
    # ssl_certificate ... ; ssl_certificate_key ... ;

    client_max_body_size 10m;

    location / {
        proxy_pass http://127.0.0.1:8096;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;           # streaming
        proxy_request_buffering off;
        proxy_read_timeout 1h;         # SSE, lectures longues
    }

    location /api/v1/events {
        proxy_pass http://127.0.0.1:8096;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 24h;
    }
}

Le chemin SSE exact sera fixé par la spécification OpenAPI (api/openapi.yaml).

7. Exposition à distance#

• Ne jamais exposer directement le port 8096 sur Internet.
• Les endpoints d'administration restent accessibles via le même domaine mais exigent le rôle admin ; une option pour restreindre /api/v1/admin/* aux réseaux locaux est planifiée.
• /metrics n'est jamais exposé par le proxy (écoute séparée, voir observability.md).
• Le caractère local ou distant d'une connexion (droit « accès distant », code rapide) est déduit de l'IP client vue à travers PROTOFLIX_TRUSTED_PROXIES et de PROTOFLIX_LOCAL_NETWORKS. Un proxy mal déclaré fait apparaître tout le monde comme local : protoflix doctor doit le signaler.

8. Workers distants (planifié, ADR 0020)#

Par défaut, tous les rôles tournent dans un seul processus, le coordinateur, qui est le seul à ouvrir protoflix.db. Un worker distant (autre processus ou autre machine) n'accède jamais à la base : il parle au coordinateur par l'API interne.

• Coordinateur : PROTOFLIX_INTERNAL_ADDR (désactivé par défaut), par exemple 10.0.0.5:8097 sur le réseau local, ou 127.0.0.1:8097 pour un worker sur la même machine. Cette adresse n'est jamais publiée par le reverse proxy public. TLS obligatoire hors localhost (certificat fourni par l'administrateur ; mTLS à évaluer en phase 6).
• Enrôlement : protoflix worker enroll --name gpu-1, lancé sur le coordinateur, produit un jeton de worker (stocké haché, révocable dans l'administration). Le jeton est transmis au worker par fichier (PROTOFLIX_WORKER_TOKEN_FILE), jamais en ligne de commande.
• Correspondance des sources : chaque worker déclare source_id → racine locale pour les sources qu'il voit (le même NAS peut être monté à un autre chemin). Un worker ne réclame que les jobs des sources qu'il peut lire.
• Panne : un worker perdu laisse expirer son lease. Le job repart vers un autre worker, et une lecture transcodée par ce worker est renégociée par le client.

Exemple de worker GPU (cible, non testé) :

# /etc/protoflix/worker.env sur la machine GPU
PROTOFLIX_ROLES=worker
PROTOFLIX_COORDINATOR_URL=https://10.0.0.5:8097
PROTOFLIX_WORKER_TOKEN_FILE=/etc/protoflix/secrets/worker-token
PROTOFLIX_SOURCE_MAP=src_01JD…=/mnt/nas/films,src_01JE…=/mnt/nas/series
PROTOFLIX_TRANSCODE_DIR=/var/cache/protoflix/transcode

Le service systemd du worker reprend l'unité du serveur, avec SupplementaryGroups=render video et DeviceAllow=/dev/dri/renderD128 rw pour l'accès au GPU. Un worker n'a pas besoin de DATA_DIR contenant une base. Les noms des variables du worker seront figés à l'implémentation.

9. Module Téléchargements BitTorrent (si activé)#

Le client BitTorrent n'est pas embarqué dans le binaire : il tourne comme démon externe isolé (ADR 0017), sous un compte dédié, avec écriture limitée à DOWNLOADS_DIR, sans accès aux bibliothèques ni à la base. Port entrant fermé par défaut ; seed désactivé par défaut. Choix du démon et exemple de déploiement à fixer avec l'ADR.

• Alternatives à un port ouvert (VPN maillé, tunnel) : documentées comme choix de l'administrateur, non intégrées au produit.

10. Vérification après installation (planifiée)#

Commande protoflix doctor : base ouverte en lecture et en écriture, DATA_DIR sur un système de fichiers local (refus des montages SMB/NFS), mode WAL actif, PRAGMA quick_check, migrations à jour, permissions de protoflix.db (0600), FFmpeg trouvé et version, permissions des répertoires, espace disque, accès en lecture aux bibliothèques, présence d'en-têtes proxy attendus, avertissements de configuration (écoute non loopback sans proxy de confiance, fichiers de secrets trop permissifs, PROTOFLIX_INTERNAL_ADDR joignable depuis Internet ou sans TLS hors localhost).

Source : docs/operations/deployment.md, dans le dépôt de ProtoFlix.