VoD System
A self-hosted clip management and live streaming platform. Upload videos, trim and compress clips, save sections of a live stream, and organise everything through a clean web interface — all running locally under Docker.
This project started in secondary school during lockdown as a Python script to squeeze game clips under Discord's 8 MB file size limit. It has since grown into a full-stack application with a Spring Boot backend, a React/Vite/TypeScript frontend, and an nginx-rtmp sidecar for live streaming.
Tech Stack
| Layer | Technology |
|---|---|
| Backend | Java 21, Spring Boot 3.4, Spring Security, JPA, FFmpeg |
| Frontend | React 19, TypeScript, Vite, Tailwind CSS v4 |
| Database | PostgreSQL 15 |
| Streaming | nginx-rtmp |
| Auth | Google OAuth 2.0 + JWT |
| Runtime | Docker Compose |
Requirements
- Docker and Docker Compose
- A Google Cloud project with OAuth 2.0 credentials (Client ID and Secret)
That is all. The backend, frontend, database, and RTMP server all run as containers — no local JDK, Node, or FFmpeg install required.
Getting Started
1. Configure the environment
Copy the example file and fill in the values:
cp .env.example .env
Open .env and set the following:
# OAuth credentials from your Google Cloud Console project
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
# A long random string used to sign JWTs — treat it like a password
JWT_SECRET_KEY=
# Absolute paths on the host where persistent data will be stored
POSTGRES_DATA=/path/to/postgres/data
STREAM_DATA=/path/to/stream/data
MEDIA_DATA=/path/to/media/data
# Database credentials — change these from the defaults before deploying
POSTGRES_URL=jdbc:postgresql://postgres:5432/vodSystem
POSTGRES_USER=myuser
POSTGRES_PASSWORD=mypassword
POSTGRES_DB=vodSystem
# The URLs the frontend will use to reach itself and the backend
FRONTEND_URL=http://localhost:5173
BACKEND_URL=http://localhost:8080
2. Start the application
docker compose up --build
This builds and starts four containers: vod_postgres, vod_backend, vod_frontend, and vod_rtmp.
Once everything has started, the interfaces are available at:
- Frontend: http://localhost:5173
- Backend API: http://localhost:8080/api/v1
- RTMP ingest:
rtmp://localhost:1935/live
3. Authenticate
Log in through the frontend using your Google account. The backend exchanges the Google ID token for a short-lived JWT that is used on all subsequent API requests.
Development Mode
For local backend or frontend development, a separate Compose file is provided that starts only the infrastructure services (PostgreSQL and the RTMP server), leaving the backend and frontend to run directly on the host:
docker compose -f docker-compose.dev.yml up
Then run the backend and frontend separately in your usual workflow.
- Important: Rootless docker should be used to avoid permission conflicts between the RTMP container and the Spring Boot host
API Reference
A Bruno collection is included under bruno/VoD-System/ with pre-configured requests covering all major endpoints. Import it directly into Bruno and point the local environment at http://localhost:8080/api/v1.
The collection is organised into four folders:
| Folder | Description |
|---|---|
| Users | Google OAuth login flow, current user |
| Media | Upload, compress, clip stream, save section |
| Jobs | Poll job status, download completed output |
| Streams | Stream history |
Future Plans
- Format handling — backend conversion of non-MP4 files via FFmpeg for broader input format support
- Input sources — YouTube imports and additional local upload options
- Testing — unit and integration test coverage, including FFmpeg-related functionality
- API documentation — comprehensive, auto-generated backend API docs