Skip to content

About

Leichtgewichtige inotify-basierte Bridge, die fertige Dateien automatisch von einem Quell- in ein Zielverzeichnis verschiebt – das Bindeglied zwischen tw-recorder und yt-upload in der Media-Pipeline. Läuft als Docker-Image oder Bare-Metal (.deb).

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

fetchbridge 🌉🎬

fetchbridge ist ein leichtgewichtiger, Docker-basierter Hintergrunddienst zur automatisierten Überwachung von Verzeichnissen und zum Verarbeiten/Verschieben von Videodateien via inotify.

Er dient als intelligentes Bindeglied in Automated-Media-Pipelines – beispielsweise zwischen einem Stream-Recorder (tw-recorder) und einem Upload-Service (yt-upload).

Eine Übersicht der internen Architektur (Module, Datenfluss, Diagramm) findet sich in ARCHITECTURE.md.


🚀 Features

  • Echtzeit-Überwachung: Reagiert ohne Verzögerung auf Dateisystem-Events (IN_MOVED_TO, IN_CLOSE_WRITE) mittels inotify - über einen eigenen, abhängigkeitsfreien ctypes-Wrapper (inotify_tree.py), der neben Linux auch für FreeBSD ≥ 14.5 ausgelegt ist.
  • Intelligente RW/RO-Erkennung:
    • Read-Write (RW): Verschiebt Dateien direkt ins Zielverzeichnis und räumt leere Quellordner automatisch auf.
    • Read-Only (RO): Kopiert Dateien sicher, falls das Quellverzeichnis schreibgeschützt gemountet ist.
  • Initialer Scan: Verarbeitet beim Start automatisch alle bereits im Quellordner vorhandenen Videos.
  • Filter-Mechanismus: Ignoriert temporäre Downloads (.part, .ytdl, .tmp), versteckte Dateien sowie ununterstützte Formate.
  • Kollisionsschutz: Benennt Zieldateien bei Namensgleichheit automatisch um (video_1.mp4).
  • Hot-Reloading der Konfiguration: Überwacht die Konfigurationsdatei und übernimmt Änderungen automatisch im laufenden Betrieb (außer source_dir, das einen Neustart erfordert).
  • Minimales Docker-Image: Drei Varianten (Debian, Alpine, reines Python-Image) zur Auswahl.

🛠️ Voraussetzungen & Pfade

Der Container arbeitet intern mit zwei primären Datenpfaden:

Pfad im Container Funktion Standard-Format
/srv/media-pipeline/recordings Quellverzeichnis (Eingang für fetchbridge, geteilt mit tw-recorders STORAGE_DIR) .mkv, .mp4, .mov, .webm
/srv/media-pipeline/incoming Zielverzeichnis (Ausgang für Folge-Tools, geteilt mit yt-uploads IN_DIR) .mkv, .mp4, .mov, .webm
/log Log-Dateien (Optional, siehe unten) Logs / App-Output

📦 Schnellstart mit Docker Compose

Hier ist ein Beispiel für die Integration in eine bestehende docker-compose.yml:

services:
  fetchbridge:
    image: ghcr.io/chaos7x/fetchbridge:latest
    container_name: fetchbridge
    hostname: fetchbridge
    user: "11107:11108"
    restart: unless-stopped
    environment:
      - TZ=Europe/Berlin
      - PYTHONUNBUFFERED=1
      - LOG_LEVEL=INFO
    volumes:
      # EIN gemeinsamer Bind-Mount für recordings/ UND incoming/ statt zwei
      # getrennter Mounts - siehe "Warum ein einzelner Mount?" unten.
      - /srv/media-pipeline:/srv/media-pipeline:rw

⚠️ Warum ein einzelner Mount?

Zwei getrennte Bind-Mounts (recordings und incoming je einzeln eingebunden) sehen im Container zwar wie normale Unterordner desselben Baums aus, sind für den Kernel aber unterschiedliche Mount-Instanzen - os.rename() (der von mover.py bevorzugte atomare Pfad) scheitert dann mit EXDEV und fällt auf das langsamere Kopieren+Löschen zurück, selbst wenn beide Host-Verzeichnisse zufällig auf derselben Partition liegen. Das gilt für jede Art von getrennten Mounts gleichermaßen - egal ob zwei Docker-Volumes, zwei einzelne -v-Bind-Mounts oder zwei separate NFS-Exports. Ein einzelner Mount über den gemeinsamen Elternordner (wie oben) vermeidet das vollständig.

🔗 Interop mit Bare-Metal (gemeinsamer Host-Pfad)

user: "11107:11108" oben ist nur ein Platzhalter. Der Mount oben nutzt bereits denselben Host-Pfad /srv/media-pipeline, den auch die Bare-Metal-/.deb-Installationen von tw-recorder/yt-upload nutzen - Container und Bare-Metal teilen sich den Baum also ohne weitere Anpassung.

Der Ordner gehört dort root:media-pipeline mit Modus 2775 (setgid, bewusst ohne Sticky-Bit) - Schreib-/Löschrecht hängt also rein an der Gruppe, nicht an der UID oder dem Datei-Owner. Die GID im user:-Feld muss deshalb mit der echten Host-Gruppe übereinstimmen, sonst gibt's Permission denied:

getent group media-pipeline   # z.B. media-pipeline:x:998:

Die zweite Zahl in user: "<uid>:<gid>" durch diese echte GID ersetzen (z.B. user: "11107:998") - die UID (erste Zahl) ist frei wählbar, da sie für die Zugriffsrechte auf diese Verzeichnisse keine Rolle spielt.


🛠️ Bare-Metal-Installation (ohne Docker)

fetchbridge läuft auch direkt auf dem Host. Es hat keine Python-Abhängigkeiten außer der Standardbibliothek (inotify wird per ctypes direkt aus der libc angesprochen) - pip installiert nur das eigene Package:

apt install python3-pip python3-setuptools
cd /pfad/zu/fetchbridge
pip install --break-system-packages --no-deps .

Danach steht der Befehl fetchbridge systemweit zur Verfügung (fetchbridge --version zum Testen).

Die Logdatei landet je nach Umgebung automatisch am sinnvollsten Ort (/var/log/fetchbridge/, sofern beschreibbar und ein klassischer Syslog-Daemon läuft, sonst nur auf stdout/journald) - siehe log_file-Konfigurationsoption, falls ein fester Pfad gewünscht ist. Läuft ein Syslog-Daemon, rotiert die App die Datei bewusst nicht selbst (kein RotatingFileHandler) - das übernimmt das mitgelieferte /etc/logrotate.d/fetchbridge (nur im .deb-Paket enthalten; bei einer reinen pip-Installation ohne .deb selbst einrichten, falls gewünscht). Nur bei explizit gesetztem log_file oder einem gemounteten Docker-/log-Volume rotiert die App eigenständig, da dort sonst niemand rotieren würde.

Alternative: Fertiges Debian-Paket (.deb)

Jedes GitHub Release enthält zusätzlich ein fetchbridge_<version>_all.deb als Anhang - keine manuelle pip-Installation nötig:

wget https://github.com/chaos7x/fetchbridge/releases/latest/download/fetchbridge_<version>_all.deb
apt install ./fetchbridge_<version>_all.deb

Das Paket legt einen dedizierten Systemuser (fetchbridge) an und startet den Dienst bewusst nicht automatisch - erst /etc/fetchbridge/fetchbridge.conf (bzw. conf.d/) anpassen, dann:

systemctl enable --now fetchbridge

Devuan / Debian ohne systemd (sysvinit-core, OpenRC): Das Paket bringt zusätzlich ein klassisches /etc/init.d/fetchbridge-Skript mit, das postinst automatisch anstelle des systemd-Service registriert, wenn kein systemd läuft - ebenfalls deaktiviert (update-rc.d … defaults-disabled, kein Start beim Booten). Die mitgelieferte .service-Datei unter /usr/lib/systemd/system/ bleibt dort einfach ungenutzt liegen, wie bei Debian-Paketen üblich. Aktivieren und starten:

update-rc.d fetchbridge enable
service fetchbridge start

Alternative: FreeBSD-Paket (.pkg)

Jedes Release enthält neben den .deb-Dateien auch FreeBSD-Pakete, je eines für FreeBSD 14 und 15 (…-freebsd14.pkg / …-freebsd15.pkg, gebaut von freebsd/build-pkg.py). Sie hängen fest an Python 3.11 (python311), damit Interpreter und Python-Abhängigkeiten zusammenpassen:

pkg install python311
pkg add fetchbridge-<version>-freebsd14.pkg

Das Paket legt /etc/fetchbridge/fetchbridge.conf aus der Vorlage an (falls noch keine existiert), dazu den Dienstuser, die Gruppe media-pipeline und die Verzeichnisse unter /srv/media-pipeline, genau wie das Debian-Paket. Der Dienst wird dabei bewusst nicht aktiviert, die nötigen sysrc/service-Befehle zeigt pkg nach der Installation an. Noch nicht auf einem echten FreeBSD-System getestet.

Alternative: FreeBSD manuell (rc.d)

Für FreeBSD ≥ 14.5 (native inotify in der libc) liegt unter freebsd/rc.d/fetchbridge ein rc.d-Skript bei, das Pendant zum systemd-Service aus debian/. Ohne das fertige Paket geht die Einrichtung auch von Hand und aktiviert den Dienst ebenfalls nicht von selbst. Bisher nur gegen die Doku geschrieben, noch nicht auf einem echten FreeBSD-System getestet.

# Abhängigkeiten (py311 an die installierte Python-Version anpassen)
pkg install python3 py311-pip
cd /pfad/zu/fetchbridge
pip install --no-deps .

# Dienstuser und gemeinsame Pipeline-Gruppe (wie debian/postinst)
pw groupshow media-pipeline >/dev/null 2>&1 || pw groupadd media-pipeline
pw usershow fetchbridge >/dev/null 2>&1 || pw useradd fetchbridge -d /nonexistent -s /usr/sbin/nologin -G media-pipeline
install -d -o root -g media-pipeline -m 2775 /srv/media-pipeline /srv/media-pipeline/recordings /srv/media-pipeline/incoming
install -d /etc/fetchbridge

# rc.d-Skript installieren und aktivieren
install -m 755 freebsd/rc.d/fetchbridge /usr/local/etc/rc.d/fetchbridge
sysrc fetchbridge_enable=YES
service fetchbridge start

Vor dem service fetchbridge start wie unter Linux /etc/fetchbridge/fetchbridge.conf anlegen (Vorlage: fetchbridge.conf.example).

Das Skript startet fetchbridge -D über daemon(8) (Neustart bei Absturz, Userwechsel inkl. media-pipeline-Zusatzgruppe) und leitet die Ausgabe an syslog weiter (Tag fetchbridge, landet standardmäßig in /var/log/messages). Weitere Einstellungen (fetchbridge_runas, fetchbridge_args, fetchbridge_env) stehen im Kopf des Skripts.

Alternative: Standalone .pyz (kein pip/apt nötig)

./build-pyz.sh baut aus src/ ein einziges, selbst-enthaltenes fetchbridge.pyz - läuft auf jedem System mit einem nackten python3, ganz ohne vorherige pip install/apt install:

./build-pyz.sh
./fetchbridge.pyz --version

🐳 Docker-Image-Varianten

Dockerfile Basis Installationsweg
Dockerfile (Standard) debian:trixie-slim apt für python3, pip install --no-deps . für fetchbridge selbst
Dockerfile.alpine alpine:3 Wie oben, aber apk statt apt
Dockerfile.pyimg python:3-slim Ein einziger pip install .

⚙️ Konfiguration

Die Hauptkonfiguration erfolgt über /etc/fetchbridge/fetchbridge.conf (bzw. fetchbridge.conf.example als Vorlage). Zusätzlich wird /etc/fetchbridge/conf.d/*.conf eingelesen (alphabetisch, spätere Dateien überschreiben frühere Werte). Änderungen werden im laufenden Betrieb automatisch erkannt (Hash-Prüfung alle CONFIG_CHECK_INTERVAL Sekunden) - außer bei source_dir, das einen Neustart erfordert (InotifyTree ist fest an den Startpfad gebunden).

[general]
# Log-Level: DEBUG, INFO, WARNING, ERROR
# log_level = INFO
# Alternative dazu: die Umgebungsvariable DEBUG=true/yes/1 (wie bei
# tw-recorder/yt-upload) - siehe Umgebungsvariablen-Abschnitt, keine Config-Option.

# Fester Pfad für die Logdatei (bei explizitem log_file oder gemountetem
# /log-Docker-Volume rotierend, max. 10 MB, 5 Backups - läuft stattdessen ein
# klassischer Syslog-Daemon, übernimmt logrotate die Rotation, siehe README).
# Ohne diese Angabe wird automatisch geloggt, sobald /log tatsächlich als
# Docker-Volume gemountet ist (reines Vorhandensein des Verzeichnisses
# reicht nicht, siehe unten) oder ein klassischer Syslog-Daemon läuft -
# sonst nur nach stdout (journald/docker logs erfassen das bereits).
# log_file = /log/fetchbridge.log

# Quellverzeichnis, das überwacht wird (Änderung erfordert Neustart)
# source_dir = /srv/media-pipeline/recordings

# Zielverzeichnis, in das fertige Dateien verschoben/kopiert werden
# target_dir = /srv/media-pipeline/incoming


[mover]
# Kommagetrennte Liste erlaubter Datei-Endungen
# allowed_extensions = .mkv,.mp4,.mov,.webm

# Kommagetrennte Liste von Endungen, die als "noch nicht fertig" gelten
# temp_extensions = .part,.ytdl,.tmp,.temp

# Leere Quell-Unterordner nach dem Verschieben automatisch entfernen (true/false)
# cleanup_empty_dirs = false

CLI & Parameter

fetchbridge [-h] [-D] [--healthcheck] [-v]
  • -D, --daemon — Dämon-Modus: Dauerhafte Ordnerüberwachung (Standardmodus im Container, siehe entrypoint.sh)
  • --healthcheck — Prüft die Heartbeat-Datei, Exit-Code 0 (healthy) oder 1 (unhealthy). Für Docker HEALTHCHECK gedacht, läuft unabhängig vom Dämon-Prozess.
  • -v, --version — Versionsnummer anzeigen

Umgebungsvariablen

  • CONFIG_FILE — Standard /etc/fetchbridge/fetchbridge.conf
  • CONF_D_DIR — Standard /etc/fetchbridge/conf.d
  • SOURCE_DIR / TARGET_DIR — Fallback, falls nicht in der Config gesetzt. Standard /srv/media-pipeline/recordings (dasselbe Verzeichnis wie tw-recorders STORAGE_DIR) bzw. /srv/media-pipeline/incoming (dasselbe Verzeichnis wie yt-uploads IN_DIR), einheitlich für Docker und Bare-Metal. Das .deb-Postinst legt beide mit einer gemeinsamen Gruppe (media-pipeline) an, damit alle drei Dienste darauf zugreifen können.
  • ALLOWED_EXTENSIONS / TEMP_EXTENSIONS — Fallback, falls nicht in der Config gesetzt
  • LOG_LEVEL — Standard INFO
  • DEBUG — Standard 0. Auf true/1 setzen für erweiterte Log-Ausgaben; Alias für LOG_LEVEL=DEBUG (dieselbe Variable wie bei tw-recorder/yt-upload), eine explizit gesetzte log_level/LOG_LEVEL hat aber immer Vorrang.
  • LOG_FILE — Fallback, falls nicht in der Config gesetzt; siehe [general]-Sektion oben
  • CONFIG_CHECK_INTERVAL — Standard 15 (Sekunden zwischen Hash-Prüfungen der Config-Dateien)
  • HEARTBEAT_FILE — Standard /var/run/fetchbridge/fetchbridge.heartbeat, falls das Verzeichnis existiert (legen systemd-Unit, init.d- und rc.d-Skript an), sonst /tmp/fetchbridge.heartbeat
  • HEARTBEAT_MAX_AGE — Standard 60 (Sekunden, bevor --healthcheck als "unhealthy" gilt)

🏷️ Versionierung

Reguläre Releases folgen vX.Y.Z (SemVer) und entstehen manuell zusammen mit einer echten Code-Änderung.

Zusätzlich prüft ein monatlicher Workflow (os-patch-release.yml, 1. jeden Monats), ob das Debian-/Alpine-Basis-Image ungenutzte Security-Patches hat, die docker-refresh.yml's wöchentliches latest-Update zwar schon mitnimmt, die aber an den fixen vX.Y.Z-Tags vorbeilaufen (die frieren für immer auf ihrem Build-Zeitpunkt ein). Findet der Workflow etwas, hängt er eine vierte Versionsstelle an, die ausschließlich für solche reinen OS-Patch-Releases reserviert ist: v1.3.1 → v1.3.1.1 → v1.3.1.2 (jeweils ohne Code-Änderung, nur aktualisierte System-Pakete). Bleibt die vierte Stelle bei Nichts-zu-patchen-Läufen einfach aus, gibt es auch keinen neuen Tag - kein Rauschen in der Release-Historie.

Der nächste echte Code-Release setzt diese vierte Stelle nicht fort, sondern lässt sie weg: auf v1.3.1.2 folgt bei einer echten Änderung v1.3.2, nicht v1.3.2.0 oder v1.3.1.3.


🧑‍💻 Lokaler Build & Entwicklung

Ein lokales Image kann über das Build-Skript kompiliert werden:

./build.sh                    # Nutzt Name & Version aus pyproject.toml, Standard-Dockerfile
./build.sh 2.0.0               # Explizite Version, Standard-Dockerfile
./build.sh alpine               # Version aus pyproject.toml, Dockerfile.alpine
./build.sh 2.0.0 pyimg          # Explizite Version, Dockerfile.pyimg

Name und Standard-Version werden automatisch aus pyproject.toml gelesen - ein explizit übergebenes Versions-Argument überschreibt das.

Tests & Linting

apt install python3-pytest   # oder: pip install -r requirements-test.txt
pytest -v

ruff check src/fetchbridge/

📄 Lizenz

Dieses Projekt steht unter der GNU General Public License v3.0 (GPLv3).

About

Leichtgewichtige inotify-basierte Bridge, die fertige Dateien automatisch von einem Quell- in ein Zielverzeichnis verschiebt – das Bindeglied zwischen tw-recorder und yt-upload in der Media-Pipeline. Läuft als Docker-Image oder Bare-Metal (.deb).

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages