KV-Tube: How I Built a Self-Hosted YouTube Alternative in a Single Docker Container
Modern video streaming platforms have become increasingly cluttered with unskippable multi-minute ads, invasive user tracking, sponsored segments, and algorithmic rabbit holes designed to maximize watch-time rather than user value.
Alternative frontends like Invidious or Piped exist, but managing their multi-service container stacks, external PostgreSQL instances, and fragile public API proxies can be difficult to maintain on a personal server.
I wanted a clean, self-contained solution: a single Docker container that provides a lightning-fast, private YouTube streaming experience with built-in sponsor skipping, playlist sync, and a responsive interface that works just as well on Android TV as it does on a desktop browser.
That project is KV-Tube.
🎬 What is KV-Tube?
KV-Tube is a self-hosted web portal that lets you watch YouTube content in up to 4K resolution with complete privacy:
- 🚫 Zero Ads & Trackers: Direct video streams without ad interruptions or behavioral profiling.
- ⚡ SponsorBlock Built-in: Automatically skips in-video sponsorship segments, intros, self-promotions, and end credits.
- 📺 Android TV & Smart Remote Friendly: Keyboard, remote D-pad, and touch-optimized navigation.
- 🔄 Cross-Device Watch History: Sync watch progress and custom playlists across your phone, tablet, and PC without needing a Google account.
- 🎵 Background Audio Playback: Listen to podcasts, talks, and music in the background with full lockscreen media controls.
🏗️ Architecture: Go Backend + Next.js Frontend in One Container
A common complaint with self-hosted web apps is multi-container overhead. For KV-Tube, the entire system is bundled into one cohesive Docker image:
┌────────────────────────────────────────────────────────┐
│ KV-Tube Container │
│ │
│ ┌─────────────────────┐ ┌───────────────────┐ │
│ │ Next.js Frontend │ │ Go Stream Server │ │
│ │ Modern Responsive UI│◄────►│ Async API Engine │ │
│ │ (PWA + TV Layout) │ │ (SponsorBlock/DB) │ │
│ └─────────────────────┘ └─────────┬─────────┘ │
│ │ │
│ ┌─────────▼─────────┐ │
│ │ Embedded SQLite │ │
│ │ History & Config │ │
│ └───────────────────┘ │
└────────────────────────────────────────────────────────┘
- Go API Service: The backend is written in Go, offering high-concurrency throughput, minimal memory usage, and near-instant cold starts. It handles metadata extraction, video stream URL resolution, and proxy caching.
- Next.js Interface: Built with Next.js, Tailwind CSS, and Lucide icons, offering smooth client-side routing, instant search suggestions, and a theater viewing mode.
- Embedded SQLite: All user data (watch progress, liked videos, history, and custom subscriptions) is stored in a lightweight local SQLite database—no external PostgreSQL or Redis dependencies required.
⚡ SponsorBlock Integration
KV-Tube integrates directly with the crowd-sourced SponsorBlock API.
When a video plays, KV-Tube queries known sponsor timestamps:
- The video player tracks playback time and automatically leaps over sponsor segments without audible audio blips.
- The playback scrubber visually marks sponsor segments in distinct colors (sponsor, intro, outro, self-promotion).
- Users can toggle which segment types they wish to skip or show in settings.
🚀 Quick Start with Docker
You can spin up KV-Tube in seconds with Docker:
docker run -d \
--name kv-tube \
-p 8080:8080 \
-v ./kv-tube-data:/app/data \
vndangkhoa/kv-tube:latest
Or with docker-compose.yml:
version: '3.8'
services:
kv-tube:
image: vndangkhoa/kv-tube:latest
container_name: kv-tube
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- ./kv-tube-data:/app/data
Access your private streaming portal at http://localhost:8080!
🔗 Check it Out on GitHub
KV-Tube is 100% open-source under the MIT license:
⭐ GitHub Repository: https://github.com/vndangkhoa/kv-tube
🐳 Docker Hub: vndangkhoa/kv-tube
Feel free to open issues, contribute, or drop a star if you find it helpful!
Top comments (0)