Tube Archivist lets you subscribe to your favorite YouTube channels, download videos with yt-dlp, and index them for full-text search with Elasticsearch. It offers offline playback, watch-history tracking, playlist creation, and SponsorBlock integration through a self-hosted web interface.
Tube Archivist Docker Compose example
Self-host Tube Archivist on your own server, homelab, or VPS starting from this Docker Compose example.
It runs Tube Archivist in Docker containers using the official bbilly1/tubearchivist:latest, redis:latest, bbilly1/tubearchivist-es:latest images, with persistent volumes and automatic restarts preconfigured.
Review the environment variables and adjust them to your setup, save the file as compose.yml (or docker-compose.yml), and start the stack with docker compose up -d.
services:
tubearchivist:
image: bbilly1/tubearchivist:latest
restart: unless-stopped
volumes:
- media:/youtube
- cache:/cache
environment:
# Connection string for the bundled Elasticsearch service (include protocol and port).
ES_URL: "http://archivist-es:9200"
# Connection string for the bundled Redis service.
REDIS_CON: "redis://archivist-redis:6379"
# UID the container runs downloaded files as; keep at 1000 unless mounting host dirs.
HOST_UID: "1000"
# GID the container runs downloaded files as; keep at 1000 unless mounting host dirs.
HOST_GID: "1000"
# Public URL where Tube Archivist is reached, including protocol and port (used for CORS/login).
TA_HOST: "changeme"
# Username for the initial Tube Archivist admin account created on first start.
TA_USERNAME: "tubearchivist"
# Password for the initial Tube Archivist admin account created on first start.
TA_PASSWORD: "changeme"
# Password shared with the bundled Elasticsearch service (internal to the compose network).
ELASTIC_PASSWORD: "verysecret"
# Timezone used for scheduled downloads and displayed timestamps.
TZ: "UTC"
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
restart: unless-stopped
volumes:
- redis:/data
depends_on:
- archivist-es
archivist-es:
image: bbilly1/tubearchivist-es:latest
restart: unless-stopped
environment:
# Password shared with the Tube Archivist service (internal to the compose network).
ELASTIC_PASSWORD: "verysecret"
# JVM heap size for Elasticsearch; raise for larger libraries.
ES_JAVA_OPTS: "-Xms1g -Xmx1g"
# Enable Elasticsearch authentication (required by Tube Archivist).
xpack.security.enabled: "true"
# Run Elasticsearch as a single-node cluster.
discovery.type: "single-node"
# Directory Elasticsearch uses for snapshot repositories.
path.repo: "/usr/share/elasticsearch/data/snapshot"
ulimits:
memlock:
soft: -1
hard: -1
volumes:
- es:/usr/share/elasticsearch/data
volumes:
media:
cache:
redis:
es:
Values set to changeme are required — replace them with your own
values before starting Tube Archivist.
Prefer a managed setup? WinterFlow installs, configures, and updates Tube Archivist for you using this same Docker Compose configuration.