vndangkhoa/kv-tube
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: rewrite README with standard project format

Browse source
This commit is contained in:
Khoa Vo 2026-05-14 14:26:18 +07:00
parent 47ad1e47e0
commit 457ff7dbbb
1 changed files with 69 additions and 215 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

284
README.md
View file

@ -1,246 +1,100 @@
# KV-Tube
A modern, fast, and fully-featured YouTube-like video streaming platform. Built with a robust Go backend and a highly responsive Next.js frontend, KV-Tube is designed for seamless deployment on systems like Synology NAS via Docker.
A modern, self-hosted video streaming platform. Go backend + Next.js frontend in a single Docker container.
---
## Quick Setup (Latest v9)
### For Synology NAS (Recommended)
1. **Create folder** on your NAS:
- Path: `/volume1/docker/kv-tube/`
- Inside, create a `data` subfolder
2. **Upload these files** to `/volume1/docker/kv-tube/`:
- `docker-compose.yml`
- `Dockerfile`
- `supervisord.conf`
3. **Open Container Manager** > **Project** > **Create**
- Project Name: `kv-tube`
- Path: `/volume1/docker/kv-tube`
- Click **Done**
4. **Access** at `http://<your-nas-ip>:5011`
---
### For Docker/Docker Compose
## Quick Start
```bash
# Clone the repo
git clone https://github.com/vndangkhoa/kv-tube.git
cd kv-tube
# Create data folder
mkdir -p data
# Build and run
docker build -t kv-tube:latest .
docker-compose up -d
docker compose up -d
```
**Access:**
- Frontend: http://localhost:5011
- Backend API: http://localhost:8981
---
- **Frontend:** http://localhost:5011
- **API:** http://localhost:8981
## Features
- **Modern Video Player**: High-resolution video playback with HLS support and quality selection.
- **Watch Page Controls**: Fullscreen mode, loop playback, and wide mode for enhanced viewing experience.
- **Custom Branding**: Consistent KV-Tube iconography throughout the app.
- **Fast Navigation**: Instant click feedback with skeleton loaders for related videos.
- **Infinite Scrolling**: Scroll seamlessly through a dynamic video grid on the homepage.
- **Watch History & Suggestions**: Keep track of what you've watched seamlessly! Fully integrated library history tracking.
- **Subscriptions Management**: Keep up to date with seamless subscription updates for YouTube channels.
- **Optimized for Safari**: Stutter-free playback algorithms and high-tolerance Hls.js configurations tailored for macOS users.
- **Background Audio**: Allows videos to continue playing audio when the browser tab is hidden or device locked (perfect for music).
- **Progressive Web App**: Fully installable PWA out of the box with offline fallbacks and custom vector iconography.
- **Region Selection**: Tailor your content to specific regions (e.g., Vietnam).
- **Responsive Design**: Beautiful, mobile-friendly interface with light and dark theme support.
- **Containerized**: Fully Dockerized for easy setup using `docker-compose`.
- High-resolution video playback with HLS and quality selection
- Watch history, subscriptions, and search
- Background audio playback (mobile-friendly)
- Progressive Web App (installable)
- Region selection
- Light/dark theme, responsive design
- Infinite scrolling, skeleton loaders
## Architecture
- **Backend & Frontend**: Go (Gin framework) and Next.js are combined into a single unified Docker container using a multi-stage `Dockerfile`.
- **Process Management**: `supervisord` manages the concurrent execution of the backend API and Next.js frontend within the same network namespace.
- **Data storage**: SQLite is used for watch history, optimized for `linux/amd64`.
## Docker Deployment (v9)
Single unified Docker container running:
- **Backend:** Go (Gin framework) — API server on port 8080
- **Frontend:** Next.js 16 (standalone) — SSR on port 3000
- **Process Manager:** supervisord manages both processes
- **Storage:** SQLite for watch history and metadata
### Quick Start (Local Build)
## Deployment
1. Clone or download this repository
2. Create a `data` folder in the project directory
3. Build and run the container:
### Docker Compose
```bash
# Build the image
docker build -t kv-tube:latest .
# Run the container
docker-compose up -d
```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
restart: unless-stopped
```
### Building & Tagging for Registry
### Synology NAS (DSM 7.2+)
To build and push to your custom registry:
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
```bash
# Build with your registry and tag
docker build -t your-registry.com/kv-tube:latest .
# Push to registry
docker push your-registry.com/kv-tube:latest
docker buildx build --platform linux/amd64 -t kv-tube:latest --push .
```
### Pre-built Image
## Environment Variables
If using the pre-built image from Forgejo registry:
```bash
# Pull from Forgejo
docker pull git.khoavo.myds.me/vndangkhoa/kv-tube:v9
# Or tag as latest for local use
docker tag git.khoavo.myds.me/vndangkhoa/kv-tube:v9 kv-tube:latest
```
## Deployment on Synology NAS
We recommend using **Container Manager** (DSM 7.2+) for the best experience. You can also use **Docker** package (DSM 6/7.1).
### Option 1: Using Container Manager (DSM 7.2+) - Recommended
#### Step 1: Prepare the folder
1. Open **File Station** and navigate to your docker folder (e.g., `/volume1/docker/`)
2. Create a new folder named `kv-tube`
3. Inside `kv-tube`, create a `data` subfolder
#### Step 2: Upload files
Upload the following files to `/volume1/docker/kv-tube/`:
- `docker-compose.yml`
- `Dockerfile`
- `supervisord.conf`
#### Step 3: Create Project
1. Open **Container Manager** > **Project** > **Create**
2. Project Name: `kv-tube`
3. Path: `/volume1/docker/kv-tube`
4. Source: Select **docker-compose.yml** (it will auto-detect from the folder)
5. Click **Next** > **Done**
The container will build and start automatically.
#### Step 4: Access the App
- **Frontend**: `http://<your-nas-ip>:5011`
- **Backend API**: `http://<your-nas-ip>:8981`
---
### Option 2: Using Docker Package (DSM 6/7.1)
#### Step 1: Pull the image
Open **Docker** > **Registry** and search for `kv-tube`, or use SSH to pull:
```bash
docker pull kv-tube:latest
```
#### Step 2: Create Container
1. Open **Docker** > **Container** > **Create**
2. Image: `kv-tube:latest` (or your custom registry URL)
3. Container Name: `kv-tube`
4. Network: `Bridge`
5. Port Forwarding:
- Local Port: `5011` → Container Port: `3000`
- Local Port: `8981` → Container Port: `8080`
6. Volume: Map `/volume1/docker/kv-tube/data` → `/app/data`
7. Environment:
- `KVTUBE_DATA_DIR=/app/data`
- `GIN_MODE=release`
- `NODE_ENV=production`
8. Restart Policy: `unless-stopped`
#### Step 3: Start Container
Click **Create** and then start the container.
---
### Option 3: Using Docker Compose (SSH)
Connect to your NAS via SSH and run:
```bash
# Navigate to your kv-tube folder
cd /volume1/docker/kv-tube
# Build and start
docker-compose up -d
# View logs
docker-compose logs -f
# Stop
docker-compose down
```
---
### Mobile PWA Installation
For the best mobile experience:
1. Open `http://<your-nas-ip>:5011` in Safari (iOS) or Chrome (Android)
2. Tap **Share** > **Add to Home Screen** (iOS)
3. Or tap **Install** (Android)
This gives you a native app-like experience with background audio playback.
---
### Updating the Container
**Using Container Manager:**
1. Stop the container
2. Remove the image
3. Pull new image or rebuild
4. Start the container
**Using Docker Compose:**
```bash
cd /volume1/docker/kv-tube
docker-compose pull
docker-compose up -d
```
**Using Watchtower (auto-update):**
The container label enables Watchtower for automatic updates:
```bash
docker run --detach \
--name watchtower \
--volume /var/run/docker.sock:/var/run/docker.sock \
--volume /your/path/config:/config \
containrrr/watchtower \
--include-stopped \
--schedule "0 2 * * *" \
kv-tube
```
---
### Troubleshooting
| Issue | Solution |
|-------|----------|
| Container won't start | Check logs: `docker logs kv-tube` or via Container Manager |
| Port conflicts | Ensure ports 5011 and 8981 are not used by other services |
| Permission denied | SSH to NAS: `sudo chmod -R 755 /volume1/docker/kv-tube/data` |
| Slow playback | Lower video quality or ensure sufficient network bandwidth |
| Cannot access frontend | Check firewall settings on Synology |
| 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 builds can be started in `frontend/` via `npm run dev`.
- Backend server starts in `backend/` via `go run main.go`.
```bash
# Frontend
cd frontend
npm install
npm run dev
# Backend
cd backend
go run main.go
```
## Updating
```bash
docker compose pull
docker compose up -d
```
Or enable auto-updates with [Watchtower](https://github.com/containrrr/watchtower).