Skip to content
Klutch.sh Docs

Deploying Tube Archivist

Introduction

Tube Archivist is a self-hosted YouTube media server that allows you to download, organize, and stream YouTube content on your own infrastructure. Built with Python and powered by yt-dlp, Tube Archivist provides a Netflix-like experience for your YouTube subscriptions and saved videos.

Unlike simple downloaders, Tube Archivist offers comprehensive media management with automatic metadata fetching, channel subscriptions, playlist support, and a beautiful web interface. It stores full video metadata, thumbnails, and subtitles while maintaining your viewing history and progress.

Key highlights of Tube Archivist:

  • YouTube Integration: Subscribe to channels and automatically download new videos
  • Metadata Rich: Full video descriptions, thumbnails, tags, and statistics
  • Playlist Support: Download and organize entire playlists
  • Search Engine: Elasticsearch-powered full-text search across all content
  • Subtitle Support: Download and display subtitles in multiple languages
  • Video Player: Built-in player with resume playback and watched status
  • Sponsor Block: Integration with SponsorBlock to skip sponsored segments
  • API Access: RESTful API for integration with other tools
  • Import/Export: Backup and migrate your entire collection
  • Scheduling: Automated download schedules for subscriptions
  • Open Source: Licensed under GPL v3

This guide walks through deploying Tube Archivist on Klutch.sh using Docker, setting up the required services, and configuring your media library.

Why Deploy Tube Archivist on Klutch.sh

Deploying Tube Archivist on Klutch.sh provides several advantages for YouTube archiving:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Tube Archivist without complex orchestration. Push to GitHub, and your media server deploys automatically.

Persistent Storage: Attach persistent volumes for your video library, metadata, and Elasticsearch index. Your collection survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your media library from anywhere.

Scalable Storage: Start with moderate storage and expand as your collection grows.

Always-On Downloads: Schedule downloads to run 24/7 without managing your own hardware.

Prerequisites

Before deploying Tube Archivist on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your Tube Archivist configuration
  • Basic familiarity with Docker and containerization concepts
  • Sufficient storage for your intended video collection
  • (Optional) A custom domain for your Tube Archivist instance

Understanding Tube Archivist Architecture

Tube Archivist requires multiple services working together:

Tube Archivist (Main Application): The Python/Django web application handling the UI, downloads, and media management.

Elasticsearch: Provides full-text search capabilities and stores video metadata.

Redis: Message broker for background tasks and caching.

yt-dlp: The underlying tool that handles YouTube video downloads.

Preparing Your Repository

To deploy Tube Archivist on Klutch.sh, create a GitHub repository containing your Dockerfile configuration.

Repository Structure

tubearchivist-deploy/
├── Dockerfile
├── docker-compose.yml
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM bbilly1/tubearchivist:latest


# Set environment variables
ENV TA_HOST=${TA_HOST}
ENV ES_URL=${ES_URL}
ENV REDIS_HOST=${REDIS_HOST}
ENV TA_USERNAME=${TA_USERNAME}
ENV TA_PASSWORD=${TA_PASSWORD}
ENV ELASTIC_PASSWORD=${ELASTIC_PASSWORD}
ENV TZ=${TZ:-UTC}


# Create directories
RUN mkdir -p /youtube /cache


# Expose the web interface port
EXPOSE 8000


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=120s --retries=3 \
  CMD curl -f http://localhost:8000/health/ || exit 1

Environment Variables Reference

VariableRequiredDefaultDescription
TA_HOSTYes-Public URL of your Tube Archivist instance
ES_URLYes-Elasticsearch connection URL
REDIS_HOSTYes-Redis server hostname
TA_USERNAMEYes-Admin username for web interface
TA_PASSWORDYes-Admin password for web interface
ELASTIC_PASSWORDYes-Password for Elasticsearch authentication
TZNoUTCTimezone for download scheduling

Deploying Tube Archivist on Klutch.sh

Tube Archivist requires Elasticsearch and Redis alongside the main application. You’ll need to deploy these services first.

    Deploy Elasticsearch

    First, deploy Elasticsearch on Klutch.sh:

    1. Create a new app for Elasticsearch
    2. Use the official Elasticsearch Docker image
    3. Configure with discovery.type=single-node
    4. Attach a persistent volume for /usr/share/elasticsearch/data
    5. Set the ELASTIC_PASSWORD environment variable

    Deploy Redis

    Next, deploy Redis:

    1. Create a new app for Redis
    2. Use the official Redis Docker image
    3. Attach a persistent volume for /data if persistence is needed
    4. Note the internal hostname for the Redis service

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub:

    Terminal window
    git init
    git add Dockerfile .dockerignore
    git commit -m "Initial Tube Archivist deployment configuration"
    git remote add origin https://github.com/yourusername/tubearchivist-deploy.git
    git push -u origin main

    Create Tube Archivist App

    Navigate to the Klutch.sh dashboard and create a new app for Tube Archivist. Select the repository containing your Dockerfile.

    Configure HTTP Traffic

    In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 8000 (Tube Archivist default port)

    Set Environment Variables

    In the environment variables section, add the following:

    VariableValue
    TA_HOSThttps://your-app-name.klutch.sh
    ES_URLURL to your Elasticsearch service
    REDIS_HOSTHostname of your Redis service
    TA_USERNAMEYour chosen admin username
    TA_PASSWORDYour chosen admin password
    ELASTIC_PASSWORDSame password configured for Elasticsearch
    TZYour timezone (e.g., America/New_York)

    Attach Persistent Volumes

    Persistent storage is essential for Tube Archivist. Add the following volumes:

    Mount PathRecommended SizePurpose
    /youtube100+ GBDownloaded video files
    /cache10 GBThumbnails and temporary files

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will:

    • Detect your Dockerfile automatically
    • Build the container image
    • Attach the persistent volumes
    • Start the Tube Archivist container
    • Provision an HTTPS certificate

    Access Tube Archivist

    Once deployment completes, access your Tube Archivist instance at https://your-app-name.klutch.sh. Log in with the admin credentials you configured.

Initial Setup and Configuration

First Login

When you first access Tube Archivist:

  1. Log in with your configured username and password
  2. You’ll see an empty dashboard ready for content

Adding Channels

Subscribe to YouTube channels:

  1. Click “Channels” in the navigation
  2. Click “Add to Queue”
  3. Paste a channel URL or ID
  4. Choose download options (videos, shorts, live streams)
  5. Subscribe to automatically download new content

Adding Playlists

Download entire playlists:

  1. Navigate to “Playlists”
  2. Click “Add to Queue”
  3. Paste the playlist URL
  4. Select which videos to download

Adding Individual Videos

Download specific videos:

  1. Go to “Downloads”
  2. Click “Add to Queue”
  3. Paste video URLs (one per line)
  4. Click “Add to Queue”

Download Settings

Quality Preferences

Configure video quality in Settings:

  • Resolution (1080p, 720p, etc.)
  • Format preference (MP4, WebM)
  • Audio quality settings

Subtitle Settings

Configure subtitle downloads:

  • Primary language
  • Secondary languages
  • Auto-generated subtitles
  • Embed subtitles in video

Scheduling

Set up automatic downloads:

  1. Go to Settings > Scheduling
  2. Enable scheduled downloads
  3. Set frequency (hourly, daily, weekly)
  4. Configure time of day

Using the Media Library

Browsing Content

Navigate your library:

  • Home: Recently downloaded and continue watching
  • Channels: Browse by subscribed channels
  • Playlists: View organized playlists
  • Downloads: Queue and download status

Video Playback

The built-in player features:

  • Resume from where you left off
  • Playback speed control
  • Subtitle selection
  • SponsorBlock integration (skip sponsors)
  • Keyboard shortcuts

Use Elasticsearch-powered search:

  • Full-text search across titles and descriptions
  • Filter by channel, date, duration
  • Search within video transcripts (if subtitles available)

SponsorBlock Integration

Enabling SponsorBlock

Configure sponsor skipping:

  1. Go to Settings > Integrations
  2. Enable SponsorBlock
  3. Choose segment types to skip:
    • Sponsors
    • Intros
    • Outros
    • Self-promotion
    • Interaction reminders

Submitting Segments

Contribute to the community by submitting segment timestamps for videos.

API Access

Enabling the API

Tube Archivist provides a RESTful API:

  1. Go to Settings > API
  2. Generate an API token
  3. Use the token for authentication

Common API Operations

Terminal window
# Get all videos
curl -H "Authorization: Token YOUR_TOKEN" \
  https://your-domain.klutch.sh/api/video/


# Add video to download queue
curl -X POST -H "Authorization: Token YOUR_TOKEN" \
  -d '{"url": "https://youtube.com/watch?v=..."}' \
  https://your-domain.klutch.sh/api/download/

Production Best Practices

Storage Management

  • Monitor available storage space
  • Set up automatic cleanup for watched videos
  • Archive older content as needed

Backup Strategy

Protect your media library:

  1. Database Backup: Export through the web interface
  2. Video Files: Back up the /youtube directory
  3. Elasticsearch: Backup or re-index from metadata

Performance Optimization

  • Allocate sufficient resources for Elasticsearch
  • Use SSD storage for better search performance
  • Limit concurrent downloads based on bandwidth

Troubleshooting Common Issues

Download Failures

Symptoms: Videos fail to download or are incomplete.

Solutions:

  • Check yt-dlp is up to date
  • Verify YouTube connectivity
  • Review error logs for specific issues
  • Try downloading manually to diagnose

Search Not Working

Symptoms: Search returns no results or errors.

Solutions:

  • Verify Elasticsearch is running
  • Check Elasticsearch connection settings
  • Rebuild search index from settings

Playback Issues

Symptoms: Videos won’t play or buffer excessively.

Solutions:

  • Check video file format
  • Verify storage is accessible
  • Review browser compatibility

Additional Resources

Conclusion

Deploying Tube Archivist on Klutch.sh gives you a comprehensive YouTube media server with automatic downloads, full-text search, and a polished viewing experience. The combination of Tube Archivist’s rich features and Klutch.sh’s deployment simplicity means you can build your personal video library without managing complex infrastructure.

With subscription support, scheduled downloads, and SponsorBlock integration, Tube Archivist transforms YouTube content into a Netflix-like experience under your control. Your videos remain available offline, searchable, and organized exactly how you want them.