kv-tube/README.md

🎬 KV-Tube

Self-hosted video streaming platform
Go backend + Next.js frontend — single Docker container

Quick Start • Features • Architecture • Deployment • Development

---

🚀 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

---

✨ Features

🎞️	Video Playback HLS streaming with quality selection	📜	Watch History Track what you've watched
🔔	Subscriptions Follow YouTube channels	🔍	Search Find videos instantly
🎵	Background Audio Play with screen locked	📱	PWA Install as native app
🌍	Region Selection Tailor content by region	🌓	Themes Light & dark mode

---

🏗️ Architecture

Single unified Docker container running:

Component	Tech	Port	Role
Backend	Go + Gin	8080	REST API, video processing, yt-dlp
Frontend	Next.js 16	3000	SSR, PWA, UI
Process Manager	supervisord	—	Manages both processes
Storage	SQLite	—	Watch history & metadata

---

📦 Deployment

🐳 Docker Compose

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 /volume1/docker/kv-tube/data
2. Upload docker-compose.yml, Dockerfile, supervisord.conf
3. Open Container Manager > Project > Create
4. Select path /volume1/docker/kv-tube, click Done

🛠️ Multi-arch Build

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

---

⚙️ Environment Variables

Variable	Default	Description
KVTUBE_DATA_DIR	/app/data	Data storage path
GIN_MODE	release	Gin framework mode
NODE_ENV	production	Node environment
CORS_ALLOWED_ORIGINS	—	Comma-separated allowed CORS origins
PORT	8080	Backend API port

---

💻 Development

# Frontend
cd frontend
npm install
npm run dev

# Backend
cd backend
go run main.go

---

🔄 Updating

docker compose pull
docker compose up -d

Or enable auto-updates with Watchtower.

---

📄 License

MIT License — see LICENSE for details.