Skip to content

docs: cover 5.1.0-beta.1 and beta.2 env vars and config #106

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gantoine merged 1 commit into from
Jul 27, 2026
Merged

docs: cover 5.1.0-beta.1 and beta.2 env vars and config #106

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/getting-started/metadata-providers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,8 @@ To enable Playmatch, set `PLAYMATCH_API_ENABLED=true` in your environment variab

When Playmatch is enabled, manually matching a ROM through the edit dialog also forwards the ROM's hashes, filename, filesize and resolved provider IDs as a suggestion to Playmatch. Suggestions are reviewed manually before being added to the Playmatch database, which helps improve match quality for the wider community over time.

By default RomM talks to the community-hosted Playmatch instance. To point at your own [self-hosted Playmatch](https://github.com/RetroRealm/playmatch), set `PLAYMATCH_API_URL` to its API base (e.g. `https://playmatch.example.com/api/v2`).

### SteamGridDB

SteamGridDB provides custom cover art for games or collections. It's not accessed through the scanner but from the "search cover" button when manually editing a game.
Expand Down
13 changes: 13 additions & 0 deletions docs/install/reverse-proxy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,3 +187,16 @@ environment:
```

If you're also using OIDC, update `OIDC_REDIRECT_URI` to match (see [OIDC Setup](../administration/oidc/index.md)).

## Harden cookies and CORS behind HTTPS

Two optional env vars tighten browser security once you're on HTTPS:

```yaml
environment:
- ROMM_SESSION_SECURE_COOKIE=true
- ROMM_CORS_ALLOWED_ORIGINS=https://romm.mysite.com
```

- `ROMM_SESSION_SECURE_COOKIE` marks the session and CSRF cookies `Secure` so browsers only send them over HTTPS. Leave it `false` if you still reach the instance over plain HTTP, or logins will silently fail.
- `ROMM_CORS_ALLOWED_ORIGINS` is a comma-separated allowlist of origins permitted to call the API from a browser. An empty value (the default) allows any origin, so set it to your public URL (plus any companion-app origins) when you want to lock cross-origin requests down.
17 changes: 17 additions & 0 deletions docs/reference/configuration-file.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,6 +209,23 @@ scan:
- "moby"
```

### `scan.priority.cover`, `scan.priority.screenshot`, `scan.priority.manual`

Optional per-field overrides that let you prioritise sources differently for each artwork type. Any field you omit falls back to the shared [`scan.priority.artwork`](#scanpriorityartwork) order, so only set the ones you want to diverge.

```yaml
scan:
priority:
cover: # Cover art only
- "igdb"
- "ss"
screenshot: # Screenshots only
- "ss"
- "igdb"
manual: # Game manuals only
- "launchbox"
```

### `scan.priority.region`

Preferred region for titles, cover art, and regional variants. ScreenScraper uses this directly, and other providers respect it where possible.
Expand Down
78 changes: 47 additions & 31 deletions docs/resources/snippets/env-vars.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,40 +36,42 @@

### Authentication

| Variable | Default | Required | Description |
| ------------------------------------ | --------- | :------: | ---------------------------------------------------------- |
| `ROMM_AUTH_SECRET_KEY` | | `✓` | App secret, generate with `openssl rand -hex 32` |
| `OAUTH_ACCESS_TOKEN_EXPIRE_SECONDS` | `1800` | | Access token lifetime in seconds |
| `OAUTH_REFRESH_TOKEN_EXPIRE_SECONDS` | `604800` | | Refresh token lifetime in seconds |
| `SESSION_MAX_AGE_SECONDS` | `1209600` | | Maximum age of a session in seconds |
| `INVITE_TOKEN_EXPIRY_SECONDS` | `600` | | Invite token lifetime in seconds |
| `DISABLE_DOWNLOAD_ENDPOINT_AUTH` | `false` | | Disable auth on the download endpoint for WebRcade/Tinfoil |
| `DISABLE_CSRF_PROTECTION` | `false` | | Disable CSRF protection (not recommended) |
| `DISABLE_USERPASS_LOGIN` | `false` | | Disable username/password login when using OIDC |
| `DISABLE_SETUP_WIZARD` | `false` | | Skip the first-boot setup wizard |
| `DISABLE_LOGS_VIEWER` | `false` | | Disable the backend logs viewer |
| Variable | Default | Required | Description |
| ------------------------------------ | --------- | :------: | -------------------------------------------------------------------- |
| `ROMM_AUTH_SECRET_KEY` | | `✓` | App secret, generate with `openssl rand -hex 32` |
| `OAUTH_ACCESS_TOKEN_EXPIRE_SECONDS` | `1800` | | Access token lifetime in seconds |
| `OAUTH_REFRESH_TOKEN_EXPIRE_SECONDS` | `604800` | | Refresh token lifetime in seconds |
| `SESSION_MAX_AGE_SECONDS` | `1209600` | | Maximum age of a session in seconds |
| `INVITE_TOKEN_EXPIRY_SECONDS` | `600` | | Invite token lifetime in seconds |
| `DISABLE_DOWNLOAD_ENDPOINT_AUTH` | `false` | | Disable auth on the download endpoint for WebRcade/Tinfoil |
| `DISABLE_CSRF_PROTECTION` | `false` | | Disable CSRF protection (not recommended) |
| `DISABLE_USERPASS_LOGIN` | `false` | | Disable username/password login when using OIDC |
| `DISABLE_SETUP_WIZARD` | `false` | | Skip the first-boot setup wizard |
| `DISABLE_LOGS_VIEWER` | `false` | | Disable the backend logs viewer |
| `ROMM_CORS_ALLOWED_ORIGINS` | | | Comma-separated list of allowed CORS origins (empty allows all) |
| `ROMM_SESSION_SECURE_COOKIE` | `false` | | Mark session and CSRF cookies Secure (enable when served over HTTPS) |

### OpenID Connect

| Variable | Default | Required | Description |
| ----------------------------- | -------------------- | :------: | ------------------------------------------------------------------------------------------- |
| `OIDC_ENABLED` | `false` | | Enable OpenID Connect authentication |
| `OIDC_AUTOLOGIN` | `false` | | Skip the OIDC button on the login page and auto-redirect |
| `OIDC_ALLOW_REGISTRATION` | `true` | | Allow new accounts to be created automatically on first OIDC login |
| `OIDC_PROVIDER` | | | Name of the OIDC provider in use |
| `OIDC_CLIENT_ID` | | | Client ID for OIDC authentication |
| `OIDC_CLIENT_SECRET` | | | Client secret for OIDC authentication |
| `OIDC_REDIRECT_URI` | | | Absolute redirect URI for OIDC authentication |
| `OIDC_SERVER_APPLICATION_URL` | | | Absolute URL of the OIDC server application |
| `OIDC_SERVER_METADATA_URL` | | | URL to the OIDC provider metadata endpoint |
| `OIDC_CLAIM_ROLES` | | | OIDC claim containing user roles |
| `OIDC_ROLE_VIEWER` | | | Group value granting the User role (grants non-admins login when `OIDC_CLAIM_ROLES` is set) |
| `OIDC_ROLE_EDITOR` | | | Group value granting the User role (same effect as viewer) |
| `OIDC_ROLE_ADMIN` | | | Role value mapping to admin permissions |
| `OIDC_TLS_CACERTFILE` | | | Path to file containing trusted CA certificates |
| `OIDC_USERNAME_ATTRIBUTE` | `preferred_username` | | Attribute on OIDC user info used as the username |
| `OIDC_RP_INITIATED_LOGOUT` | `false` | | Enable RP-initiated logout flow |
| `OIDC_END_SESSION_ENDPOINT` | | | OIDC end-session endpoint override URL |
| Variable | Default | Required | Description |
| ----------------------------- | -------------------- | :------: | ------------------------------------------------------------------ |
| `OIDC_ENABLED` | `false` | | Enable OpenID Connect authentication |
| `OIDC_AUTOLOGIN` | `false` | | Skip the OIDC button on the login page and auto-redirect |
| `OIDC_ALLOW_REGISTRATION` | `true` | | Allow new accounts to be created automatically on first OIDC login |
| `OIDC_PROVIDER` | | | Name of the OIDC provider in use |
| `OIDC_CLIENT_ID` | | | Client ID for OIDC authentication |
| `OIDC_CLIENT_SECRET` | | | Client secret for OIDC authentication |
| `OIDC_REDIRECT_URI` | | | Absolute redirect URI for OIDC authentication |
| `OIDC_SERVER_APPLICATION_URL` | | | Absolute URL of the OIDC server application |
| `OIDC_SERVER_METADATA_URL` | | | URL to the OIDC provider metadata endpoint |
| `OIDC_CLAIM_ROLES` | | | OIDC claim containing user roles |
| `OIDC_ROLE_VIEWER` | | | Role value mapping to viewer permissions |
| `OIDC_ROLE_EDITOR` | | | Role value mapping to editor permissions |
| `OIDC_ROLE_ADMIN` | | | Role value mapping to admin permissions |
| `OIDC_TLS_CACERTFILE` | | | Path to file containing trusted CA certificates |
| `OIDC_USERNAME_ATTRIBUTE` | `preferred_username` | | Attribute on OIDC user info used as the username |
| `OIDC_RP_INITIATED_LOGOUT` | `false` | | Enable RP-initiated logout flow |
| `OIDC_END_SESSION_ENDPOINT` | | | OIDC end-session endpoint override URL |

### Metadata Providers

Expand Down Expand Up @@ -137,6 +139,13 @@
| `YOUTUBE_BASE_URL` | `https://www.youtube.com` | | Base URL for alternate YouTube frontends (Piped, Invidious, etc.) |
| `TINFOIL_WELCOME_MESSAGE` | `RomM Switch Library` | | Welcome message shown in Tinfoil Switch clients |

### Assets

| Variable | Default | Required | Description |
| ----------------------------- | ----------- | :------: | ---------------------------------------------------------------------------------- |
| `MAX_ASSET_UPLOAD_SIZE_BYTES` | `536870912` | | Max size of a save/state/screenshot upload request in bytes (0 disables the limit) |
| `MAX_AUTOCLEANUP_LIMIT` | `100` | | Max number of saves a client can keep per slot when autocleanup is on (minimum 1) |

### Logging

| Variable | Default | Required | Description |
Expand Down Expand Up @@ -186,3 +195,10 @@
| `POSTGRES_PASSWORD` | `authentik` | | Postgres password for the Authentik dev stack |
| `AUTHENTIK_SECRET_KEY` | | | Authentik secret key |
| `AUTHENTIK_BOOTSTRAP_PASSWORD` | | | Initial Authentik admin bootstrap password |

### Emulator Streaming

| Variable | Default | Required | Description |
| ------------------------- | ------- | :------: | --------------------------------------------------------------------------------- |
| `STREAMING_BROKER_SECRET` | | | - |
| `STREAMING_SAVE_TIMEOUT` | `45` | | Seconds to wait for a broker save-and-exit (raise if a broker has SAVE_WAIT > 45) |
Loading
Loading