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 |
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
internal — Bridge network for dashboard ↔ database ↔ worker communication.cloudflare-net — Routes the dashboard to transcode.m1ckyb.com via Cloudflare Tunnel.- Worker accesses the dashboard API at
http://librarrarian:5000.
4. Persistent Storage
| Container |
Host Path / Volume |
Description |
db |
postgres_data (named vol) |
PostgreSQL data |
librarrarian |
/docker/services/librarrarian |
Application data and config |
librarrarian |
/nfs/media/ |
NFS media library (read) |
librarrarian-worker-1 |
/nfs/media/ |
NFS media library (read/write for transcoding) |
5. Environment Variables
| Variable |
Service |
Description |
DB_HOST / DB_USER / DB_PASSWORD / DB_NAME |
All |
PostgreSQL connection details |
API_KEY |
Dashboard + Worker |
Shared key for worker authentication |
FLASK_SECRET_KEY |
Dashboard |
Flask session signing key |
AUTH_ENABLED |
Dashboard |
Master auth switch (true/false) |
OIDC_ENABLED |
Dashboard |
Enable OIDC SSO |
OIDC_ISSUER_URL |
Dashboard |
OIDC provider URL |
OIDC_CLIENT_ID / OIDC_CLIENT_SECRET |
Dashboard |
OIDC app credentials |
LOCAL_LOGIN_ENABLED |
Dashboard |
Enable local username/password fallback |
PASSKEY_ENABLED |
Dashboard |
Enable WebAuthn passkeys |
MEDIA_PATHS |
Worker |
Comma-separated allowed media paths |
AUTOSTART |
Worker |
Auto-start processing on container launch |
TZ |
All |
Timezone |
[!NOTE]
Requires login to GitHub Container Registry before first pull: docker login ghcr.io -u YOUR-USERNAME -p YOUR-PAT
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/