Document Docker deployment and web dashboard

This commit is contained in:
Sleeps
2026-10-06 18:32:52 +01:00
parent 5cae9ea833
commit 0afe0536f4
+59 -6
View File
@@ -37,14 +37,52 @@ Long term:
- Docker / Docker Compose
- Ollama for optional stage-2 captions
## 1. Start Meilisearch
## 1. Run Scene Search with Docker
The normal deployment runs both Meilisearch and the Scene Search API/web app with Docker Compose. The Python CLI remains available for maintenance and debugging, but you do not need to keep `python -m scene_search.cli serve` running manually.
Create your environment file and set the Jellyfin/API credentials:
```bash
cp .env.example .env
# Change MEILI_MASTER_KEY in .env
docker compose up -d
nano .env
```
At minimum set `MEILI_MASTER_KEY`, `JELLYFIN_API_KEY`, `SCENE_API_KEY`, and your Ollama URL/model settings.
GPU access requires the NVIDIA Container Toolkit on the Docker host. Once Docker can expose the NVIDIA GPU to containers, build and start everything:
```bash
docker compose up -d --build
```
The existing `./data` directory is bind-mounted into the application container, so SQLite, thumbnails, editable prompts and the Hugging Face model cache persist across container rebuilds.
The Compose service reaches Jellyfin on the same host through `host.docker.internal:8096` by default. If your Jellyfin server uses another address, set:
```env
JELLYFIN_DOCKER_URL=http://your-jellyfin-host:8096
```
Meilisearch is addressed internally as `http://meilisearch:7700`; the existing host port `7869` remains available for its dashboard/API.
Check the containers:
```bash
docker compose ps
docker compose logs -f scene-search
```
The standalone Scene Search dashboard is then available at:
```text
http://<tardis-ip-or-hostname>:8097/
```
If `SCENE_API_KEY` is configured, enter it once in the dashboard. It is stored only in that browser's local storage.
> If an item has no Jellyfin Trickplay data and the indexer must use ffmpeg fallback, its Jellyfin media path must also be mounted into the container at the same path. Trickplay-backed items do not require the original media filesystem to be mounted.
## 2. Python environment
Create and activate a venv, install a CUDA-compatible PyTorch build if required, then:
@@ -322,7 +360,7 @@ SCENE_API_KEY=replace-with-a-random-secret
If Jellyfin and this project run on the same host, keeping the API bound to `127.0.0.1` is recommended.
Start the service:
With the recommended Docker deployment the service starts automatically with `docker compose up -d`. For development outside Docker you can still run:
```bash
python -m scene_search.cli serve
@@ -364,7 +402,22 @@ The API also exposes authenticated Jellyfin-management endpoints used by the plu
- `POST /api/jellyfin/index` — start one background indexing job for selected library ids.
- `GET /api/jellyfin/index/status` — report live library/item/frame/sync progress.
Only one plugin-triggered indexing job can run at a time. Search requests return a temporary 503 while that job owns the shared embedding model.
Only one indexing job can run at a time. Search requests return a temporary 503 while that job owns the shared embedding model.
The indexing status now includes an overall item-weighted percentage across all selected libraries. The final 1% is reserved for rebuilding Meilisearch, so the UI reaches 99% after media ingestion and 100% only when the serving index is ready.
### Standalone web dashboard
The API serves a lightweight management/search UI at `/`. It provides:
- service/Meilisearch health at a glance;
- Jellyfin library selection and indexed item/frame counts;
- normal or forced indexing;
- overall progress plus current library/item/frame progress;
- final indexed/unchanged/failed/removed totals;
- semantic scene search with cached frame thumbnails.
The page talks to the same authenticated API used by the Jellyfin plugin. The API key is never embedded into the HTML; when supplied in the page it is kept in that browser's local storage.
## Jellyfin 12 search plugin
@@ -398,7 +451,7 @@ Open **Dashboard → Plugins → Scene Search** and configure:
The plugin asks the Python service for the libraries visible to the configured Jellyfin API key and shows their current indexed item/frame counts. The selected library ids are saved in Jellyfin's plugin configuration, so normal operation does not require editing `.env`.
Use **Index selected libraries** to start a backend indexing job. The plugin shows the current library, item and frame progress and polls until the job completes. When ingestion finishes, the backend automatically rebuilds Meilisearch, so newly indexed vectors are searchable without a separate `sync-meili` command.
Use **Index selected libraries** to start a backend indexing job. The plugin shows an overall percentage/progress bar across all selected libraries as well as the current library, item and frame progress, and polls until the job completes. When ingestion finishes, the backend automatically rebuilds Meilisearch, so newly indexed vectors are searchable without a separate `sync-meili` command.
Plugin-triggered indexing reuses the API process's existing SigLIP instance and blocks semantic searches while the indexing job owns the model, avoiding a second GPU copy on the same machine.