๐ŸŽฌ KV-Tube

Your personal YouTube ยท Self-hosted, private, lightweight

License Go Next.js Docker SQLite PWA

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 ```bash 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) ```yaml 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 ```bash 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 ```bash # 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`](LICENSE) for more information.


If you find this project useful, please โญ star it on GitHub.
Built with โค๏ธ by Khoa Vo