TubeArchivist mit Docker installieren: Selbstgehosteter YouTube-Archivier

YouTube-Kanäle verschwinden, Videos werden gelöscht, Algorithmen entscheiden über die Sichtbarkeit von Inhalten – wer langfristig auf seine Videosammlung zugreifen möchte, sollte sich nicht auf die Plattform verlassen. TubeArchivist ist ein selbstgehosteter Medienserver mit über 8.100 GitHub-Stars (Stand Juni 2026), der YouTube-Kanäle abonniert, Videos samt vollständiger Metadaten über yt-dlp herunterlädt und sie in einem Elasticsearch-Index durchsuchbar macht – inklusive Untertitel und Kommentare. Die Oberfläche ist eine moderne React-App, der Betrieb läuft ausschließlich per Docker. Diese Anleitung zeigt dir, wie du den Stack aus drei Containern auf einem beliebigen Linux-Host in etwa 20 Minuten zum Laufen bringst.

Voraussetzungen

1. Linux-Host (Bare-Metal, VM, VPS oder NAS mit Docker-Unterstützung) – Ubuntu/Debian empfohlen
2. Docker Engine 20.10+ und das Docker Compose Plugin v2 (docker compose) installiert – falls nicht vorhanden, siehe Docker und Docker Compose auf Linux installieren
3. Mindestens 2 GB RAM (4 GB+ empfohlen für mittlere bis große Sammlungen), mindestens 2 CPU-Kerne
4. Ausreichend Festplattenplatz für das Videoarchiv – je nach Sammlung sind das schnell hunderte GB bis mehrere TB
5. Internetzugang für den Image-Pull und YouTube-Downloads
6. Optional: Reverse Proxy (Nginx, Traefik oder Caddy) für HTTPS und einen eigenen Domainnamen – Grundlagen dazu in der Anleitung zu Caddy als Reverse Proxy mit automatischem HTTPS
7. Auf ARM64-Hosts (Raspberry Pi 4/5, Apple Silicon): das offizielle Elasticsearch-Image (elasticsearch:8.19.0) statt bbilly1/tubearchivist-es verwenden – das TubeArchivist-eigene ES-Image ist ausschließlich für amd64 gebaut

Eckdaten im Überblick

Schritt 1: Kernel-Parameter prüfen und Projektordner anlegen

Elasticsearch benötigt einen erhöhten Kernel-Parameter für virtuelle Speicherbereiche. Ohne diesen Schritt startet der ES-Container nicht und gibt die Fehlermeldung „max virtual memory areas vm.max_map_count [65530] is too low" aus. Setze den Wert dauerhaft:

# Aktuellen Wert prüfen
sysctl vm.max_map_count

# Dauerhaft setzen (Wert in /etc/sysctl.conf eintragen)
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# Prüfen
sysctl vm.max_map_count

Auf WSL (Windows Subsystem for Linux) trägst du den Wert stattdessen in %USERPROFILE%\.wslconfig ein. Lege anschließend den Projektordner an:

sudo mkdir -p /opt/tubearchivist
sudo chown $USER:$USER /opt/tubearchivist
cd /opt/tubearchivist

Verifizieren: sysctl vm.max_map_count muss vm.max_map_count = 262144 ausgeben. Der Ordner /opt/tubearchivist existiert und gehört deinem Benutzer (ls -la /opt/ | grep tubearchivist).

Schritt 2: Umgebungsvariablen in der .env-Datei setzen

Passwörter und hostspezifische Einstellungen gehören nicht in die compose.yaml, sondern in eine separate .env-Datei. Die wichtigste Variable ist TA_HOST: Sie muss exakt dem URL-Origin entsprechen, von dem du auf TubeArchivist zugreifst – inklusive http:// oder https://, korrektem Hostnamen und Port, ohne abschließenden Slash. Ein falscher Wert führt zu CSRF-Fehlern oder endlosen Redirect-Schleifen beim Login.

# /opt/tubearchivist/.env

# Pflichtfelder – ALLE anpassen!
TA_HOST=http://192.168.1.100:8000        # Exakte URL (IP oder Hostname), kein Trailing-Slash
TA_USERNAME=tubearchivist                 # Initialer Admin-Benutzername
TA_PASSWORD=MeinSicheresPasswort2026!     # Initiales Admin-Passwort, nach dem ersten Login ändern
ELASTIC_PASSWORD=MeinESPasswort2026!      # Elasticsearch-Passwort – MUSS in beiden Diensten identisch sein

# Empfohlene optionale Einstellungen
TZ=Europe/Berlin                          # Zeitzone für den internen Scheduler
HOST_UID=1000                             # UID deines Benutzers (id -u)
HOST_GID=1000                             # GID deiner Gruppe (id -g)
TA_AUTO_UPDATE_YTDLP=release              # yt-dlp automatisch auf neue Stable-Versionen aktualisieren

Deinen UID und GID findest du mit dem Befehl id. Schütze die Datei anschließend vor unbefugtem Lesen:

chmod 600 /opt/tubearchivist/.env

Verifizieren: cat /opt/tubearchivist/.env zeigt alle Werte korrekt. ls -la /opt/tubearchivist/.env zeigt Rechte -rw-------. Prüfe nochmals, dass ELASTIC_PASSWORD in beiden Vorkommen (für die App und für ES) identisch ist – ein Mismatch führt zu stillen Verbindungsfehlern.

Schritt 3: compose.yaml erstellen

Der Stack besteht aus drei Diensten: der TubeArchivist-App, Redis als Task-Queue und Cache sowie Elasticsearch als Suchindex. Redis und Elasticsearch werden nur container-intern exponiert (expose, nicht ports), da von außen kein direkter Zugriff nötig ist. Named Volumes sind für Elasticsearch ausdrücklich empfohlen – Bind Mounts führen dort häufig zu Berechtigungsfehlern. Weitere Hintergründe zu Volumes und Netzwerken findest du in der Anleitung Docker-Netzwerke und Volumes richtig nutzen.

# /opt/tubearchivist/compose.yaml
services:
  tubearchivist:
    container_name: tubearchivist
    image: bbilly1/tubearchivist:latest
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - media:/youtube
      - cache:/cache
    environment:
      - ES_URL=http://archivist-es:9200
      - REDIS_CON=redis://archivist-redis:6379
      - HOST_UID=${HOST_UID}
      - HOST_GID=${HOST_GID}
      - TA_HOST=${TA_HOST}
      - TA_USERNAME=${TA_USERNAME}
      - TA_PASSWORD=${TA_PASSWORD}
      - ELASTIC_PASSWORD=${ELASTIC_PASSWORD}
      - TZ=${TZ}
      - TA_AUTO_UPDATE_YTDLP=${TA_AUTO_UPDATE_YTDLP:-release}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/api/health/"]
      interval: 2m
      timeout: 10s
      retries: 3
      start_period: 30s
    depends_on:
      - archivist-es
      - archivist-redis

  archivist-redis:
    image: redis:latest
    container_name: archivist-redis
    restart: unless-stopped
    expose:
      - "6379"
    volumes:
      - redis:/data
    depends_on:
      - archivist-es

  archivist-es:
    # AMD64: bbilly1/tubearchivist-es (getestete ES-8-Version, vorkonfiguriert)
    # ARM64 (Raspberry Pi, Apple Silicon): elasticsearch:8.19.0 verwenden!
    image: bbilly1/tubearchivist-es
    container_name: archivist-es
    restart: unless-stopped
    environment:
      - "ELASTIC_PASSWORD=${ELASTIC_PASSWORD}"
      - "ES_JAVA_OPTS=-Xms1g -Xmx1g"
      - "xpack.security.enabled=true"
      - "discovery.type=single-node"
      - "path.repo=/usr/share/elasticsearch/data/snapshot"
    ulimits:
      memlock:
        soft: -1
        hard: -1
    volumes:
      - es:/usr/share/elasticsearch/data
    expose:
      - "9200"

volumes:
  media:
  cache:
  redis:
  es:

Hinweis zu ES_JAVA_OPTS: Der Wert -Xms1g -Xmx1g reserviert 1 GB Heap für die JVM. Auf Hosts mit weniger als 4 GB RAM kannst du auf -Xms512m -Xmx512m reduzieren; auf leistungsstarken Servern empfiehlt sich -Xms2g -Xmx2g. Faustregel: nie mehr als die Hälfte des verfügbaren RAM.

Verifizieren: docker compose -f /opt/tubearchivist/compose.yaml config gibt die aufgelöste Konfiguration ohne Fehler aus. Alle ${…}-Variablen müssen durch die Werte aus der .env ersetzt sein.

Schritt 4: Stack starten

Starte den Stack aus dem Projektordner heraus. Docker lädt die Images beim ersten Start automatisch herunter (insgesamt ca. 500–700 MB je nach Architektur):

cd /opt/tubearchivist
docker compose up -d

Elasticsearch braucht beim allerersten Start etwas länger, um seinen Index zu initialisieren. TubeArchivist wartet dank depends_on und dem Healthcheck, bis alle Abhängigkeiten bereit sind. Verfolge den Startvorgang mit:

# Alle Container im Blick behalten
docker compose logs -f

# Nur Elasticsearch (bei Startproblemen)
docker compose logs -f archivist-es

# Nur TubeArchivist
docker compose logs -f tubearchivist

Verifizieren: Nach 1–2 Minuten zeigt docker compose ps für alle drei Container den Status running (TubeArchivist nach vollständiger Initialisierung: healthy). Die erwartete Ausgabe sieht in etwa so aus:

NAME               IMAGE                         STATUS
tubearchivist      bbilly1/tubearchivist:latest   Up 2 minutes (healthy)
archivist-redis    redis:latest                   Up 2 minutes
archivist-es       bbilly1/tubearchivist-es       Up 2 minutes

Zusätzlich: curl -s http://localhost:8000/api/health/ sollte {"status": "OK"} zurückgeben.

Schritt 5: Erst-Einrichtung im Browser

Öffne die URL, die du in TA_HOST eingetragen hast (z. B. http://192.168.1.100:8000), im Browser. Du siehst die Login-Seite von TubeArchivist.

1. Melde dich mit dem Benutzernamen und Passwort an, die du in TA_USERNAME und TA_PASSWORD gesetzt hast.
2. Passwort sofort ändern: Der Wert aus TA_PASSWORD wird nur beim allerersten Start ausgewertet, um den Admin-Account zu erstellen. Danach wird die Variable ignoriert. Ändere das Passwort unter Einstellungen → Benutzer.
3. Navigiere zu Einstellungen → Application und prüfe, ob Zeitzone und Download-Pfade deinen Erwartungen entsprechen.

Einen Kanal abonnierst du über die Suche: Gib die YouTube-Kanal-URL oder -ID ein, klicke auf „Subscribe". Wichtig: Das Abonnieren lädt keine bereits vorhandenen Videos herunter – es registriert den Kanal nur für zukünftige Downloads. Um den gesamten bisherigen Kanalbestand zu archivieren, navigiere zum Kanal und wähle „Download entire channel", um alle Videos in die Download-Queue einzutragen. Bei großen Kanälen mit hunderten Videos kann das mehrere Stunden dauern.

Verifizieren: Die TubeArchivist-Oberfläche lädt vollständig und ohne Fehler im Browser. Du kannst dich einloggen, die Dashboard-Seite erscheint, und unter Settings → Application ist die Verbindung zu Elasticsearch als „connected" markiert.

Schritt 6: Reverse Proxy und HTTPS einrichten (optional, empfohlen)

Für den Zugriff über eine eigene Domain oder aus dem Internet solltest du TubeArchivist hinter einen Reverse Proxy mit HTTPS stellen. Konfiguriere zunächst deinen Proxy (z. B. Caddy, Traefik oder Nginx Proxy Manager), dann passe TA_HOST in der .env auf die neue URL an – zum Beispiel https://tube.meinedomain.de. Starte den Stack danach neu:

cd /opt/tubearchivist
# .env anpassen: TA_HOST=https://tube.meinedomain.de
docker compose up -d --force-recreate tubearchivist

Der interne Port 8000 wird an den Proxy weitergeleitet. TA_HOST muss bei HTTPS zwingend mit https:// beginnen. Einen soliden Einstieg in Reverse-Proxy-Setups bietet die Anleitung Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten.

Verifizieren: Aufruf der externen HTTPS-URL liefert die TubeArchivist-Login-Seite. Das Browser-Schloss ist geschlossen (gültiges TLS-Zertifikat). docker compose logs tubearchivist zeigt keine CSRF- oder Origin-Fehler.

Schritt 7: Updates und Backups

TubeArchivist prüft täglich auf neue Versionen und zeigt einen Hinweis im Interface an. Ein Update führst du mit zwei Befehlen durch:

cd /opt/tubearchivist
docker compose pull
docker compose up -d

Docker ersetzt nur Container, deren Image sich geändert hat. Daten in Named Volumes bleiben dabei vollständig erhalten. Zum Sichern des Elasticsearch-Index empfiehlt sich ein regelmäßiger Snapshot (TubeArchivist nutzt den Pfad /usr/share/elasticsearch/data/snapshot). Das Videoarchiv im media-Volume lässt sich mit einem externen Backup-Tool wie Restic sichern – eine Anleitung dazu findest du unter Restic Backup auf Linux und Windows einrichten und automatisieren.

Verifizieren: Nach dem Update zeigt docker compose ps alle Container als running. Im TubeArchivist-Interface unter Settings ist die angezeigte Versionsnummer auf dem neuen Stand.

Troubleshooting: Typische Fehler

1. „max virtual memory areas vm.max_map_count [65530] is too low" – Elasticsearch startet nicht. Ursache: Kernel-Parameter zu niedrig. Fix: dauerhaft über /etc/sysctl.conf wie in Schritt 1 beschrieben setzen (vm.max_map_count=262144).
2. „failed to create shim / error setting rlimits" – Docker kann die ulimits für Elasticsearch nicht setzen. Tritt häufig auf NAS-Systemen oder bestimmten Cloud-VMs auf. Fix: Den ulimits-Block komplett aus dem archivist-es-Service in der compose.yaml entfernen und docker compose up -d neu ausführen.
3. CSRF-Fehler oder Redirect-Schleife beim Login – Ursache: TA_HOST stimmt nicht mit dem tatsächlich aufgerufenen URL-Origin überein. Fix: TA_HOST in der .env auf exakt die URL setzen, die der Browser in der Adressleiste zeigt (Protokoll, Hostname, Port, kein Trailing-Slash). Stack neu starten.
4. Verbindung zu Elasticsearch schlägt still fehl – Ursache: ELASTIC_PASSWORD ist im tubearchivist-Dienst und im archivist-es-Dienst unterschiedlich. Fix: Beide Werte in der .env angleichen, Stack neu starten. Logs prüfen mit docker compose logs tubearchivist.
5. „disk usage exceeded flood-stage watermark" – Elasticsearch sperrt den Index automatisch, wenn die Festplattenauslastung 95 % übersteigt. Fix: Speicherplatz freimachen, dann Elasticsearch-Index manuell entsperren oder auf freieren Speicher migrieren.
6. YouTube-Throttling: HTTP 403, extrem langsame Downloads – YouTube erkennt Bot-Traffic und drosselt. Maßnahmen: TA_AUTO_UPDATE_YTDLP=release setzen, längere Pausen zwischen Downloads einplanen, Cookies einbinden, POT-Integration prüfen.
7. ARM64-Fehler beim ES-Container – bbilly1/tubearchivist-es ist ausschließlich für amd64 gebaut. Fix: Im archivist-es-Dienst das Image auf elasticsearch:8.19.0 ändern.
8. Berechtigungsfehler auf dem ES-Volume – Tritt auf, wenn ein Bind Mount statt eines Named Volume verwendet wird. Fix: Named Volume in der compose.yaml verwenden.

Häufige Fragen

Wie ändere ich das Admin-Passwort nach dem ersten Start?

Die Variable TA_PASSWORD wird nur beim allerersten Start ausgewertet, um den initialen Admin-Account anzulegen. Danach hat sie keine Wirkung mehr. Das Passwort änderst du im laufenden Betrieb im Webinterface unter Einstellungen → Benutzer.

Was passiert, wenn ich einen Kanal abonniere?

Das Abonnieren registriert den Kanal für zukünftige automatische Downloads – bestehende Videos werden dabei nicht heruntergeladen. Um den gesamten bisherigen Kanalbestand zu archivieren, musst du auf der Kanalseite explizit „Download entire channel" auswählen. Wenn du einen Kanal deabonnierst, bleiben bereits heruntergeladene Videos erhalten.

Kann TubeArchivist hinter einem Reverse Proxy mit HTTPS betrieben werden?

Ja, das ist sogar empfohlen. Setze TA_HOST auf die externe URL mit https://-Präfix (z. B. https://tube.meinedomain.de). Der interne Port 8000 wird vom Proxy weitergeleitet. Die URL in TA_HOST muss exakt der URL entsprechen, die der Browser aufruft – andernfalls kommt es zu CSRF-Fehlern.

Wie integriere ich TubeArchivist mit Jellyfin oder Plex?

Es existieren offizielle Plugins für beide Medienserver: tubearchivist/tubearchivist-jf-plugin für Jellyfin und tubearchivist-plex für Plex. Die heruntergeladenen Videos liegen im media-Volume (Pfad /youtube) und lassen sich direkt als Bibliothek einbinden. Jellyfin selbst kannst du ebenfalls per Docker betreiben – eine Anleitung liefert Jellyfin mit Docker: eigener Media-Server ohne Abo.

Wie viel Speicherplatz wird benötigt?

Das hängt vollständig von der Anzahl und Auflösung der archivierten Videos ab. Videos werden nach dem Schema <channel-id>/<video-id>.mp4 abgelegt – statische Pfade, die sich auch bei Metadaten-Änderungen nicht verschieben. Empfehlung: das media-Volume auf ein separates, großes Laufwerk legen und den verfügbaren Speicher im Auge behalten (Flood-Stage-Watermark bei 95 %).

Kann ich den Redis-Container mit anderen Projekten teilen?

Nein. Die offizielle Dokumentation hält explizit fest, dass das Teilen des Redis-Containers mit anderen Anwendungen nicht unterstützt wird und zu unvorhersehbaren Fehlern führen kann. Für jeden TubeArchivist-Stack ist eine dedizierte Redis-Instanz vorgesehen.

Gibt es Browser-Erweiterungen für TubeArchivist?

Ja. Es gibt offizielle Browser-Extensions für Firefox und Chrome, mit denen du Videos direkt von der YouTube-Seite heraus in die TubeArchivist-Download-Queue hinzufügen kannst. Außerdem ist eine SponsorBlock-Integration eingebaut, die Sponsor-Segmente automatisch markiert oder überspringt.

Fazit

TubeArchivist ist der aktuell ausgereifteste selbstgehostete YouTube-Archivier: durchsuchbar bis in Untertitel und Kommentare, skalierbar auf 100.000+ Videos, mit aktiver Entwicklung und einem lebendigen Ökosystem aus Plugins. Der Einstieg ist mit dieser Anleitung in unter 30 Minuten erledigt. Der einzige relevante Einrichtungs-Trade-off ist der Ressourcenbedarf: Elasticsearch braucht ordentlich RAM. Wer das hat, bekommt dafür eine lokale Video-Bibliothek, die YouTube-unabhängig, vollständig durchsuchbar und langfristig kontrollierbar ist – und sich nahtlos in bestehende Medienserver-Setups mit Jellyfin oder Plex integriert. Für den produktiven Betrieb lohnt sich außerdem ein Blick auf die Anleitung Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only für den Produktivbetrieb.

Weiterführende Anleitungen und Quellen

1. Docker und Docker Compose auf Linux installieren (Ubuntu/Debian): die Self-Hosting-Grundlage
2. Docker-Netzwerke und Volumes richtig nutzen
3. Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten
4. Caddy als Reverse Proxy einrichten: Anfänger-Anleitung mit automatischem HTTPS
5. Jellyfin mit Docker: eigener Media-Server ohne Abo
6. Restic Backup auf Linux und Windows einrichten und automatisieren
7. Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only für den Produktivbetrieb

Quellen: TubeArchivist GitHub-Repository (README & compose.yaml) | Offizielle Dokumentation: Docker Compose Installation | Offizielle Dokumentation: Umgebungsvariablen | Offizielle Dokumentation: FAQ | Docker Hub: bbilly1/tubearchivist

Passende Anleitungen auf S-EDV

1. netcup Local Block Storage bestellen, einrichten und unter Linux einbinden
2. Linux 7.1-rc6 veröffentlicht: Kernel-Entwicklung stabilisiert sich nach KI-bedin
3. Linux-Kernel CVE-2026-23111: Ein-Zeichen-Fehler in nf_tables ermöglicht lokale R