project-kino
Docker-hosted web GUI for searching and downloading movies/series, with Jellyfin integration.
Quick Start
cp .env.example .env
# edit .env — set DB_PASSWORD, SECRET_KEY, JELLYFIN_URL, JELLYFIN_API_KEY
docker compose up --build
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- Health: http://localhost:8000/health
Architecture
frontend (React/Vite + nginx)
└─ /api/* → backend (FastAPI)
└─ PostgreSQL
worker (Python polling)
└─ reads pending downloads from DB, simulates job execution
API
| Method | Path | Description |
|---|---|---|
| GET | /health | Health check |
| GET | /api/search?q= | Search across configured providers |
| POST | /api/downloads | Queue a download |
| GET | /api/downloads | List all downloads |
| GET | /api/downloads/:id | Get one download |
| POST | /api/downloads/:id/retry | Retry a failed download |
Providers
Providers are operator-configured search sources. The default mock provider returns
test data. Add real providers by implementing BaseProvider in backend/src/providers.py
and registering them in the _registry.
No hardcoded piracy sources. All download URLs come from operator-configured providers only.
Configuration
All secrets via environment variables or .env (never committed):
| Variable | Description |
|---|---|
DB_PASSWORD |
PostgreSQL password |
SECRET_KEY |
App secret key |
JELLYFIN_URL |
Jellyfin base URL |
JELLYFIN_API_KEY |
Jellyfin API key |
MEDIA_PATH |
Local path for downloaded media |