docs: fact-check sweep, Jellyfin, *arr stack, and ROM scraping guides

Fact-check results: - RomM 5.2.0: MariaDB+Redis now required (was SQLite), auth var renamed, 11 metadata providers - Copyparty v1.20.19: 3 CVEs fixed, WOPI integration, docker editions documented - Calibre-Web 0.6.27-ls397: version pinning, kepubify auto-config, CVE fixes - Calibre 9.9.0: content server security fix noted New documentation: - docs/Dankserver/Jellyfin.md — full media server guide (compose, Caddy, GPU, metadata, clients) - docs/Dankserver/ARR-Stack.md — automated download stack overview - docs/Dankserver/RomM-Scraping.md — metadata providers, naming, cover art, emulator integration - docs/Dankserver/sonarr.md, radarr.md, lidarr.md, readarr.md, prowlarr.md, qbittorrent.md - docs/Dankserver/mariadb.md, redis.md — supporting services for RomM Infrastructure updates: - dankserver/compose.yaml: added mariadb, redis, jellyfin, *arr services - dankserver/Caddyfile: added hostnames for all new services - dankserver/.env.example: added all new environment variables - docs/index.md: linked all new documentation pages Tested: 52/52 tests pass.
2026-08-20 23:40:07 -07:00
1 parent 34918bf309
commit e8fd009419
@@ -1,26 +1,103 @@
 # RomM

-RomM (ROM Manager) is a self-hosted rom manager and player for retro game collections. It scans a ROM library, enriches it with metadata and cover art, and serves it through a clean web UI.
+RomM (ROM Manager) is a self-hosted ROM library manager and player. It scans a ROM collection, enriches it with metadata and cover art from multiple providers, and serves it through a clean web interface. RomM also supports browser-based emulation via EmulatorJS and native emulator streaming.

 **Host:** Dankserver — **Hostname:** `romm.dankserver.local` — **Docs:** https://docs.romm.app

-## Facts (from research)
+## Facts

 | Item | Value |
 |------|-------|
+| Latest version | 5.2.0 (released 2026-07-29) |
 | Image | `ghcr.io/rommapp/romm:latest` |
 | Port | 8085 (host) → 8080 (container) |
-| Data volume | config, cache, covers, metadata DB |
-| ROMs volume | bind mount to the game library |
-| Frontend | React; backend FastAPI/Node |
-| Metadata | Screenscraper, IGDB, MobyGames, RAHasher (optional) |
+| Database | MariaDB (default); PostgreSQL optional |
+| Cache / Queue | Redis or Valkey (required for task queue) |
+| Frontend | React SPA |
+| Backend | FastAPI / Node |
+| Metadata providers | IGDB, Screenscraper, MobyGames, Hasheous, Playmatch, LaunchBox, Flashpoint, HowLongToBeat, SteamGridDB, RetroAchievements, TGDB, ES-DE gamelist |
+| Emulator player | EmulatorJS (WebAssembly RetroArch cores) |
+| Emulator streaming | Native containers (PCSX2, Dolphin, Xemu) → browser |
+
+## Architecture
+
+RomM 5.2.0 requires three supporting services. The compose stack includes `romm`, `mariadb`, and `redis` (or `valkey`).
+
+```mermaid
+graph LR
+    U[User] --> C[Caddy :80/:443]
+    C --> R[RomM :8085]
+    R --> DB[(MariaDB)]
+    R --> Cache[(Redis)]
+    R --> Lib[/romm/library]
+    R --> Res[/romm/resources]
+```

 ## Configuration

- Set `ROMM_USERNAME`, `ROMM_PASSWORD`, `ROMM_SECRET_KEY` on first boot (creates the admin user).
- `DISABLE_AUTH: true` disables authentication for LAN-only deployments (not recommended behind Caddy auth).
- Bind-mount the ROM library read-only unless RomM should also manage folder structure.
- Metadata providers need API keys; set them in the RomM admin UI after first login.
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ROMM_USERNAME` | Yes | Initial admin username |
+| `ROMM_PASSWORD` | Yes | Initial admin password (set on first boot) |
+| `ROMM_AUTH_SECRET_KEY` | Yes | JWT signing key. Generate with `openssl rand -hex 32`. Replaces the old `ROMM_SECRET_KEY`. |
+| `DB_HOST` | Yes | MariaDB hostname (e.g. `mariadb`) |
+| `DB_NAME` | Yes | Database name (e.g. `romm`) |
+| `DB_USER` | Yes | Database user |
+| `DB_PASSWD` | Yes | Database password |
+| `REDIS_HOST` | Yes | Redis hostname (e.g. `redis`) |
+| `DISABLE_SETUP_WIZARD` | No | Set to `true` to skip the first-run wizard |
+| `OIDC_ENABLED` | No | Enable OpenID Connect authentication |
+| `OIDC_CLIENT_ID` | No | OIDC client ID |
+| `OIDC_CLIENT_SECRET` | No | OIDC client secret |
+| `OIDC_REDIRECT_URI` | No | OIDC redirect URI |
+| `STREAMING_BROKER_SECRET` | No | Secret for native emulator streaming |
+| `STREAMING_SAVE_TIMEOUT` | No | Timeout for save states during streaming |
+| `KIOSK_MODE` | No | Enable kiosk mode |
+| `ROMM_SESSION_SECURE_COOKIE` | No | Secure cookie flag for sessions |
+
+### Metadata Provider Credentials
+
+These are set via environment variables or in `config.yml`:
+
+| Variable | Provider | Notes |
+|----------|----------|-------|
+| `IGDB_CLIENT_ID` / `IGDB_CLIENT_SECRET` | IGDB (Twitch OAuth2) | Create app at Twitch Developer Portal. Free tier: ~10 req/sec. |
+| `SCREENSCRAPER_USER` / `SCREENSCRAPER_PASSWORD` | Screenscraper | Account credentials (not API key). Free, community-driven. |
+| `MOBYGAMES_API_KEY` | MobyGames | Paid hobbyist API. Note: RomM recommends Screenscraper as free alternative. |
+| `RETROACHIEVEMENTS_API_KEY` | RetroAchievements | Hash-based achievements via bundled RAHasher binary. |
+| `STEAMGRIDDB_API_KEY` | SteamGridDB | Custom cover art via the search cover button. |
+| `HASHEOUS_API_ENABLED` | Hasheous | Set to `true`. Free, hash-based, proxies IGDB data. Fast scans. |
+| `PLAYMATCH_API_ENABLED` | Playmatch | Set to `true`. Multi-provider hash matching (IGDB, SS, SteamGridDB, RA). |
+
+### Config File
+
+RomM uses `config.yml` for scan settings, available through the admin UI (Scan Settings). Place the file at `/opt/romm/config/config.yml` on the host.
+
+Key scan config options:
+
+```yaml
+scan:
+  priority:
+    metadata:
+      - igdb
+      - ss        # Screenscraper
+    artwork:
+      - igdb
+      - ss
+    region:
+      - us
+      - eu
+      - jp
+    region_mode: prefer_rom_tags   # or prefer_config
+  media:
+    - box2d
+    - screenshot
+    - manual
+  gamelist:
+    export: true    # Export ES-DE compatible gamelist.xml
+```

 ## Volumes

@@ -28,18 +105,90 @@ RomM (ROM Manager) is a self-hosted rom manager and player for retro game collec
 |----------------|------------------------|
 | `/romm/library` | `/opt/romm/library` |
 | `/romm/resources` | `/opt/romm/resources` |
+| `/romm/config` | `/opt/romm/config` |
+
+The library volume contains ROM files and subdirectories per platform. The resources volume stores cached artwork, metadata, and the SQLite/SQLite-backed asset cache. The config volume holds `config.yml` and other configuration.
+
+## Docker Compose
+
+```yaml
+services:
+  romm:
+    image: ghcr.io/rommapp/romm:latest
+    container_name: romm
+    restart: unless-stopped
+    environment:
+      ROMM_USERNAME: "${ROMM_USERNAME}"
+      ROMM_PASSWORD: "${ROMM_PASSWORD}"
+      ROMM_AUTH_SECRET_KEY: "${ROMM_AUTH_SECRET_KEY}"
+      DB_HOST: mariadb
+      DB_NAME: romm
+      DB_USER: "${ROMM_DB_USER}"
+      DB_PASSWD: "${ROMM_DB_PASSWD}"
+      REDIS_HOST: redis
+    ports:
+      - "8085:8080"
+    volumes:
+      - /opt/romm/library:/romm/library
+      - /opt/romm/resources:/romm/resources
+      - /opt/romm/config:/romm/config
+    depends_on:
+      mariadb:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+
+  mariadb:
+    image: docker.io/mariadb:11
+    container_name: romm-mariadb
+    restart: unless-stopped
+    environment:
+      MARIADB_ROOT_PASSWORD: "${MARIADB_ROOT_PASSWORD}"
+      MARIADB_DATABASE: romm
+      MARIADB_USER: "${ROMM_DB_USER}"
+      MARIADB_PASSWORD: "${ROMM_DB_PASSWD}"
+    volumes:
+      - /opt/romm/mariadb:/var/lib/mysql
+    healthcheck:
+      test: ["CMD", "mariadb-admin", "ping", "-h", "localhost"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+
+  redis:
+    image: docker.io/redis:7-alpine
+    container_name: romm-redis
+    restart: unless-stopped
+    volumes:
+      - /opt/romm/redis:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+```

 ## Healthcheck

-Expose a `/health` endpoint; RomM serves the UI on `/`.
+```yaml
+healthcheck:
+  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+  interval: 30s
+  timeout: 10s
+  retries: 3
+```

 ## Gotchas

- The first login sets the admin password; do not rely on the env credentials after that.
- Database is SQLite by default — back it up with the resources volume.
- RAHasher build increases image build time; skip unless RetroAchievements hashes are needed.
+- **First login overwrites env credentials.** The `ROMM_PASSWORD` env var sets the initial password. After first login, the admin password is controlled in the UI. The env var only applies on first boot.
+- **MariaDB and Redis are required.** RomM 5.2.0 no longer supports SQLite-only deployments. Both MariaDB and Redis must be running.
+- **Reverse proxy cache stale index.html.** Purge Caddy proxy cache after RomM version bumps to avoid serving a stale frontend after an upgrade.
+- **RAHasher build time.** Enabling RetroAchievements hashing increases the first image build. Skip unless you need achievement data.
+- **MobyGames is paid.** The hobbyist API has strict rate limits. Screenscraper is the recommended free alternative.
+- **OIDC requires additional services.** Authentik, Keycloak, or another OIDC provider must be running before enabling `OIDC_ENABLED`.

 ## See Also

 - [[Dankserver Stack]]
+- [[RomM Scraping]] — metadata providers, cover art, naming conventions, emulator integration
 - [[Calibre-Web]] — sibling library web UI