RomM is configured entirely through environment variables, which you can set directly in yourDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/rommapp/romm/llms.txt
Use this file to discover all available pages before exploring further.
docker-compose.yml file under the environment: key or in a separate .env file referenced by Docker Compose. The env.template file in the RomM repository documents every available variable with inline comments and is the canonical reference for default values.
Core Application
Base folder path for the library, resources, and assets. All sub-paths (library, resources, assets) are derived from this value.
Custom temporary directory path. Defaults to the system temp directory when left unset.
Public-facing URL of this RomM instance. Used when generating absolute links (e.g., OIDC redirects).
Port on which the application listens inside the container.
Enables read-only mode. Intended for public displays or kiosks where users should not modify the library.
Database
DB_HOST, DB_USER, and DB_PASSWD are required. RomM will not start without a reachable database.Hostname of the database instance (e.g.,
mariadb when using the bundled Docker Compose stack).Port number of the database instance.
Database name. Should match the
MYSQL_DATABASE (or MARIADB_DATABASE) value used when creating the database container.Database username. Should match the
MARIADB_USER value in the MariaDB/MySQL container.Database password. Should match the
MARIADB_PASSWORD value in the MariaDB/MySQL container.Root user password for the database. Only consumed by the bundled MariaDB container — not used by RomM itself.
Database driver. Accepted values:
mariadb, mysql, postgresql.Extra query parameters for the database connection URL, expressed as a JSON object (e.g.,
{"charset": "utf8mb4"}).Redis / Valkey
Hostname of the Redis or Valkey instance used for caching and task queuing.
Port number of the Redis/Valkey instance.
Username for Redis/Valkey authentication (ACL-based auth). Leave empty for password-only auth.
Password for the Redis/Valkey instance.
Redis/Valkey logical database index.
Enable TLS (
rediss://) for the Redis/Valkey connection.Authentication
ROMM_AUTH_SECRET_KEY is required. Generate a strong value with openssl rand -hex 32 and keep it secret — rotating this key will invalidate all active sessions.Application secret used to sign tokens and sessions. Generate with
openssl rand -hex 32.OAuth2 access token lifetime in seconds (default: 30 minutes).
OAuth2 refresh token lifetime in seconds (default: 7 days).
Maximum age of a browser session in seconds (default: 14 days).
Lifetime of user invite tokens in seconds (default: 10 minutes).
Disable authentication on the download endpoint. Required for certain integrations such as WebRcade and Tinfoil that cannot pass credentials.
Disable CSRF protection. Not recommended unless you understand the security implications.
Hide the username/password login form. Use when relying exclusively on OIDC so local login cannot be used as a fallback.
Skip the first-boot setup wizard. Useful when deploying RomM non-interactively with a pre-configured environment.
Disable the backend log viewer in the RomM UI.
OpenID Connect (OIDC)
OIDC support lets you delegate authentication to an external identity provider (e.g., Authentik, Keycloak, Authelia). At minimum you need
OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, and OIDC_SERVER_METADATA_URL.Enable OpenID Connect authentication.
Skip the OIDC button on the login page and automatically redirect users to the identity provider.
Automatically create a new RomM account for users on their first successful OIDC login.
Display name of the OIDC provider shown on the login page (e.g.,
Authentik).Client ID issued by the OIDC provider.
Client secret issued by the OIDC provider.
Absolute redirect URI registered with the OIDC provider (e.g.,
https://romm.example.com/api/oauth/openid).Absolute URL of the OIDC server application. Used to construct provider URLs when
OIDC_SERVER_METADATA_URL is not set.URL to the OIDC provider’s discovery / metadata endpoint (e.g.,
https://auth.example.com/application/o/romm/.well-known/openid-configuration).Name of the OIDC claim that carries role information (e.g.,
groups).Role value in the OIDC claim that maps to the viewer permission level.
Role value in the OIDC claim that maps to the editor permission level.
Role value in the OIDC claim that maps to the admin permission level.
Path to a PEM file containing trusted CA certificates, for when your OIDC provider uses a private or self-signed TLS certificate.
The attribute from the OIDC user-info response used as the RomM username.
Enable the RP-initiated logout flow so that logging out of RomM also ends the session at the identity provider.
Override URL for the OIDC end-session endpoint (used by RP-initiated logout when the provider does not advertise it in metadata).
Metadata Providers
Client ID for the IGDB API. Obtain from the Twitch developer console.
Client secret for the IGDB API (paired with
IGDB_CLIENT_ID).Secret API key for the MobyGames API. Generate one at mobygames.com.
Screenscraper username. Register at screenscraper.fr.
Screenscraper password (paired with
SCREENSCRAPER_USER).Secret API key for SteamGridDB. Generate one in your SteamGridDB account preferences.
Secret API key for RetroAchievements. Generate one at retroachievements.org/settings.
How often (in days) to refresh the cached RetroAchievements metadata for each ROM.
Enable the PlayMatch API integration for ROM identification.
Enable the LaunchBox metadata integration. When enabled, RomM downloads and updates the LaunchBox database on a scheduled basis.
Enable the Hasheous API for hash-based ROM identification. No API key required.
Enable the Flashpoint Project API for web-game metadata.
Enable the HowLongToBeat API for game completion-time data.
Enable the TheGamesDB API integration.
Scans & Tasks
Timeout for background scan/rescan tasks in seconds (default: 4 hours).
Number of worker processes dedicated to scanning tasks.
Timeout for non-scan background tasks in seconds (default: 5 minutes).
How long to retain task results in Valkey/Redis in seconds (default: 24 hours).
Timeout for individual 7-Zip operations in seconds.
Automatically trigger a library rescan when the filesystem detects changes inside the ROMs folder.
Delay in minutes to wait after a filesystem change before starting the rescan (debounce).
Enable a cron-based scheduled library rescan.
Cron expression controlling when scheduled rescans run (default: 3:00 AM daily).
Enable a scheduled task to update the Nintendo Switch TitleDB index used for ROM matching.
Cron expression for scheduled Switch TitleDB updates (default: 4:00 AM daily).
Enable a scheduled task to download and update the LaunchBox metadata database.
Cron expression for scheduled LaunchBox metadata updates (default: 4:00 AM daily).
Enable a scheduled task to convert all cached artwork to WebP format to reduce disk usage.
Cron expression for scheduled WebP image conversion (default: 4:00 AM daily).
Enable scheduled syncing of user RetroAchievements progress.
Cron expression for scheduled RetroAchievements progress sync (default: 4:00 AM daily).
Sync
Watch the sync folder and trigger a scan automatically when changes are detected.
Delay in minutes before scanning after a sync folder change (debounce).
Enable scheduled sync push/pull operations.
Cron expression for scheduled sync push/pull (default: every 30 minutes).
Path to SSH keys used for sync remotes.
Path to the SSH
known_hosts file for sync remotes.Emulation
Disable in-browser ROM playback via EmulatorJS.
Disable in-browser Flash playback via RuffleRS.
Integrations
Welcome message displayed in Tinfoil Nintendo Switch clients when browsing the RomM library.
Web Server
Number of Gunicorn worker processes. The recommended formula is
2 × CPU cores + 1.Request timeout for the web server in seconds.
Keep-Alive connection wait time in seconds.
Maximum number of requests a worker processes before it is automatically restarted (helps prevent memory leaks).
Random jitter added to
WEB_SERVER_MAX_REQUESTS to stagger worker restarts and avoid all workers cycling simultaneously.Maximum number of simultaneous clients per worker process.
Seconds to wait for Gunicorn to start before giving up and failing the health check.
Bind the web server to IPv4 addresses only (disables IPv6 socket binding).
Proxy
HTTP proxy URL for outbound requests made by RomM (e.g.,
http://proxy.example.com:3128).HTTPS proxy URL for outbound requests (e.g.,
http://proxy.example.com:3128).Comma-separated list of hostnames or IP addresses that should bypass the configured proxy.
Logging
Application log level. Accepted values:
DEBUG, INFO, WARNING, ERROR, CRITICAL.Force ANSI color codes in log output even when the terminal does not advertise color support.
Disable ANSI color codes in log output entirely.
Observability
DSN (Data Source Name) for Sentry error tracking. When set, unhandled exceptions and performance traces are sent to your Sentry project. Leave empty to disable Sentry entirely.
Development
These variables are intended for contributors running RomM outside of Docker (e.g., with Uvicorn or the Vite dev server). They are not needed in production deployments.Enable development mode, which activates hot-reloading and verbose debug output.
Host address for the development server.
Port for the development server.
Enable HTTPS in the development server.
Log all SQL queries to stdout in development mode. Useful for diagnosing database behaviour.
Postgres database name for the bundled Authentik development stack. Not used by RomM itself.
Postgres username for the bundled Authentik development stack.
Postgres password for the bundled Authentik development stack.
Secret key for the Authentik identity provider in the development stack.
Initial admin password for the Authentik identity provider in the development stack.