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 |
Troubleshooting
password authentication failed for user "kino"
The PostgreSQL data volume was initialized with a different password than what
the backend is currently configured to use. This happens when the .env file
is created, changed, or removed after the first docker compose up.
Reset the volume and restart:
docker compose down -v # removes all volumes including db_data — data will be lost
docker compose up --build
If you want to keep data, first export it:
docker compose exec db pg_dump -U kino kino > backup.sql
docker compose down -v
docker compose up --build
# restore:
docker compose exec -T db psql -U kino kino < backup.sql