docs: rename docs/ -> serverAppConfigs-docs/ per system-wide PROJECTNAME-docs convention

All in-repo path references (AGENTS.md, README, old scripts, report artifacts, test code paths) rewritten in the same commit; focused-test map extended for .gitignore, old/scripts/*, dankclaw/comfyui/*, and report/* per this repo's own convention ('add one before committing'). Obsidian wikilinks are title-based and unaffected.
2026-08-28 02:20:06 -07:00
1 parent 6d4a96a423
commit 5829a0bfe8
@@ -0,0 +1,194 @@
+# RomM
+
+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
+
+| Item | Value |
+|------|-------|
+| Latest version | 5.2.0 (released 2026-07-29) |
+| Image | `ghcr.io/rommapp/romm:latest` |
+| Port | 8085 (host) → 8080 (container) |
+| 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
+
+### 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
+
+| Container path | Host path (convention) |
+|----------------|------------------------|
+| `/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
+
+```yaml
+healthcheck:
+  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+  interval: 30s
+  timeout: 10s
+  retries: 3
+```
+
+## Gotchas
+
+- **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