TubeArchivist mit Docker installieren: Selbstgehosteter YouTube-Archivier
TubeArchivist archiviert YouTube-Kanäle lokal: Videos mit Metadaten herunterladen, per Elasticsearch durchsuchbar indexieren und im Browser abspielen, unabhängig von YouTube, betrieben als Docker-Stack aus drei Containern mit festgelegten Image-Tags.
Werbung Mit * markierte Links sind Werbelinks: Bei einem Kauf erhalten wir eine Provision, der Preis bleibt gleich. Als Amazon-Partner verdiene ich an qualifizierten Verkäufen. Mehr dazu

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:9.5.5) stattbbilly1/tubearchivist-esverwenden, das TubeArchivist-eigene ES-Image ist ausschließlich für amd64 gebaut
Eckdaten im Überblick
| Eigenschaft | Wert |
|---|---|
| App-Image | bbilly1/tubearchivist:v0.6.0 |
| ES-Image (amd64) | bbilly1/tubearchivist-es:9.5.5 |
| ES-Image (ARM64) | elasticsearch:9.5.5 |
| Redis-Image | redis:8 |
| Webinterface-Port | 8000 (Anwendung direkt, seit v0.6.0 ohne eingebautes Nginx; änderbar mit TA_PORT) |
| 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_countLegen Sie anschließend den Projektordner an:
$ sudo mkdir -p /opt/tubearchivist
$ sudo chown $USER:$USER /opt/tubearchivist
$ cd /opt/tubearchivistsysctl 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=IHR_ADMIN_PASSWORT # Initiales Admin-Passwort, nach dem ersten Login ändern
ELASTIC_PASSWORD=IHR_ELASTIC_PASSWORT # Elasticsearch-Passwort, MUSS in beiden Diensten identisch sein
# Empfohlene optionale Einstellungen
TZ=Europe/Berlin # Zeitzone für den internen Scheduler
TA_AUTO_UPDATE_YTDLP=release # yt-dlp automatisch auf neue Stable-Versionen aktualisierenUID und GID liefert der Befehl id. Schützen Sie die Datei anschließend vor unbefugtem Lesen:
$ chmod 600 /opt/tubearchivist/.envls -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.6.0
user: "1000:1000" # optional, ohne die Zeile läuft der Container als root
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
- 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 (vorkonfiguriert)
# ARM64 (Raspberry Pi, Apple Silicon): elasticsearch:9.5.5 verwenden!
image: bbilly1/tubearchivist-es:9.5.5
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.
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 -dElasticsearch 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 tubearchivistNach 1 bis 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.6.0 Up 2 minutes (healthy)
archivist-redis redis:8 Up 2 minutes
archivist-es bbilly1/tubearchivist-es:9.5.5 Up 2 minutesZusä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_USERNAMEundTA_PASSWORDan. - Passwort sofort ändern: Der Wert aus
TA_PASSWORDwird 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.
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 tubearchivistTA_HOST muss bei HTTPS mit https:// beginnen. Einen Einstieg bietet die Anleitung Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten.
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 -dDocker 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.
Umstieg von v0.5 auf v0.6
Version 0.6.0 enthält laut Release Notes Breaking Changes. Der Container kann jetzt unter einem eigenen Benutzer ohne root laufen, dafür entfällt das eingebaute Nginx; Videos, Untertitel und Vorschaubilder liefert die Anwendung selbst aus, unter geänderten URLs. Elasticsearch wechselt von 8.19.0 auf 9.5.5. Für Bestandsinstallationen gilt:
- Älteren Stand erst auf v0.5.12 bringen und einmal vollständig starten lassen; Migrationen für Versionen vor v0.5.5 sind entfallen.
- Stack stoppen und sichern.
HOST_UIDundHOST_GIDauscompose.yamlund.enventfernen,TA_BACKEND_PORTfalls gesetzt ebenfalls; einen anderen Port setzt künftigTA_PORT.- Optional
user: "1000:1000"beim Diensttubearchivistsetzen und vorher die Daten der Volumesmediaundcacheauf diese UID übertragen, bei Named Volumes zum Beispiel mitdocker run --rm -v tubearchivist_media:/d alpine chown -R 1000:1000 /d(Volumename mitdocker volume lsprüfen). TubeArchivist ändert Dateirechte nicht mehr selbst. - Tags auf
bbilly1/tubearchivist:v0.6.0undbbilly1/tubearchivist-es:9.5.5ändern (ARM64:elasticsearch:9.5.5), danndocker compose pullunddocker compose up -d. Wer ein anderes Elasticsearch-Image auf älterem 8.x nutzt, geht zuerst auf 8.19.x.
Eigene Direktlinks oder Proxy-Regeln für Medienpfade passen Sie an die URLs an, die die API zurückgibt. Scheitert der Start, können Sie laut Release Notes direkt nach der Fehlermeldung auf v0.5.12 zurück, weil dann noch nichts umgestellt ist. Im Test lief genau dieser Ablauf mit der Compose-Datei aus Schritt 3: Bestand mit v0.5.12 und Elasticsearch 8.19.0, angepasste Benutzereinstellung, dann Umstellung wie oben mit user: "1000:1000". Nach rund 50 Sekunden antwortete /api/health/ mit 200, der Container lief als uid=1000, das Log meldete Confirming v0.6.0 environment und ES version check passed: Elasticsearch meldete 9.5.5, die vorher gesetzte Einstellung war erhalten, die Anmeldung gelang mit 204, ein falsches Passwort bekam 400, und /api/ping/ meldete v0.6.0.
Nach dem Update zeigt docker compose ps alle Container als running. Die in der Oberfläche angezeigte Versionsnummer entspricht dem neuen Tag.
Grundlagen zum Betrieb finden Sie in Linux-Server absichern mit UFW und Fail2ban.
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
ulimitsnicht setzen, häufig auf NAS-Systemen und manchen Cloud-VMs. Lösung: Denulimits-Block komplett aus demarchivist-es-Service in dercompose.yamlentfernen unddocker compose up -dneu ausführen.- CSRF-Fehler oder Redirect-Schleife beim Login
Ursache:
TA_HOSTstimmt nicht mit dem tatsächlich aufgerufenen URL-Origin überein. Lösung:TA_HOSTauf exakt die URL aus der Adressleiste setzen, Container neu erstellen.- Verbindung zu Elasticsearch schlägt fehl
ELASTIC_PASSWORDunterscheidet sich zwischen den Diensten, etwa nach einer Änderung nach dem ersten Start. Lösung: beide Dienste über dieselbe Variable versorgen, Logs mitdocker compose logs tubearchivistprü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=releasesetzen, längere Pausen zwischen Downloads einplanen, Cookies einbinden, POT-Integration prüfen.- ARM64-Fehler beim ES-Container
bbilly1/tubearchivist-esgibt es nur für amd64. Lösung: Imarchivist-es-Dienst das Image aufelasticsearch:9.5.5ä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
- Docker und Docker Compose auf Linux installieren (Ubuntu/Debian): die Self-Hosting-Grundlage
- Docker-Netzwerke und Volumes richtig nutzen
- Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten
- Caddy als Reverse Proxy einrichten: Anfänger-Anleitung mit automatischem HTTPS
- Jellyfin mit Docker: eigener Media-Server ohne Abo
- Restic Backup auf Linux und Windows einrichten und automatisieren
- 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


