Tdarr auf Ubuntu einrichten

Tdarr ist ein verteiltes System für Videoanalyse, Health Checks und automatisches Transcoding mit FFmpeg oder HandBrake. Laut offiziellem Projekt besteht Tdarr aus zwei Hauptkomponenten: Tdarr_Server als Zentrale und Tdarr_Node als verarbeitende Worker. Genau dadurch eignet es sich sehr gut, wenn ein Server die Verwaltung übernimmt und ein oder mehrere Systeme die eigentliche Rechenarbeit erledigen.

Ein typischer Anwendungsfall ist, große Film- oder Serienbibliotheken einheitlich zu optimieren, zum Beispiel in HEVC umzuwandeln, unnötige Untertitel oder Metadaten zu entfernen oder Health Checks über die Dateien laufen zu lassen. Wichtig ist aber: Tdarr ist extrem mächtig und kann bei falscher Konfiguration viel Last erzeugen oder Medien unnötig neu encodieren. Deshalb richten wir es bewusst sauber und kontrolliert ein.

In dieser Anleitung setzen wir Tdarr auf Ubuntu mit Docker Compose auf, binden Medien- und Cache-Pfade sauber ein, erklären Server und Node und schauen uns an, wie du gefahrlos mit einer ersten Bibliothek startest.

1. Voraussetzungen

Für diese Anleitung brauchst du:

• einen Ubuntu Server mit Docker und Docker Compose Plugin
• einen Medienpfad auf dem Host, zum Beispiel /srv/media
• einen separaten Cache-Ordner, zum Beispiel /srv/tdarr/cache
• genügend freien Speicherplatz für temporäre Dateien
• optional weitere Tdarr Nodes auf anderen Systemen

Wichtig: Der Cache-Ordner sollte nicht auf demselben knappen Volume liegen wie dein Root-Dateisystem, wenn du große Bibliotheken bearbeitest. Gerade bei 4K-Dateien können temporäre Dateien schnell sehr groß werden.

2. Verzeichnisse anlegen

Lege zuerst ein sauberes Arbeitsverzeichnis für Tdarr an:

mkdir -p ~/tdarr/server
mkdir -p ~/tdarr/configs
mkdir -p ~/tdarr/logs
mkdir -p /srv/tdarr/cache

Dein eigentlicher Medienpfad kann natürlich schon existieren. In dieser Anleitung verwenden wir exemplarisch:

/srv/media

3. Docker Compose Datei erstellen

Für ein einfaches Setup mit Server und lokalem Node reicht eine gemeinsame Compose-Datei. Ein praxistauglicher Start sieht so aus:

services:
  tdarr:
    image: ghcr.io/haveagitgat/tdarr:latest
    container_name: tdarr
    restart: unless-stopped
    ports:
      - "8265:8265"
      - "8266:8266"
    environment:
      - TZ=Europe/Zurich
      - PUID=1000
      - PGID=1000
      - UMASK_SET=002
      - serverIP=0.0.0.0
      - serverPort=8266
      - webUIPort=8265
      - internalNode=true
      - inContainer=true
      - ffmpegVersion=6
      - nodeName=MainNode
    volumes:
      - ~/tdarr/server:/app/server
      - ~/tdarr/configs:/app/configs
      - ~/tdarr/logs:/app/logs
      - /srv/media:/media
      - /srv/tdarr/cache:/temp

Die wichtigsten Mounts dabei:

• /app/server für Tdarr-Serverdaten
• /app/configs für Konfigurationen
• /app/logs für Logs
• /media als eingebundener Medienpfad
• /temp als Transcode-Cache

Wenn du GPU-Transcoding nutzen willst, kommen je nach Hardware zusätzliche Docker-Optionen hinzu. Für den Einstieg würde ich aber bewusst zuerst CPU-basiert und kontrolliert starten.

4. Container starten

Speichere die Datei als docker-compose.yml und starte Tdarr:

cd ~/tdarr
docker compose up -d

Prüfe danach kurz, ob der Container läuft:

docker compose ps

Wenn alles sauber läuft, erreichst du die Weboberfläche danach unter:

http://server.example.com:8265

5. Logs prüfen

Gerade beim ersten Start solltest du direkt einen Blick in die Logs werfen:

docker compose logs -f tdarr

Besonders wichtig sind hier Hinweise auf:

• fehlende Schreibrechte
• ungültige Pfade
• Node-Verbindungsprobleme
• FFmpeg- oder Hardware-Fehler

Viele Tdarr-Probleme sind am Anfang schlicht Pfad- oder Rechteprobleme. Es lohnt sich also, das direkt sauber zu prüfen.

6. Erste Bibliothek anlegen

Öffne die Weboberfläche und lege deine erste Library an. Wichtig ist dabei, dass du in Tdarr den Containerpfad verwendest, nicht den Hostpfad.

Wenn dein Hostpfad also

/srv/media

lautet und im Container nach /media gemountet ist, musst du in Tdarr den Bibliothekspfad entsprechend als Unterpfad von /media angeben, zum Beispiel:

/media/movies

Genau hier passieren sehr oft die ersten Fehler. Tdarr kann nur mit Pfaden arbeiten, die aus Sicht des Containers wirklich existieren.

7. Cache-Pfad richtig setzen

Der Cache-Pfad ist besonders wichtig, weil Tdarr dort während Health Checks und Transcodes arbeitet. In deinem Compose-Beispiel ist dafür vorgesehen:

/srv/tdarr/cache

Im Container entspricht das:

/temp

Achte darauf, dass dieser Ordner ausreichend Platz hat und schreibbar ist. Wenn hier Rechte oder Speicherplatz nicht stimmen, bleiben Jobs hängen oder brechen scheinbar „grundlos“ ab.

8. Warum du nicht sofort alle Plugins aktivieren solltest

Das offizielle Projekt beschreibt Tdarr als hochgradig modular mit Plugin-Stacks. Genau das ist die Stärke, aber auch die Gefahr. Wer sofort mehrere aggressive Plugins kombiniert, verarbeitet schnell viel Material anders als beabsichtigt.

Mein klarer Rat für den Einstieg:

• erst mit einer kleinen Testbibliothek arbeiten
• zuerst nur Health Checks oder einen sehr einfachen Transcode testen
• Ergebnisse kontrollieren, bevor du die volle Bibliothek freigibst
• nicht direkt mehrere gleichzeitige Worker aktivieren

Gerade bei Kundenumgebungen ist dieses vorsichtige Vorgehen extrem wichtig.

9. Ein sinnvoller erster Plugin-Ansatz

Ein typischer, relativ kontrollierter Start ist zum Beispiel:

• zuerst Health Check aktivieren
• dann nur nicht-HEVC-Dateien in HEVC umwandeln
• unnötige Untertitel oder Metadaten erst später angehen

Laut Projekt-README sind genau solche Plugin-Stacks der Kern von Tdarr. Wichtig ist aber, dass du jeden Schritt bewusst testest und nicht nur „irgendeinen populären Stack“ blind übernimmst.

10. Rechte und Besitzverhältnisse prüfen

Wenn Tdarr Dateien lesen, aber nicht zurückschreiben kann, liegt das fast immer an Rechten oder falschen Benutzer-IDs. Prüfe auf dem Host deshalb:

id
ls -ld /srv/media
ls -ld /srv/tdarr/cache

Die in Docker gesetzten Werte für PUID und PGID müssen zu einem Benutzer passen, der auf Medien- und Cachepfad wirklich zugreifen darf.

11. Weitere Nodes hinzufügen

Eine große Stärke von Tdarr ist die Verteilung auf mehrere Nodes. Das bedeutet: Ein zentraler Server verwaltet die Jobs, andere Geräte können die eigentliche Verarbeitung übernehmen.

Das lohnt sich besonders, wenn du:

• einen kleinen Server für die Verwaltung hast
• aber stärkere Desktops oder Workstations zum Encodieren nutzen willst
• oder verschiedene Systeme mit unterschiedlicher Hardware beschleunigen möchtest

Wichtig ist dann, dass alle Nodes die Medienpfade konsistent sehen. Unterschiedliche Pfadstrukturen zwischen Server und Node sind eine häufige Fehlerquelle.

12. Sicherheit und Veröffentlichung

Tdarr ist ein mächtiges Admin-Tool und sollte nicht unnötig offen im Internet erreichbar sein. Wenn du die Oberfläche von außen brauchst, würde ich sie nur abgesichert veröffentlichen, zum Beispiel:

• nur intern im LAN
• über VPN
• hinter einem Reverse Proxy mit zusätzlicher Anmeldung
• oder zusammen mit Authelia / Access-Schutz

Ein offen erreichbares Tdarr-WebUI auf Port 8265 würde ich für Kundenumgebungen klar vermeiden.

13. Updates einspielen

Updates laufen bei Docker-Setups klassisch über neue Images:

cd ~/tdarr
docker compose pull
docker compose up -d

Prüfe danach wieder kurz Status und Logs:

docker compose ps
docker compose logs --tail=50 tdarr

Wichtig ist dabei: Gerade bei Tdarr sollten Server und Nodes versionsmäßig zusammenpassen. Mischstände führen öfter zu seltsamen Effekten als bei einfachen Single-Container-Apps.

14. Fazit

Tdarr ist ein sehr starkes Werkzeug, wenn du Medienbibliotheken systematisch analysieren, prüfen und optimieren willst. Gerade für größere Sammlungen oder wiederkehrende Standards ist der Ansatz mit zentralem Server und optionalen Nodes extrem praktisch.

Der Schlüssel zu einem stabilen Setup liegt aber nicht nur in der Installation, sondern in sauberen Pfaden, korrekten Rechten und einem vorsichtigen Start mit kleinen Testmengen. Wenn diese Basis stimmt, kann Tdarr sehr viel Arbeit automatisieren.

Tipp:
Wenn du das für einen Kunden einrichtest, starte nicht direkt auf der kompletten Bibliothek. Richte zuerst eine kleine Test-Library ein und kontrolliere die ersten Durchläufe manuell. Das spart im Zweifel sehr viel Ärger.