backend/
├── pyproject.toml
├── README.md
├── src/
│   └── media_library_viewer_api/
│       ├── __init__.py
│       ├── main.py              # FastAPI app entrypoint
│       ├── config.py            # pydantic-settings config
│       ├── dependencies.py      # Dependency injection
│       ├── path_utils.py        # Jellyfin→SSH path resolution
│       ├── jobs.py              # Job templates
│       ├── utils.py             # Formatting helpers
│       ├── routers/
│       │   ├── dashboard.py
│       │   ├── monitoring.py
│       │   ├── media.py
│       │   ├── users.py
│       │   ├── settings.py
│       │   ├── files.py
│       │   └── jobs.py
│       ├── clients/
│       │   ├── jellyfin.py
│       │   ├── jellyseerr.py
│       │   ├── local.py
│       │   ├── resources.py
│       │   └── ssh.py
│       ├── domain/
│       │   └── media.py
│       └── services/
│           ├── media_index.py
│           └── settings_store.py
└── tests/

Setup

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Configuration

Set environment variables directly in your shell or a wrapper script before running the app or Compose. The Docker Compose files use interpolation and do not require an env_file entry.

For local .env development, you can still create one if you prefer, but it is optional.

# Optional backend logging level
LOG_LEVEL=INFO

# Optional SMTP settings for the Users -> message popup
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=your-smtp-username
SMTP_PASSWORD=your-smtp-password
SMTP_FROM_ADDRESS=no-reply@example.com
SMTP_FROM_NAME=Manage
SMTP_USE_TLS=true
SMTP_USE_SSL=false
SMTP_TIMEOUT=30

# Jellyfin, Jellyseerr, and SSH targets are now configured per machine in the app's Settings tab.
# The backend seeds a local machine automatically, so no global Jellyfin or SSH env vars are required.

# Versioning
# The backend tries to auto-detect its version from installed package metadata.
# If needed, you can override the displayed version/build markers with APP_VERSION and APP_BUILD_INFO.
APP_VERSION=0.1.0
APP_BUILD_INFO=dev

# Authentik / OIDC
AUTH_ENABLED=true
OIDC_ISSUER_URL=https://authentik.example/application/o/media-library-viewer/
OIDC_AUDIENCE=media-library-viewer
OIDC_JWKS_URL=
OIDC_CLOCK_SKEW_SECONDS=30

Running

cd backend
uvicorn media_library_viewer_api.main:app --reload --port 8000

Or with PYTHONPATH if not installed:

PYTHONPATH=src uvicorn media_library_viewer_api.main:app --reload --port 8000

API docs available at: http://localhost:8000/docs

Docker

The repository root includes a production docker-compose.yml and a development docker-compose.dev.yml. The backend media index is stored in the backend_cache Docker volume so it survives container restarts and image rebuilds. The production compose file expects required environment variables to be supplied via interpolation (shell exports or inline VAR=value docker compose ...).

Configuration workflow examples

Export your runtime variables before launching Compose:

export BACKEND_APP_HOST=manage.example.com
export FRONTEND_APP_HOST=manage.example.com
export CERT_RESOLVER=letsencrypt
export VITE_OIDC_ISSUER=https://authentik.example/application/o/manage/
export VITE_OIDC_CLIENT_ID=manage
export VITE_OIDC_REDIRECT_URI=https://manage.example.com/
export VITE_OIDC_POST_LOGOUT_REDIRECT_URI=https://manage.example.com/

docker compose up --build

After the API is running, open the app, go to Settings, and add machine entries:
- Local: monitors the API host itself without SSH.
- SSH: monitors another machine using a host, username, and a private key pasted directly into the machine settings, with an optional passphrase.
Open Monitoring to see one section per configured machine. Each section uses its own collector state, disk path, metrics queries, and recent action history, which are populated automatically by the backend poller.

For local development, docker compose -f docker-compose.dev.yml up --build does not require an SSH key unless you configure remote SSH machines in the Settings tab.

API Endpoints

GET /api/dashboard/counts — Movie/series/episode totals
GET /api/dashboard/libraries — Per-library breakdown
GET /api/dashboard/now-playing — Active playback sessions
GET /api/monitoring/machines — Persistent monitoring machine definitions
GET /api/monitoring/status?machine_id= — Collector status for a machine
GET /api/monitoring/metrics?machine_id= — Resource samples (last hour)
GET /api/monitoring/disk?machine_id= — Disk space
POST /api/monitoring/start|stop|restart?machine_id= — Collector controls
GET /api/monitoring/diagnostics?machine_id= — Collector debug info
GET /api/monitoring/poller — Backend poller status and configuration
GET /api/monitoring/machines/{machine_id}/actions — Recent machine action history
GET /api/dashboard/monitoring — Dashboard-wide per-machine monitoring summary table with 10-minute averages and min/max subtext
GET /api/settings/machines — Manage machine definitions
GET /api/media/status — Index status
POST /api/media/build — Rebuild index
GET /api/media/query — Query with filters/sort/pagination
GET /api/files/list?path= — Directory listing
GET /api/files/ffprobe?path= — ffprobe JSON
GET /api/files/stat?path= — stat output
GET /api/files/resolve-path?path= — Path resolution
GET /api/jobs/templates — Available jobs
POST /api/jobs/run — Execute a job
GET /api/users — Jellyfin users with optional Jellyseerr enrichment
GET /api/version — Backend version/build metadata for the UI