kv-tube/README.md

🎬 KV-Tube

Your personal YouTube · Self-hosted, private, lightweight

Features • Quick Start • Why KV-Tube? • Deployment • Development • Contributing

---

Watch, search, and subscribe — just like YouTube, but fully under your control.

✨ Features

🎞️ Video Playback HLS streaming with adaptive quality — from 144p to 4K.	📜 Watch History Automatically tracked. Always in sync. Never lose your place.
🔔 Subscriptions Follow any YouTube channel. Get updates instantly.	🔍 Search Full-text search across videos, channels, and history.
🎵 Background Audio Keep listening with the screen locked — perfect for music.	📱 PWA Install as a native app. Works offline. Full-screen experience.
🌍 Region Tuning Tailor content and recommendations to any region.	🌓 Themes Light, dark, and system-following themes out of the box.

🚀 Quick Start

git clone https://github.com/vndangkhoa/kv-tube.git
cd kv-tube
mkdir -p data
docker build -t kv-tube:latest .
docker compose up -d

Frontend: http://localhost:5011  •  API: http://localhost:8981

---

🤔 Why KV-Tube?

YouTube is incredible — but it's also ad-ridden, tracks everything, and sometimes removes the videos you love.

KV-Tube gives you:

• Privacy — No tracking, no algorithms manipulating you. Your watch history stays on your machine.
• Permanence — Videos you subscribe to stay available. No takedowns, no region blocks.
• Ownership — Run it on your NAS, your VPS, or a Raspberry Pi. It's yours.
• Simplicity — One container. One command. Zero configuration.

📖 Backstory

I built KV-Tube because I wanted a way to watch YouTube content without the YouTube baggage — ads, recommendation rabbit holes, and the feeling that the product was me, not the video player.

What started as a simple Go API to proxy video streams evolved into a full-featured frontend with subscriptions, search, PWA support, and a clean, YouTube-like interface. It runs on my Synology NAS at home, and I use it daily.

If that resonates, give it a star ⭐ — it helps others find the project.

---

🏗️ Architecture

KV-Tube ships as a single Docker image. Everything runs in one container, managed by supervisord.

Layer	Tech	Port	Role
Backend	Go + Gin	8080	REST API, video fetching, yt-dlp orchestration
Frontend	Next.js 16	3000	SSR, PWA, responsive UI
Process Manager	supervisord	—	Keeps backend + frontend alive
Storage	SQLite	—	Watch history, subscriptions, metadata

📦 Deployment

🐳 Docker Compose (Recommended)

services:
  kv-tube:
    build: .
    container_name: kv-tube
    ports:
      - "5011:3000"
      - "8981:8080"
    volumes:
      - ./data:/app/data
    environment:
      - KVTUBE_DATA_DIR=/app/data
      - GIN_MODE=release
      - NODE_ENV=production
      - CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5011
    restart: unless-stopped

🖥️ Synology NAS (DSM 7.2+)

1. Create folder /volume1/docker/kv-tube/data
2. Upload docker-compose.yml, Dockerfile, supervisord.conf
3. In Container Manager → Project → Create, select the folder
4. Done. The container builds and starts automatically.

🛠️ Multi-arch Build

docker buildx build --platform linux/amd64 -t kv-tube:latest --push .

---

⚙️ Configuration

Variable	Default	Description
KVTUBE_DATA_DIR	/app/data	Path for SQLite DB and data
GIN_MODE	release	Gin framework log mode
NODE_ENV	production	Node.js environment
CORS_ALLOWED_ORIGINS	""	Comma-separated allowed origins
PORT	8080	Backend API listen port

---

💻 Development

# Frontend
cd frontend
npm install
npm run dev

# Backend
cd backend
go run main.go

---

🤝 Contributing

Contributions are welcome! Here's how to help:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push (git push origin feature/amazing)
5. Open a Pull Request

Please make sure to follow existing code style and add tests when possible.

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

_{If you find this project useful, please ⭐ star it on GitHub.
Built with ❤️ by Khoa Vo}