Wer langfristig auf eine Videosammlung zugreifen muss, etwa auf Schulungsvideos, archiviert sie lokal, da YouTube-Kanäle und Videos verschwinden können. TubeArchivist ist ein selbst gehosteter Medienserver, der YouTube-Kanäle abonniert, Videos samt Metadaten über yt-dlp herunterlädt und sie in einem Elasticsearch-Index durchsuchbar macht, inklusive Untertitel und Kommentare. Diese Anleitung richtet den Docker-Stack aus drei Containern auf einem Linux-Host in etwa 20 Minuten ein.

Voraussetzungen

Linux-Host (Bare-Metal, VM, VPS oder NAS mit Docker-Unterstützung) – Ubuntu/Debian empfohlen
Docker Engine 20.10+ und das Docker Compose Plugin v2 (docker compose) installiert – falls nicht vorhanden, siehe Docker und Docker Compose auf Linux installieren
Mindestens 2 CPU-Kerne und 4 GB RAM (Elasticsearch reserviert allein 1 GB Heap); 2 GB genügen nur mit reduziertem Heap für kleine Sammlungen
Ausreichend Festplattenplatz für das Videoarchiv , je nach Sammlung hunderte GB bis mehrere TB
Internetzugang für den Image-Pull und YouTube-Downloads
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
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

Eigenschaft	Wert
App-Image	`bbilly1/tubearchivist:v0.5.12` (Stand 30.09.2026)
ES-Image (amd64)	`bbilly1/tubearchivist-es`
ES-Image (ARM64)	`elasticsearch:8.19.0`
Redis-Image	`redis:8`
Webinterface-Port	8000 (Nginx-Reverse-Proxy vor uvicorn)
Elasticsearch-Port	9200 (nur container-intern)
Redis-Port	6379 (nur container-intern)
RAM	4 GB empfohlen (2 GB mit 512 MB ES-Heap)
Lizenz	GPL-3.0
Quellcode	github.com/tubearchivist/tubearchivist

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. Setzen Sie den Wert dauerhaft:

# Aktuellen Wert prüfen
sysctl vm.max_map_count

# Dauerhaft setzen (eigene Datei unter /etc/sysctl.d, gilt auch nach Neustart)
echo "vm.max_map_count=262144" | sudo tee /etc/sysctl.d/99-tubearchivist.conf
sudo sysctl --system

# Prüfen
sysctl vm.max_map_count

Legen Sie 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 Ihrem Benutzer (ls -la /opt/ | grep tubearchivist).

Schritt 2: Umgebungsvariablen in der .env-Datei setzen

Passwörter und hostspezifische Einstellungen gehören in eine separate .env-Datei. Die wichtigste Variable ist TA_HOST: Sie muss exakt der Adresse entsprechen, über die Sie TubeArchivist aufrufen, mit http:// oder https://, Hostname und Port, ohne abschließenden Schrägstrich. 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 Ihres Benutzers (id -u)
HOST_GID=1000                             # GID Ihrer Gruppe (id -g)
TA_AUTO_UPDATE_YTDLP=release              # yt-dlp automatisch auf neue Stable-Versionen aktualisieren

UID und GID liefert der Befehl id. Schützen Sie die Datei anschließend vor unbefugtem Lesen:

chmod 600 /opt/tubearchivist/.env

Verifizieren: ls -la /opt/tubearchivist/.env zeigt die Rechte -rw-------, cat zeigt alle Werte ohne Platzhalter. Die compose.yaml liest ELASTIC_PASSWORD für App und Elasticsearch aus derselben Variable, beide Werte sind damit identisch.

Schritt 3: compose.yaml erstellen

Der Stack besteht aus der TubeArchivist-App, Redis als Warteschlange und Cache sowie Elasticsearch als Suchindex. Redis und Elasticsearch sind nur im Container-Netz erreichbar (expose statt ports). Für Elasticsearch empfiehlt das Projekt Named Volumes, Bind Mounts führen dort häufig zu Berechtigungsfehlern. Hintergründe erklärt die Anleitung Docker-Netzwerke und Volumes richtig nutzen.

# /opt/tubearchivist/compose.yaml
services:
  tubearchivist:
    container_name: tubearchivist
    image: bbilly1/tubearchivist:v0.5.12
    restart: unless-stopped
    ports:
      - "8000:8000"   # mit Reverse Proxy auf demselben Host: "127.0.0.1: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:8
    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:8.19.0
    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 reduzieren Sie auf -Xms512m -Xmx512m, bei großen Sammlungen erhöhen Sie auf -Xms2g -Xmx2g. Faustregel: höchstens 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

Starten Sie den Stack im Projektordner. Docker lädt die Images beim ersten Start automatisch herunter:

cd /opt/tubearchivist
docker compose up -d

Elasticsearch braucht beim ersten Start länger, um den Index anzulegen; TubeArchivist wiederholt den Verbindungsaufbau, bis der Suchindex bereit ist. Den Startvorgang verfolgen Sie 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:v0.5.12      Up 2 minutes (healthy)
archivist-redis    redis:8                            Up 2 minutes
archivist-es       bbilly1/tubearchivist-es:8.19.0    Up 2 minutes

Zusätzlich liefert curl -s http://localhost:8000/api/health/ eine Antwort mit Status „OK“.

Schritt 5: Erst-Einrichtung im Browser

Öffnen Sie die in TA_HOST eingetragene URL (z. B. http://192.168.1.100:8000) im Browser. Die Anmeldeseite von TubeArchivist erscheint.

Melden Sie sich mit den Werten aus TA_USERNAME und TA_PASSWORD an.
Passwort sofort ändern: Der Wert aus TA_PASSWORD wird nur beim allerersten Start ausgewertet, um den Admin-Account zu erstellen. Ändern Sie das Passwort unter Einstellungen → Benutzer.
Prüfen Sie unter Einstellungen → Application Download-Format und Zeitpläne.

Einen Kanal abonnieren Sie, indem Sie die YouTube-Kanal-URL oder -ID eingeben und auf „Subscribe“ klicken. Das Abonnieren registriert den Kanal nur für künftige Downloads. Für den bisherigen Bestand wählen Sie auf der Kanalseite „Download entire channel“; bei hunderten Videos dauert das mehrere Stunden.

Verifizieren: Die Anmeldung gelingt, die Startseite erscheint ohne Fehlermeldung. Nach dem Abonnieren eines Testkanals steht der Kanal unter „Channels“, und docker compose logs tubearchivist zeigt keine Verbindungsfehler zu Elasticsearch oder Redis.

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

Für den Zugriff über eine eigene Domain oder aus dem Internet stellen Sie TubeArchivist hinter einen Reverse Proxy mit HTTPS (z. B. Caddy, Traefik oder Nginx Proxy Manager). Läuft der Proxy auf demselben Host, binden Sie Port 8000 an 127.0.0.1, damit TubeArchivist nicht zusätzlich unverschlüsselt erreichbar ist. Passen Sie dann TA_HOST in der .env an, etwa auf https://tube.meinedomain.de, und erstellen Sie den Container neu:

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

TA_HOST muss bei HTTPS mit https:// beginnen. Einen Einstieg bietet die Anleitung Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten.

Verifizieren: Die externe HTTPS-URL liefert die Anmeldeseite mit gültigem Zertifikat. docker compose logs tubearchivist zeigt keine CSRF- oder Origin-Fehler.

Schritt 7: Updates und Backups

TubeArchivist zeigt neue Versionen in der Oberfläche an. Lesen Sie vor dem Update die Release Notes, tragen Sie den neuen Tag in der compose.yaml ein und führen Sie aus:

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 erhalten. Den Elasticsearch-Index sichern Sie über die Snapshot-Funktion in den Einstellungen (Pfad /usr/share/elasticsearch/data/snapshot), das Videoarchiv im media-Volume mit einem Backup-Werkzeug wie Restic, siehe Restic Backup auf Linux und Windows einrichten und automatisieren.

Verifizieren: Nach dem Update zeigt docker compose ps alle Container als running. Die in der Oberfläche angezeigte Versionsnummer entspricht dem neuen Tag.

Troubleshooting: Typische Fehler

„max virtual memory areas vm.max_map_count [65530] is too low“: Elasticsearch startet nicht. Lösung: Wert wie in Schritt 1 dauerhaft auf 262144 setzen.
„failed to create shim / error setting rlimits“: Docker kann die ulimits nicht setzen, häufig auf NAS-Systemen und manchen Cloud-VMs. Lösung: Den ulimits-Block komplett aus dem archivist-es-Service in der compose.yaml entfernen und docker compose up -d neu ausführen.
CSRF-Fehler oder Redirect-Schleife beim Login – Ursache: TA_HOST stimmt nicht mit dem tatsächlich aufgerufenen URL-Origin überein. Lösung: TA_HOST auf exakt die URL aus der Adressleiste setzen, Container neu erstellen.
Verbindung zu Elasticsearch schlägt fehl: ELASTIC_PASSWORD unterscheidet sich zwischen den Diensten, etwa nach einer Änderung nach dem ersten Start. Lösung: beide Dienste über dieselbe Variable versorgen, Logs mit docker compose logs tubearchivist prüfen.
„disk usage exceeded flood-stage watermark“: Elasticsearch sperrt den Index ab 95 % Belegung. Lösung: Speicherplatz freigeben; ab Elasticsearch 7.4 hebt sich die Sperre danach selbst auf.
HTTP 403 oder sehr langsame Downloads: YouTube drosselt erkannten Bot-Verkehr. Maßnahmen: TA_AUTO_UPDATE_YTDLP=release setzen, längere Pausen zwischen Downloads einplanen, Cookies einbinden, POT-Integration prüfen.
ARM64-Fehler beim ES-Container: bbilly1/tubearchivist-es gibt es nur für amd64. Lösung: Im archivist-es-Dienst das Image auf elasticsearch:8.19.0 ändern.
Berechtigungsfehler auf dem ES-Volume: tritt bei Bind Mounts auf. Lösung: Named Volume verwenden.

Häufige Fragen

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

In der Oberfläche unter Einstellungen → Benutzer (siehe Schritt 4); TA_PASSWORD wirkt nur beim ersten Start.

Was passiert, wenn ich einen Kanal abonniere?

Der Kanal wird für künftige Downloads registriert, vorhandene Videos lädt erst „Download entire channel“ (siehe Schritt 5). Nach dem Deabonnieren bleiben heruntergeladene Videos erhalten.

Kann TubeArchivist hinter einem Reverse Proxy mit HTTPS betrieben werden?

Ja, siehe Schritt 6. TA_HOST enthält dann die externe URL mit https://; weicht sie von der Adresse im Browser ab, 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 betreiben Sie ebenfalls per Docker, siehe Jellyfin mit Docker: eigener Media-Server ohne Abo.

Wie viel Speicherplatz wird benötigt?

Das hängt von Anzahl und Auflösung der Videos ab. Sie liegen unter <channel-id>/<video-id>.mp4. Legen Sie das media-Volume auf ein großes separates Laufwerk und überwachen Sie die Belegung (Sperre ab 95 %).

Kann ich den Redis-Container mit anderen Projekten teilen?

Nein. Laut offizieller Dokumentation ist ein gemeinsam genutzter Redis-Container nicht unterstützt. Jeder TubeArchivist-Stack erhält eine eigene Redis-Instanz.

Gibt es Browser-Erweiterungen für TubeArchivist?

Ja. Es gibt offizielle Browser-Extensions für Firefox und Chrome, mit denen Sie Videos direkt von YouTube aus in die Download-Warteschlange übernehmen. Außerdem ist eine SponsorBlock-Integration eingebaut, die Sponsor-Segmente automatisch markiert oder überspringt.

Fazit

TubeArchivist archiviert YouTube-Kanäle lokal und macht sie bis in Untertitel und Kommentare durchsuchbar. Der wichtigste Kompromiss ist der RAM-Bedarf von Elasticsearch. Für den produktiven Betrieb hilft die Anleitung Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only für den Produktivbetrieb.

Weiterführende Anleitungen und Quellen

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

netcup Local Block Storage bestellen, einrichten und unter Linux einbinden