📚 Librarrarian — Media Transcoding Dashboard
Host: Homelab · Compose:
Homelab/Docker/librarrarian/compose.yaml
Stack name:librarrarian
1. Overview
Librarrarian is a custom Flask-based dashboard for managing and monitoring media transcoding jobs. It provides a web UI to track the status of media encoding across the NFS library and supports OIDC SSO, passkey authentication, and a background worker process. This is a private project hosted at ghcr.io/m1ckyb/librarrarian-dashboard.
2. Architecture & Services
| Service | Image | Port | Role |
|---|---|---|---|
db |
postgres:16-alpine@sha256:3c5c8892d184f738f4fe282d14ddaa613a38f00f4189d2d94725ebe6f2909ddb |
50021 |
PostgreSQL database for job state |
librarrarian |
ghcr.io/m1ckyb/librarrarian-dashboard:develop |
50020 |
Web dashboard (Flask) |
librarrarian-worker-1 |
ghcr.io/m1ckyb/librarrarian-worker:develop |
— | Background job worker (transcoding) |
3. Networking
cloudflare-net— Routes the dashboard totranscode.m1ckyb.comvia Cloudflare Tunnel.internal— Bridge network for dashboard ↔ database ↔ worker communication.
4. Persistent Storage
| Container | Host Path / Volume | Description |
|---|---|---||
| db | postgres_data | — |
| librarrarian | /docker/services/librarrarian | Application data and config |
| librarrarian | /nfs/media/ | NFS media library (read/write for transcoding) |
| librarrarian-worker-1 | /nfs/media/ | NFS media library (read/write for transcoding) |
5. Environment Variables
| Variable | Service | Description |
|---|---|---|
POSTGRES_DB |
db |
— |
POSTGRES_PASSWORD |
db |
— |
POSTGRES_USER |
db |
— |
API_KEY |
librarrarian |
Shared key for worker authentication |
AUTH_ENABLED |
librarrarian |
Master auth switch (true/false) |
DB_HOST |
librarrarian |
— |
DB_NAME |
librarrarian |
— |
DB_PASSWORD |
librarrarian |
— |
DB_USER |
librarrarian |
— |
DEVMODE |
librarrarian |
— |
FLASK_SECRET_KEY |
librarrarian |
Flask session signing key |
LOCAL_LOGIN_ENABLED |
librarrarian |
Enable local username/password fallback |
LOCAL_PASSWORD |
librarrarian |
— |
LOCAL_USER |
librarrarian |
— |
OIDC_CLIENT_ID |
librarrarian |
— |
OIDC_CLIENT_SECRET |
librarrarian |
— |
OIDC_ENABLED |
librarrarian |
Enable OIDC SSO |
OIDC_ISSUER_URL |
librarrarian |
OIDC provider URL |
OIDC_PROVIDER_NAME |
librarrarian |
— |
PASSKEY_ENABLED |
librarrarian |
Enable WebAuthn passkeys |
PYTHONUNBUFFERED |
librarrarian |
— |
TZ |
librarrarian |
Timezone |
WEBAUTHN_ORIGIN |
librarrarian |
— |
WEBAUTHN_RP_ID |
librarrarian |
— |
WEBAUTHN_RP_NAME |
librarrarian |
— |
API_KEY |
librarrarian-worker-1 |
Shared key for worker authentication |
AUTOSTART |
librarrarian-worker-1 |
Auto-start processing on container launch |
DASHBOARD_URL |
librarrarian-worker-1 |
— |
DB_HOST |
librarrarian-worker-1 |
— |
DB_NAME |
librarrarian-worker-1 |
— |
DB_PASSWORD |
librarrarian-worker-1 |
— |
DB_USER |
librarrarian-worker-1 |
— |
MEDIA_PATHS |
librarrarian-worker-1 |
Comma-separated allowed media paths |
TZ |
librarrarian-worker-1 |
Timezone |
6. Access & Usage
| URL | Description |
|---|---|
https://transcode.m1ckyb.com |
Librarrarian web UI |
http://localhost:50020 |
Direct local access |
# Start
docker compose -f Homelab/Docker/librarrarian/compose.yaml up -d
# Health check
curl -f http://localhost:50020/api/health
# Worker logs
docker logs librarrarian-worker-1 -f
7. Maintenance & Backup
# Update (uses develop tag — will always pull latest)
docker compose -f Homelab/Docker/librarrarian/compose.yaml pull
docker compose -f Homelab/Docker/librarrarian/compose.yaml up -d
# Backup
docker exec librarrarian-db pg_dump -U postgres > /backup/librarrarian-db.sql
rsync -av /docker/services/librarrarian/ /backup/librarrarian/