This guide will assume that you already have the following done, if not - stop here and come back when you do.
Welcome to the RomM Project, the premier self-hosted, open source ROM manager.
Website | DemoRomM (ROM Manager) allows you to scan, enrich, and browse your game collection with a clean and responsive interface. With support for multiple platforms, various naming schemes, and custom tags, RomM is a must-have for anyone who plays on emulators.
To get started with RomM, head over to the Quick Start guide in the main repository.
"},{"location":"#philosophy","title":"Philosophy","text":"At the heart of this project is a commitment to freedom, collaboration, and transparency. We believe that software should be built for the benefit of its users, rather than solely to maximize profit or serve the interests of a few stakeholders, ensuring that it doesn't manipulate, exploit, or prioritize data collection.
By offering RomM as a self-hosted, open-source solution, we ensure that everyone has the ability to manage their game collections on their own terms, and own their data, all without being tied to proprietary systems or services.
Rom is and will always be free and open-source software.
The core app is licensed under GNU AGPLv3, which requires that all modifications to the code be made available under the same license. This ensures that the community can benefit from and build upon the contributions of others, promoting trust and transparency.
Other projects under the umbrella will be licensed under similar permissive licenses, such as GNU GPLv3 for software, or CC0 for documentation.
"},{"location":"#contributing","title":"Contributing","text":"RomM is a collaborative project, and we welcome contributions from the community. Our code is available on GitHub, and we encourage you to contribute to the project by submitting bug reports, feature requests, or pull requests. Please check the contribution guidelines in each project for more information.
"},{"location":"#community","title":"Community","text":"We strive to create a safe and respectful space where everyone can contribute and benefit from the project by fostering a welcoming and inclusive environment for all users, regardless of their background or identity.
Join us on Discord, where you can ask questions, submit ideas, get help, showcase your collection, and discuss RomM with other users.
"},{"location":"Getting-Started/Authentication/","title":"Authentication","text":"RomM provides support for various forms of authentication, granting flexibility in securing access to its features.
"},{"location":"Getting-Started/Authentication/#setup","title":"Setup","text":"You'll want to set the following environment variable before starting RomM:
ROMM_AUTH_SECRET_KEY is required and can be generated with openssl rand -hex 32When the /login endpoint is called with valid credentials, a session_id is generated, stored as a cookie and sent to the browser. The same token is used to create a cache entry in Redis (or in-memory if Redis is disabled) which maps the token to the user. This way no sensitive information is stored on the client.
A user can have one of the following roles:
As permissions are additive, editors will have all permissions of the viewer role, and admins all those of the editor role.
Requests can be made to protected API endpoints with an authorization header. The token is the base64 encoded value of username:password.
Example using cURL:
curl https://romm.local/api/platforms -H 'Authorization: Basic YWRtaW46aHVudGVyMg=='\nAlong with the above forms of authentication, we've added an endpoint to generate expiring, scope-limited authentication tokens (/api/token). Successfully authenticating with that endpoint with return an access_token valid for 15 minutes, and a refresh_token valid for 2 weeks. The refresh_token can be used to generate a new access_token when needed.
The /api/token endpoint requires a username, password, and a list of scopes in the format read:roms write:roms read:platforms .... The list of scopes and endpoints are available to browse via Swagger UI or ReDoc (see next section).
Note: As of now, only the legacy password grant type is supported. We plan to eventually add support for Client Credentials.
"},{"location":"Getting-Started/Authentication/#openapi","title":"OpenAPI","text":"The API endpoints are fully documented and compliant with the OpenAPI specification. Explore the API endpoints using the Swagger UI interface at /api/docs and the ReDoc interface at /api/redoc, or view the raw JSON at /openapi.json.
For more information on OpenAPI, visit the OpenAPI Specification website.
"},{"location":"Getting-Started/Authentication/#faq","title":"FAQ","text":""},{"location":"Getting-Started/Authentication/#can-i-disable-authentication","title":"Can I disable authentication?","text":"No, authentication is required and enabled by default.
"},{"location":"Getting-Started/Authentication/#i-want-to-allow-an-editor-to-edit-roms-but-not-delete-them-can-i-do-that","title":"I want to allow an EDITOR to edit ROMs but not delete them. Can I do that?","text":"At this time, fine-grain control over permissions within a role is not supported. This decision was taking in order to simplify user management in the client, and authentication/permission code on the server.
"},{"location":"Getting-Started/Authentication/#is-authentication-saferobust-can-i-trust-it","title":"Is authentication safe/robust? Can I trust it?","text":"We've done our best to build an authentication system that is simple, clear and comprehensible. We have automated tests which verify that access is granted when it should be, and blocked when not (invalid credentials, missing permissions, expired access tokens, etc.). That being said, we welcome any reviews of our authentication and permission flows, PRs to fix issues, and new tests to cover edge cases.
"},{"location":"Getting-Started/Authentication/#i-found-an-bugissue-with-authentication-how-do-i-report-it","title":"I found an bug/issue with authentication. How do I report it?","text":"Please report bugs in our authentication/permission system privately by submitting a vulnerability report.
"},{"location":"Getting-Started/Environment-Variables/","title":"Environment Variables","text":"This is a complete list of available environment variables; required variables are marked with a \u2713.
Tip
You can also set environment variables with a _FILE suffix, which will load the contents of the file specified in the variable into the variable without the suffix. For example, setting ROMM_AUTH_SECRET_KEY_FILE=/run/secrets/romm_auth_secret_key and creating a file with the secret key at the specified path will set ROMM_AUTH_SECRET_KEY to the contents of the file. Learn more.
openssl rand -hex 32 \u2713 DISABLE_CSRF_PROTECTION Disables CSRF protection (not recommended) false DISABLE_DOWNLOAD_ENDPOINT_AUTH Disable auth on download endpoint (WebRcade, Tinfoil) false DISABLE_USERPASS_LOGIN Disables login with username and password (when using OIDC) false UPLOAD_TIMEOUT Timeout for file uploads (in seconds) 600 SCAN_TIMEOUT Timeout for the background scan/rescan tasks (in seconds) 14400 DISABLE_EMULATOR_JS Disables playing in browser with EmulatorJS false DISABLE_RUFFLE_RS Disables playing flash games with RuffleRS false TZ Sets the timezone UTC GUNICORN_WORKERS Number of processes running the app 2 ROMM_BASE_PATH Base folder path for library, resources and assets /romm LOGLEVEL Logging level for the app INFO FORCE_COLOR Forces color output false NO_COLOR Disables color output false"},{"location":"Getting-Started/Environment-Variables/#dependencies","title":"Dependencies","text":"Variable Description Required Default DB_HOST Host name of database instance \u2713 127.0.0.1 DB_PORT Port number of database instance 3306 DB_NAME Should match MYSQL_DATABASE in MariaDB romm DB_USER Database username (in MariaDB, should match MARIADB_USER) \u2713 DB_PASSWD Database password (in MariaDB, should match MARIADB_PASSWORD) \u2713 ROMM_DB_DRIVER Database driver to use (options: mariadb, mysql, postgresql) mariadb REDIS_HOST Host name of Redis/Valkey instance 127.0.0.1 REDIS_PORT Port number of Redis/Valkey instance 6379 REDIS_USERNAME Username for Redis/Valkey instance REDIS_PASSWORD Password for Redis/Valkey instance REDIS_DB Database number for Redis/Valkey instance 0 REDIS_SSL Enable SSL for Redis instance false SENTRY_DSN DSN for Sentry error tracking"},{"location":"Getting-Started/Environment-Variables/#metadata-providers","title":"Metadata providers","text":"Variable Description Required Default IGDB_CLIENT_ID Client ID for IGDB API IGDB_CLIENT_SECRET Client secret for IGDB API MOBYGAMES_API_KEY MobyGames secret API key STEAMGRIDDB_API_KEY SteamGridDB secret API key"},{"location":"Getting-Started/Environment-Variables/#authentication","title":"Authentication","text":"Variable Description Required Default OIDC_ENABLED Enable OpenID Connect (OIDC) authentication false 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_TLS_CACERTFILE Path to a file containing trusted CA certificates"},{"location":"Getting-Started/Environment-Variables/#background-tasks","title":"Background tasks","text":"Variable Description Required Default ENABLE_RESCAN_ON_FILESYSTEM_CHANGE Enable re-scanning of library when filesystem changes false RESCAN_ON_FILESYSTEM_CHANGE_DELAY Delay in minutes before re-scanning library when filesystem changes 5 ENABLE_SCHEDULED_RESCAN Enable scheduled re-scanning of library false SCHEDULED_RESCAN_CRON Cron expression for scheduled re-scanning \"0 3 * * *\" ENABLE_SCHEDULED_UPDATE_SWITCH_TITLEDB Enable scheduled updating of Switch TitleDB index false SCHEDULED_UPDATE_SWITCH_TITLEDB_CRON Cron expression for scheduled updating of Switch TitleDB \"0 4 * * *\""},{"location":"Getting-Started/Generate-API-Keys/","title":"Generate API Keys","text":""},{"location":"Getting-Started/Generate-API-Keys/#igdb","title":"IGDB","text":"To access the IGDB API you'll need a Twitch account and a valid phone number for 2FA verification. Up-to-date instructions are available in the IGDB API documentation. When registering your application in the Twitch Developer Portal, fill out the form like so:
correct-horse-battery-staple or KVV8NDXMSRFJ2MRNPNRSL7GQTlocalhostApplication IntegrationConfidentialImportant
The name you pick has to be unique! Picking an existing name will fail silently, with no error messages. We recommend using romm-<random hash>, like romm-3fca6fd7f94dea4a05d029f654c0c44b
Note the client ID and secret that appear on screen, and use them to set IGDB_CLIENT_ID and IGDB_CLIENT_SECRET in your environment variables.
To access the MobyGames API, create a MobyGames account and then visit your profile page. Click the API link under your user name to sign up for an API key. Copy the key shown and use it to set MOBYGAMES_API_KEY.
Important
MobyGames API became a paid feature. Any existing key can be used as usual, but any new API key created will be under a paywall
"},{"location":"Getting-Started/Generate-API-Keys/#steamgriddb","title":"SteamGridDB","text":"To access steamGridDB API, you need to login into their website with a steam account. Once logged in, go to your API tab under the preferences page. Copy the key shown and use it to set STEAMGRIDDB_API_KEY.
This quick start guide will help you get a RomM instance up and running. It is split into 3 parts:
This guide will assume that you already have the following done, if not - stop here and come back when you do.
Warning
Not setting up RomM with a metadata API will work for basic operation but can cause issues with, for instance, the Playnite plugin. It is recommended to setup IGDB API keys to avoid issues during setup.
"},{"location":"Getting-Started/Quick-Start-Guide/#twitch-and-mobygames-api-keys","title":"Twitch and MobyGames API Keys","text":"Head over to API key docs to get your Twitch and/or MobyGames keys, then come back here
"},{"location":"Getting-Started/Quick-Start-Guide/#generating-authentication-keys","title":"Generating Authentication Keys","text":"This step will generate a key that is used in the authorization of RomM. Without this, you will be unable to log in and use the platform
Run the following command in a terminal:
openssl rand -hex 32\nThen copy the output and save it to the ROMM_AUTH_SECRET_KEY variable in the docker-compose file. It should look like this:
~$: openssl rand -hex 32\n03a054b6ca27e0107c5eed552ea66becd9f3a2a8a91e7595cd462a593f9ecd09\nNow that we have everything gathered, we can begin getting your instance set up!
MYSQL_ROOT_PASSWORD: Sets the root password of the database. Use a unique and secure password (use a password generator for simplicity)MYSQL_DATABASE: Sets the database name for RomM. This can be modified - but it's not necessaryMYSQL_USER: User to connect to the database with. This can be modified - but it's not necessaryMYSQL_PASSWORD: Password for the user to connect to the database with. Use a unique and secure password (use a password generator for simplicity)DB_NAME: Name of the database set in the database sectionDB_USER: Name of the user to connect to the databaseDB_PASSWD: Password of the user to connect to the database/path/to/library: Path to the directory where your rom files will be stored/path/to/assets: Path to the directory where you will store your saves, etc/path/to/config: Path to the directory where you will store the config.ymlSave the file as docker-compose.yml instead of docker-compose.example.yml. It should look something like this:
Example Docker Composeversion: \"3\"\n\nvolumes:\n mysql_data:\n romm_resources:\n romm_redis_data:\n\nservices:\n romm:\n image: rommapp/romm:latest\n container_name: romm\n restart: unless-stopped\n environment:\n - DB_HOST=romm-db\n - DB_NAME=romm # Should match MARIADB_DATABASE in mariadb\n - DB_USER=romm-user # Should match MARIADB_USER in mariadb\n - DB_PASSWD= # Should match MARIADB_PASSWORD in mariadb\n - ROMM_AUTH_SECRET_KEY= # Generate a key with `openssl rand -hex 32`\n - IGDB_CLIENT_ID= # Generate an ID and SECRET in IGDB\n - IGDB_CLIENT_SECRET= # https://api-docs.igdb.com/#account-creation\n - MOBYGAMES_API_KEY= # https://www.mobygames.com/info/api/\n - STEAMGRIDDB_API_KEY= # https://github.com/rommapp/romm/wiki/Generate-API-Keys#steamgriddb\n volumes:\n - romm_resources:/romm/resources # Resources fetched from IGDB (covers, screenshots, etc.)\n - romm_redis_data:/redis-data # Cached data for background tasks\n - /path/to/library:/romm/library # Your game library. Check https://github.com/rommapp/romm?tab=readme-ov-file#folder-structure for more details.\n - /path/to/assets:/romm/assets # Uploaded saves, states, etc.\n - /path/to/config:/romm/config # Path where config.yml is stored\n ports:\n - 80:8080\n depends_on:\n romm-db:\n condition: service_healthy\n restart: true\n\n romm-db:\n image: mariadb:latest\n container_name: romm-db\n restart: unless-stopped\n environment:\n - MARIADB_ROOT_PASSWORD= # Use a unique, secure password\n - MARIADB_DATABASE=romm\n - MARIADB_USER=romm-user\n - MARIADB_PASSWORD=\n volumes:\n - mysql_data:/var/lib/mysql\n healthcheck:\n test: [\"CMD\", \"healthcheck.sh\", \"--connect\", \"--innodb_initialized\"]\n start_period: 30s\n start_interval: 10s\n interval: 10s\n timeout: 5s\n retries: 5\nOpen the terminal and navigate to the directory containing the docker-compose file
docker compose up -d to kick off the docker pull. You will see it pull the container and set up the volumes and network: RomM docker compose install docker ps -f name=romm to verify that the containers are runninghttp://localhost:8080, where you should be greeted with the RomM setup pageNow that the container is running, we will configure it by importing your ROMs
"},{"location":"Getting-Started/Quick-Start-Guide/#uploading-your-roms-via-web-interface","title":"Uploading Your ROMs via Web Interface","text":"This method is certainly viable, but not recommended if you have a lot of ROMs and/or multiple platforms. It is good for adding after the fact as your collection grows, but wouldn't be recommended for the first set up, nor for multi-file ROMs
roms/platforms you haveThis method is generally the fastest and recommended for first time setup
docker compose down if you are in the terminal and directory containing the docker-compose file, otherwise docker stop romm:/romm/library and create a folder named romsroms folder you createddocker compose up -d if you are in the terminal and directory containing the docker-compose file, otherwise docker start rommHere are some basic configurations for popular reverse proxies. Some installations may require modifications to configuration options not listed below.
"},{"location":"Getting-Started/Reverse-Proxy/#caddy","title":"Caddy","text":"http://romm.mysite.com {\n reverse_proxy romm:8080\n}\nhttps://romm.mysite.com {\n tls mysite.com.crt mysite.com.key # Certificate and key files\n\n encode zstd gzip\n\n header * {\n Strict-Transport-Security \"max-age=31536000;\"\n X-XSS-Protection \"1; mode=block\"\n X-Frame-Options \"SAMEORIGIN\"\n X-Robots-Tag \"noindex, nofollow\"\n -Server\n -X-Powered-By\n }\n\n reverse_proxy romm:8080\n}\nserver {\n listen 80 default_server;\n server_name romm.mysite.com;\n client_max_body_size 0;\n\n location / {\n include /config/nginx/proxy.conf;\n include /config/nginx/resolver.conf;\n set $upstream_app romm;\n set $upstream_port 8080;\n set $upstream_proto http;\n proxy_pass $upstream_proto://$upstream_app:$upstream_port;\n }\n}\nserver {\n listen 80 default_server;\n server_name _;\n return 301 https://$host$request_uri;\n}\n\nserver {\n listen 443 ssl http2;\n listen [::]:443 ssl http2;\n\n server_name romm.mysite.com;\n include /config/nginx/ssl.conf;\n client_max_body_size 0;\n\n location / {\n include /config/nginx/proxy.conf;\n include /config/nginx/resolver.conf;\n set $upstream_app romm;\n set $upstream_port 8080;\n set $upstream_proto http;\n proxy_pass $upstream_proto://$upstream_app:$upstream_port;\n\n # Hide version\n server_tokens off;\n\n # Security headers\n add_header X-Frame-Options \"SAMEORIGIN\" always;\n add_header X-Content-Type-Options \"nosniff\" always;\n add_header X-XSS-Protection \"1; mode=block\" always;\n add_header Strict-Transport-Security \"max-age=31536000; includeSubDomains\" always;\n add_header Referrer-Policy \"no-referrer-when-downgrade\" always;\n }\n}\nItems marked with \u2757 are important to set, as RomM may not correctly otherwise!
"},{"location":"Getting-Started/Reverse-Proxy/#details","title":"\u26a1 Details","text":"romm.example.com (replace example with your own)* Scheme: http8080offonon \u2757Strongly recommended, but only required if you plan to secure your site (use HTTPS)
ononoffonCustom Nginx Configuration \u2757
proxy_max_temp_file_size 0;\nhttp:\n romsdomainse:\n entryPoints:\n - \"https\"\n rule: \"Host(`roms.domain.se`)\"\n middlewares:\n - default-headers\n - https-redirectscheme\n tls:\n certResolver: http\n service: romsdomainse\n\nservices:\n romsdomainse:\n loadBalancer:\n servers:\n - url: \"http://192.168.1.100:8080\"\n passHostHeader: true\nlabels:\n - \"traefik.enable=true\"\n - \"traefik.http.services.romm.loadbalancer.server.port=8080\"\n - \"traefik.http.routers.romm.rule=Host(`romm.YOUR_DOMAIN.com`)\"\n - \"traefik.http.routers.romm.entrypoints=websecure\"\n - \"traefik.http.routers.romm.tls=true\"\n - \"traefik.http.routers.romm.tls.certresolver=https\"\nScheduled tasks can be enabled and configured with the following environment variables:
Variable Description Value ENABLE_SCHEDULED_RESCAN Enable scheduled re-scanning of librarytrue SCHEDULED_RESCAN_CRON Cron expression for scheduled re-scanning \"0 3 * * *\" ENABLE_SCHEDULED_UPDATE_SWITCH_TITLEDB Enable scheduled updating of Switch TitleDB index true SCHEDULED_UPDATE_SWITCH_TITLEDB_CRON Cron expression for scheduled updating of Switch TitleDB \"0 4 * * *\" ENABLE_SCHEDULED_UPDATE_MAME_XML Enable scheduled updating of MAME XML index true SCHEDULED_UPDATE_MAME_XML_CRON Cron expression for scheduled updating of MAME XML \"0 5 * * *\""},{"location":"Maintenance/Scheduled-Tasks/#scheduled-re-scan","title":"Scheduled re-scan","text":"Users can opt to enable scheduled re-scans, and set the interval using Cron notation. Not that the scan will not completely re-scan every file, only catching those which have been added/updated.
"},{"location":"Maintenance/Scheduled-Tasks/#switch-titledb-update","title":"Switch titleDB update","text":"Support was added for Nintendo Switch ROMs with filenames using the titleid/programid format (e.g. 0100000000010000.xci). If a file under the switch folder matches the regex, the scanner will use the index to attempt to match it to a game. If a match is found, the IGDB handler will use the matched name as the search term.
The associated task updates the /fixtures/switch_titledb.json file at a regular interval to support new game releases.
Support was also added for MAME arcade games with shortcode names (e.g. actionhw.zip -> ACTION HOLLYWOOD), and works in the same way as the TitleID matcher (without the regex).
The associated task updates the /fixtures/mame.xml file at a regular interval to support updates to the library.
RomM can also monitor the filesystem for events (files created/moved/deleted) and schedules a re-scan of the platform (or entire library is a new platform was added).
The watcher can be enabled and configured with the following environment variables:
Variable Description Value ENABLE_RESCAN_ON_FILESYSTEM_CHANGE Enable re-scanning of library when filesystem changestrue RESCAN_ON_FILESYSTEM_CHANGE_DELAY Delay in minutes before re-scanning library when filesystem changes 5 The watcher will monitor the /library/roms folder for changes to the filesystem, such as files being added, moved or deleted. It will ignore certain events (like modifying the file content or metadata), and will skip default OS files (like .DS_Store on mac).
When a change is detected, a scan will be scheduled for sometime in the future (default 5 minutes). If other events are triggered between now and the time at which the scan starts, more platforms will be added to the scan list (or the scan may switch to a full scan). This is done to reduce the number of tasks scheduled when many big changes happen to the library (mass upload, new mount, etc.)
"},{"location":"Maintenance/Upgrading-to-3.0/","title":"Upgrading to 3.0","text":"Version 3.0 of RomM introduces a number of breaking changes aimed at improving performance and usability, which will require some users to make specific changes before upgrading to ensure compatibility and to take full advantage of the new features.
All of the following changes are reflected in the example docker-compose.yml file, which has been simplified greatly. Please read this entire file carefully, as failing to do so may cause RomM to become inaccessible or unresponsive.
"},{"location":"Maintenance/Upgrading-to-3.0/#dropped-support-for-sqlite","title":"Dropped support for SQLite","text":"We're removed support for SQLite as we've faced a number of engineering issues with it in the past, and MariaDB has proven more stable and robust. If you currently use SQLite, we'll automatically migrate your data from SQLite to MariaDB, but you'll first need to make the following changes before upgrading to the latest image.
In your environment variables, change ROMM_DB_DRIVER to mariadb (or remove it completely as it's no longer needed). You'll then want to add the following environment variables:
- DB_HOST=mariadb\n- DB_PORT=3306\n- DB_NAME=romm # Should match MYSQL_DATABASE in mariadb\n- DB_USER=romm-user # Should match MYSQL_USER in mariadb\n- DB_PASSWD= # Should match MYSQL_PASSWORD in mariadb\nTo setup a new MariaDB container, have a look at the example docker-compose.yml file.
"},{"location":"Maintenance/Upgrading-to-3.0/#authentication-as-standard","title":"Authentication as standard","text":"To support new features like EmulatorJS and saves/states management, we've decided to require authentication for all users. Anyone currently running RomM with authentication disabled will need to remove the ROMM_AUTH_ENABLED environment variable and add the following ones:
- ROMM_AUTH_SECRET_KEY= # Generate a key with `openssl rand -hex 32`\nWe understand that this requirement for authentication might conflict with the way some users currently share their collection with others (unrestricted access for all). However, given the exciting new features we've built, and the ones we're looking to build in the near future, we feel this is the right decision for the project.
"},{"location":"Maintenance/Upgrading-to-3.0/#redis-is-now-built-in","title":"Redis is now built-in","text":"As Redis is required for authentication to work, we've integrated it directly into the docker image. If you're currently running the experimental Redis container, you can remove it, along with these environment variables:
- ENABLE_EXPERIMENTAL_REDIS\n- REDIS_HOST\n- REDIS_PORT\nMounting the config.yml file is now done by mounting a config folder.. Place your existing config.yml file inside a folder and bind it to /romm/config:
- /path/to/config:/romm/config\nUpdated config.example.yml
"},{"location":"Maintenance/Upgrading-to-3.0/#support-for-saves-states-and-screenshots","title":"Support for saves, states and screenshots","text":"This version introduces preliminary support for uploading/downloading saves, states and screenshots (read more about it in the 3.0 release notes). We've added a new volume mapping for these types of files called assets, which you'll want to bind to a local folder (or volume) so they'll persist. In your volumes section, add the following mapping, where /path/to/assets/ is some folder where you'll want to store these assets (and make sure that folder exists):
- /path/to/assets:/romm/assets\nWe recommend creating a folder next to your library/the one mapped to /romm/library in order to keep all your RomM files in the same place.
PSP emulation with the PPSSPP core requires special setup with a reverse proxy, or launching Chrome browser with the --disable-web-security and --enable-features=SharedArrayBuffer flags, which WE STRONGLY DISCOURAGE as it disables important security features.
When it's ready.
"},{"location":"Miscellaneous/FAQs/#when-will-the-version-after-that-one-release","title":"When will the version after that one release?","text":"After the upcoming version is released.
"},{"location":"Miscellaneous/FAQs/#when-will-x-feature-be-available","title":"When will X feature be available?","text":"Sometime between now and the heat death of the universe.
"},{"location":"Miscellaneous/FAQs/#when-will-version-xxx-of-romm-or-any-of-the-romm-clientsappsplugins-be-released","title":"When will versionx.x.x of RomM (or any of the RomM clients/apps/plugins) be released?","text":"Same as above question.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/","title":"OIDC Setup With Authelia","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#oidc-setup-with-authelia","title":"OIDC Setup With Authelia","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#a-quick-rundown-of-the-technologies","title":"A quick rundown of the technologies","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#what-is-authelia","title":"What is Authelia?","text":"Authelia is an open-source authentication and authorization server providing two-factor authentication and single sign-on (SSO) for your applications via a web portal. It acts as a companion for reverse proxies by allowing, denying, or redirecting requests. Authelia can be deployed alongside your other services to centralize identity management.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#what-is-oauth2","title":"What is OAuth2?","text":"OAuth2 (Open Authorization 2.0) is an industry-standard protocol for authorization. It allows applications (clients) to gain limited access to user accounts on an HTTP service without sharing the user\u2019s credentials. Instead, it uses access tokens to facilitate secure interactions. OAuth2 is commonly used in scenarios where users need to authenticate via a third-party service.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#what-is-openid-connect-oidc","title":"What is OpenID Connect (OIDC)?","text":"OIDC (OpenID Connect) is an identity layer built on top of OAuth2. While OAuth2 primarily handles authorization, OIDC adds authentication, enabling applications to verify a user\u2019s identity and obtain profile information. This makes OIDC suitable for SSO solutions, where user identity is central to access management.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#setting-up-a-provider-and-application-in-authelia","title":"Setting up a Provider and Application in Authelia","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#step-1-install-and-configure-authelia","title":"Step 1: Install and Configure Authelia","text":"Before setting up a provider and app, ensure that Authelia is installed and running by following the getting started and OIDC provider guides.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#step-2-add-a-client","title":"Step 2: Add a client","text":"In Authelia's configuration.yml, under identity_providers \u2192 oidc \u2192 clients, add a new entry:
client_id and client_secretpublic should be set to false.redirect_uris should include your RomM instance's URL + /api/oauth/openid (e.g., http://romm.host.local/api/oauth/openid).scopes includes openid, email and profile.token_endpoint_auth_method should be set to client_secret_basic.userinfo_signed_response_alg should be set to none.Refer to the official docs for more details.
This entry should look like this:
#identity_providers:\n# oidc:\n# clients:\n- client_id: \"<randomly_generated>\" # read above for how generate\n client_name: \"RomM\" # will be displayed in Authelia to users\n client_secret: \"$pbkdf2-sha512$randomly_generated\" # read above for how generate\n public: false\n authorization_policy: \"two_factor\" # or one_factor, depending on your needs\n grant_types:\n - authorization_code\n redirect_uris:\n - \"http://romm.host.local/api/oauth/openid\"\n scopes:\n - \"openid\"\n - \"email\"\n - \"profile\"\n userinfo_signed_response_alg: \"none\"\n token_endpoint_auth_method: \"client_secret_basic\"\nTo enable OIDC authentication in RomM, you need to set the following environment variables:
OIDC_ENABLED: Set to true to enable OIDC authentication.OIDC_PROVIDER: The lowercase name of the provider (authelia).OIDC_CLIENT_ID: The client ID copied from the Authelia application.OIDC_CLIENT_SECRET: The generated output from Random Password.OIDC_REDIRECT_URI: The redirect URI configured in the Authelia provider, in the format http://romm.host.local/api/oauth/openid.OIDC_SERVER_APPLICATION_URL: The base URL for you Authelia instance, e.g. http://authelia.host.local.In RomM, open your user profile and set your email address. This email has to match your user email in Authelia.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#step-5-test-the-integration","title":"Step 5: Test the Integration","text":"After configuring the environment variables, restart (or stop and remove) your RomM instance and navigate to the login page. You should see an option to log in using OIDC. Click on the OIDC button, and you'll be redirected to Authelia for authentication. Once authenticated, you'll be redirected back to RomM.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/","title":"OIDC Setup With Authentik","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#oidc-setup-with-authentik","title":"OIDC Setup With Authentik","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#a-quick-rundown-of-the-technologies","title":"A quick rundown of the technologies","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#what-is-authentik","title":"What is Authentik?","text":"Authentik is an open-source identity provider (IdP) designed to manage authentication, authorization, and user management across applications. It supports modern authentication protocols and provides tools to simplify integration, including single sign-on (SSO), multi-factor authentication (MFA), and auditing capabilities. Authentik can be deployed alongside your other services to centralize identity management.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#what-is-oauth2","title":"What is OAuth2?","text":"OAuth2 (Open Authorization 2.0) is an industry-standard protocol for authorization. It allows applications (clients) to gain limited access to user accounts on an HTTP service without sharing the user\u2019s credentials. Instead, it uses access tokens to facilitate secure interactions. OAuth2 is commonly used in scenarios where users need to authenticate via a third-party service.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#what-is-openid-connect-oidc","title":"What is OpenID Connect (OIDC)?","text":"OIDC (OpenID Connect) is an identity layer built on top of OAuth2. While OAuth2 primarily handles authorization, OIDC adds authentication, enabling applications to verify a user\u2019s identity and obtain profile information. This makes OIDC suitable for SSO solutions, where user identity is central to access management.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#setting-up-a-provider-and-application-in-authentik","title":"Setting up a Provider and Application in Authentik","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#step-1-install-and-configure-authentik","title":"Step 1: Install and Configure Authentik","text":"Before setting up a provider and app, ensure that Authentik is installed and running by following the official installation guide..
A provider in Authentik acts as the bridge between RomM and Authentik.
/api/oauth/openid (e.g., http://romm.host.local/api/oauth/openid).OIDC_CLIENT_ID and OIDC_CLIENT_SECRET in your RomM instance. An app in Authentik represents the external service (in our case RomM) that will use the provider for authentication.
romm). - Provider: Link the app to the previously created provider, \"RomM OIDC Provider\". To enable OIDC authentication in RomM, you need to set the following environment variables:
OIDC_ENABLED: Set to true to enable OIDC authentication.OIDC_PROVIDER: The lowercase name of the provider (authentik).OIDC_CLIENT_ID: The client ID copied from the Authentik application.OIDC_CLIENT_SECRET: The client secret copied from the Authentik application.OIDC_REDIRECT_URI: The redirect URI configured in the Authentik provider, in the format http://romm.host.local/api/oauth/openid.OIDC_SERVER_APPLICATION_URL: The URL of the Authentik application, e.g., http://authentik.host.local/application/o/romm.In RomM, open your user profile and set your email address. This email has to match your user email in Authentik.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#step-6-test-the-integration","title":"Step 6: Test the Integration","text":"After configuring the environment variables, restart (or stop and remove) your RomM instance and navigate to the login page. You should see an option to log in using OIDC. Click on the OIDC button, and you'll be redirected to Authentik for authentication. Once authenticated, you'll be redirected back to RomM.
"},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/","title":"OIDC Setup With PocketID","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#oidc-setup-with-pocket-id","title":"OIDC Setup With Pocket ID","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#a-quick-rundown-of-the-technologies","title":"A quick rundown of the technologies","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#what-is-pocket-id","title":"What is Pocket ID?","text":"Pocket ID is a simple OIDC provider that allows users to authenticate with their passkeys to your services.
The goal of Pocket ID is to be a simple and easy-to-use. There are other self-hosted OIDC providers like Keycloak or ORY Hydra but they are often too complex for simple use cases.
Additionally, what makes Pocket ID special is that it only supports passkey authentication, which means you don\u2019t need a password.
"},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#what-is-oauth2","title":"What is OAuth2?","text":"OAuth2 (Open Authorization 2.0) is an industry-standard protocol for authorization. It allows applications (clients) to gain limited access to user accounts on an HTTP service without sharing the user\u2019s credentials. Instead, it uses access tokens to facilitate secure interactions. OAuth2 is commonly used in scenarios where users need to authenticate via a third-party service.
"},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#what-is-openid-connect-oidc","title":"What is OpenID Connect (OIDC)?","text":"OIDC (OpenID Connect) is an identity layer built on top of OAuth2. While OAuth2 primarily handles authorization, OIDC adds authentication, enabling applications to verify a user\u2019s identity and obtain profile information. This makes OIDC suitable for SSO solutions, where user identity is central to access management.
"},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#setting-up-a-client-in-pocket-id","title":"Setting up a client in Pocket ID","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#step-1-install-and-configure-pocket-id","title":"Step 1: Install and Configure Pocket ID","text":"Before setting up the OIDC client, ensure that Pocket ID is installed and running by following the setup guide.
"},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#step-2-add-a-client","title":"Step 2: Add a client","text":"Once you have logged in and configured a PassKey you now need to create an OIDC client, this will let Pocket ID know about the application that needs to be configured, and will give you the relevant keys to add to the RomM compose file.
https://{host}/api/oauth/openidTo enable OIDC authentication in RomM, you need to set the following environment variables:
OIDC_ENABLED: Set to true to enable OIDC authentication.OIDC_PROVIDER: The lowercase name of the provider (pocketid).OIDC_CLIENT_ID: The client ID copied from the Pocket ID applicationOIDC_CLIENT_SECRET: The client secret that is showing within your Pocket ID application.OIDC_REDIRECT_URI: The redirect URI configured in the Pocket ID provider, in the format https://{host}/api/oauth/openid.OIDC_SERVER_APPLICATION_URL: The authorization URL for you Pocket ID instance, e.g. https://id.host.local/authorize.In RomM, open your user profile and set your email address. This email has to match your user email in Pocket ID.
"},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#step-5-test-the-integration","title":"Step 5: Test the Integration","text":"After configuring the environment variables, restart (or stop and remove) your RomM instance and navigate to the login page. You should see an option to log in using OIDC. Click on the OIDC button, and you'll be redirected to Pocket ID for authentication. Once authenticated, you'll be redirected back to RomM.
"},{"location":"Platforms-and-Players/Custom-Platforms/","title":"Custom Platforms","text":"While RomM supports every platform listed in the Supported Platforms page, the list is not exhaustive, and you may have ROMs in your library for other platforms. To load those files into RomM, place them in a folder for each platform, and give it a name that's all lowercase, with - to separate words, and with no white spaces. For example, pocket-challenge-v2 would map to Pocket Challenge V2, and display the default platform icon in the app.
Furthermore, only a portion of the supported platforms have custom icons built-in. If your library has platforms that aren't listed in the platforms icons list, RomM will display a default fallback icon.
If you'd like to load your own custom icons for missing platforms, you can mount /var/www/html/assets/platforms to some local folder and place all of your custom .ico platform icons in there. You'll also want to download the ones provided in this project and place them in the same folder. If you'd like to use your own icons for platforms already supported by RomM, just replace the file with another using the exact same name.
The name of the .ico file should match the slug of the platform on IGDB. For example, the URL for the AmstradCPC is https://www.igdb.com/platforms/acpc, so the filename should be acpc.ico.
EmulatorJS is a web-based emulator for various system; that is, it allows you to run old games in your web browser. It's based on Emscripten, which is a toolchain for compiling C and C++ code to WebAssembly.
Warning
Due to a change by Apple in iOS 18.2, emulation is severely limited, and likely non-functional, on iOS devices.
Warning
PSP emulation with the PPSSPP core requires special setup with a reverse proxy, or launching Chrome browser with the --disable-web-security and --enable-features=SharedArrayBuffer flags, which WE STRONGLY DISCOURAGE as it disables important security features.
Warning
Emulation is a complex and resource-intensive process. As such, it may not work well in all browser, especially older or less powerful ones. If you're having trouble running a game, try using a different browser or device.
"},{"location":"Platforms-and-Players/EmulatorJS-Player/#loading-saves-and-states","title":"Loading saves and states","text":"Our integration with EmulatorJS automates the process of loading and saving save files and save states. Before starting the game, select a save and/or state file to load (if one is available). Anytime you save the game (or create a save state), the save and state files stored with RomM will be updated, so there's no need to manually download or upload them.
"},{"location":"Platforms-and-Players/EmulatorJS-Player/#supported-systems","title":"Supported systems","text":"Note that only the following systems are currently supported:
Ruffle is a web-based player for flash games. With flash now discontinued, this is the best way to play your flash collection in the browser.
Important
Ruffle will only play games stored in platform folders called flash or browser.
Below is a list of all supported platforms/systems/consoles and their respective folder names. The folder name is case-sensitive and must be used exactly as it appears in the list below.
Platform Name Folder Name IGDB MobyGames 1292 Advanced Programmable Video System1292-advanced-programmable-video-system IGDB MobyGames 3DO Interactive Multiplayer 3do IGDB MobyGames ABC 80 abc-80 MobyGames APF MP1000/Imagination Machine apf MobyGames AY-3-8500 ay-3-8500 IGDB AY-3-8603 ay-3-8603 IGDB AY-3-8605 ay-3-8605 IGDB AY-3-8606 ay-3-8606 IGDB AY-3-8607 ay-3-8607 IGDB AY-3-8610 ay-3-8610 IGDB AY-3-8710 ay-3-8710 IGDB AY-3-8760 ay-3-8760 IGDB Acorn Archimedes acorn-archimedes IGDB MobyGames Acorn Electron acorn-electron IGDB MobyGames Adventure Vision adventure-vision MobyGames AirConsole airconsole IGDB MobyGames Alice 32/90 alice-3290 MobyGames Altair 680 altair-680 MobyGames Altair 8800 altair-8800 MobyGames Amazon Alexa amazon-alexa MobyGames Amazon Fire TV amazon-fire-tv IGDB MobyGames Amiga amiga IGDB MobyGames Amiga CD32 amiga-cd32 IGDB MobyGames Amstrad CPC acpc IGDB MobyGames Amstrad PCW amstrad-pcw IGDB MobyGames Android android IGDB MobyGames Antstream antstream MobyGames Apple I apple-i MobyGames Apple II appleii IGDB MobyGames Apple IIGD apple2gs MobyGames Apple IIGS apple-iigs IGDB MobyGames Apple Pippin apple-pippin IGDB Arcade arcade IGDB MobyGames Arcadia 2001 arcadia-2001 IGDB MobyGames Arduboy arduboy IGDB MobyGames Astral 2000 astral-2000 MobyGames Atari 2600 atari2600 IGDB MobyGames Atari 5200 atari5200 IGDB MobyGames Atari 7800 atari7800 IGDB MobyGames Atari 8-bit atari8bit IGDB MobyGames Atari Jaguar jaguar IGDB MobyGames Atari Jaguar CD atari-jaguar-cd IGDB Atari Lynx lynx IGDB MobyGames Atari ST/STE atari-st IGDB MobyGames Atari VCS atari-vcs MobyGames Atom atom MobyGames BBC Micro bbcmicro MobyGames BBC Microcomputer System bbcmicro IGDB MobyGames BREW brew MobyGames Bally Astrocade astrocade IGDB MobyGames BeOS beos MobyGames BlackBerry OS blackberry IGDB MobyGames Blacknut blacknut MobyGames Blu-ray Player blu-ray-player IGDB MobyGames Bubble bubble MobyGames CD-i philips-cd-i MobyGames CDC Cyber 70 cdccyber70 IGDB CDTV commodore-cdtv MobyGames COSMAC fred-cosmac MobyGames CP/M cpm MobyGames Call-A-Computer time-shared mainframe computer system call-a-computer IGDB Camputers Lynx camputers-lynx MobyGames Casio Loopy casio-loopy IGDB MobyGames Casio PV-1000 casio-pv-1000 MobyGames Casio Programmable Calculator casio-programmable-calculator MobyGames Champion 2711 champion-2711 MobyGames Channel F fairchild-channel-f MobyGames ClickStart clickstart MobyGames Coleco Adam colecoadam MobyGames ColecoVision colecovision IGDB MobyGames Colour Genie colour-genie MobyGames Commodore 128 c128 MobyGames Commodore 16 c16 IGDB MobyGames Commodore C64/128/MAX c64 IGDB MobyGames Commodore CDTV commodore-cdtv IGDB MobyGames Commodore PET cpet IGDB MobyGames Commodore PET/CBM cpet MobyGames Commodore Plus/4 c-plus-4 IGDB MobyGames Commodore VIC-20 vic-20 IGDB MobyGames Compal 80 compal-80 MobyGames Compucolor I compucolor-i MobyGames Compucolor II compucolor-ii MobyGames Compucorp Programmable Calculator compucorp-programmable-calculator MobyGames CreatiVision creativision MobyGames Cybervision cybervision MobyGames DOS dos IGDB MobyGames DVD Player dvd-player IGDB MobyGames Danger OS danger-os MobyGames Dedicated console dedicated-console MobyGames Dedicated handheld dedicated-handheld MobyGames Didj didj MobyGames DoJa doja MobyGames Donner Model 30 donner30 IGDB Dragon 32/64 dragon-32-slash-64 IGDB MobyGames Dreamcast dc IGDB MobyGames ECD Micromind ecd-micromind MobyGames EDSAC edsac--1 IGDB Electron acorn-electron MobyGames Enterprise enterprise MobyGames Epoch Cassette Vision epoch-cassette-vision IGDB MobyGames Epoch Game Pocket Computer epoch-game-pocket-computer MobyGames Epoch Super Cassette Vision epoch-super-cassette-vision IGDB MobyGames Evercade evercade IGDB MobyGames ExEn exen MobyGames Exelvision exelvision MobyGames Exidy Sorcerer exidy-sorcerer IGDB MobyGames FM Towns fm-towns IGDB MobyGames FM-7 fm-7 IGDB MobyGames Fairchild Channel F fairchild-channel-f IGDB MobyGames Family Computer famicom IGDB Family Computer Disk System fds IGDB Feature phone mobile-custom MobyGames Ferranti Nimrod Computer nimrod IGDB Fire TV amazon-fire-tv MobyGames Freebox freebox MobyGames G-cluster g-cluster MobyGames GIMINI gimini MobyGames GNEX gnex MobyGames GP2X gp2x MobyGames GP2X Wiz gp2x-wiz MobyGames GP32 gp32 MobyGames GVM gvm MobyGames Galaksija galaksija MobyGames Gamate gamate IGDB Game & Watch g-and-w IGDB Game Boy gb IGDB MobyGames Game Boy Advance gba IGDB MobyGames Game Boy Color gbc IGDB MobyGames Game Gear gamegear MobyGames Game Wave game-wave MobyGames Game.Com game-dot-com MobyGames Game.com game-dot-com IGDB MobyGames GameStick gamestick MobyGames Gear VR gear-vr IGDB Genesis/Mega Drive genesis-slash-megadrive MobyGames Gizmondo gizmondo IGDB MobyGames Gloud gloud MobyGames Glulx glulx MobyGames Google Stadia stadia IGDB MobyGames HD DVD Player hd-dvd-player MobyGames HP 2100 hp2100 IGDB HP 3000 hp3000 IGDB HP 9800 hp-9800 MobyGames HP Programmable Calculator hp-programmable-calculator MobyGames Handheld Electronic LCD handheld-electronic-lcd IGDB Heath/Zenith H8/H89 heathzenith MobyGames Heathkit H11 heathkit-h11 MobyGames Hitachi S1 hitachi-s1 MobyGames Hugo hugo MobyGames Hyper Neo Geo 64 hyper-neo-geo-64 IGDB HyperScan hyperscan IGDB MobyGames IBM 5100 ibm-5100 MobyGames Ideal-Computer ideal-computer MobyGames Intel 8008 intel-8008 MobyGames Intel 8080 intel-8080 MobyGames Intel 8086 / 8088 intel-8086 MobyGames Intellivision intellivision IGDB MobyGames Intellivision Amico intellivision-amico IGDB Interact Model One interact-model-one MobyGames Interton Video 2000 interton-video-2000 MobyGames Interton VC 4000 vc-4000 IGDB J2ME j2me MobyGames Jolt jolt MobyGames Jupiter Ace jupiter-ace MobyGames KIM-1 kim-1 MobyGames KaiOS kaios MobyGames Kindle Classic kindle MobyGames Laser 200 laser200 MobyGames LaserActive laseractive MobyGames LeapTV leaptv IGDB MobyGames Leapster leapster IGDB MobyGames Leapster Explorer/LeadPad Explorer leapster-explorer-slash-leadpad-explorer IGDB MobyGames Leapster Explorer/LeapPad Explorer leapster-explorer-slash-leadpad-explorer MobyGames Legacy Computer legacy-computer IGDB Legacy Mobile Device mobile IGDB Linux linux IGDB MobyGames Luna luna MobyGames MOS Technology 6502 mos-technology-6502 MobyGames MRE mre MobyGames MSX msx IGDB MobyGames MSX2 msx2 IGDB Mac mac IGDB MobyGames Macintosh mac MobyGames Maemo maemo MobyGames Mainframe mainframe MobyGames Matsushita/Panasonic JR matsushitapanasonic-jr MobyGames Mattel Aquarius mattel-aquarius MobyGames MeeGo meego MobyGames Mega Duck/Cougar Boy mega-duck-slash-cougar-boy IGDB Memotech MTX memotech-mtx MobyGames Meritum meritum MobyGames Meta Quest 2 meta-quest-2 IGDB Meta Quest 3 meta-quest-3 IGDB Microbee microbee MobyGames Microtan 65 microtan-65 MobyGames Microvision microvision--1 IGDB MobyGames Mophun mophun MobyGames Motorola 6800 motorola-6800 MobyGames Motorola 68k motorola-68k MobyGames N-Gage ngage IGDB MobyGames N-Gage (service) ngage2 MobyGames NEC PC-6000 Series nec-pc-6000-series IGDB Nascom nascom MobyGames Neo Geo neogeoaes MobyGames Neo Geo AES neogeoaes IGDB MobyGames Neo Geo CD neo-geo-cd IGDB MobyGames Neo Geo MVS neogeomvs IGDB MobyGames Neo Geo Pocket neo-geo-pocket IGDB MobyGames Neo Geo Pocket Color neo-geo-pocket-color IGDB MobyGames Neo Geo X neo-geo-x MobyGames New Nintendo 3DS new-nintendo-3ds IGDB MobyGames NewBrain newbrain MobyGames Newton newton MobyGames Nintendo 3DS 3ds IGDB MobyGames Nintendo 64 n64 IGDB MobyGames Nintendo 64DD nintendo-64dd IGDB Nintendo DS nds IGDB MobyGames Nintendo DSi nintendo-dsi IGDB MobyGames Nintendo Entertainment System nes IGDB MobyGames Nintendo GameCube ngc IGDB MobyGames Nintendo PlayStation nintendo-playstation IGDB Nintendo Switch switch IGDB MobyGames North Star northstar MobyGames Noval 760 noval-760 MobyGames Nuon nuon IGDB MobyGames OOParts ooparts IGDB MobyGames OS/2 os2 MobyGames Oculus Go oculus-go IGDB MobyGames Oculus Quest oculus-quest IGDB MobyGames Oculus Rift oculus-rift IGDB Odyssey odyssey--1 IGDB MobyGames Odyssey 2/Videopac G7000 odyssey-2-slash-videopac-g7000 IGDB MobyGames Ohio Scientific ohio-scientific MobyGames OnLive Game System onlive-game-system IGDB MobyGames Orao orao MobyGames Oric oric MobyGames Ouya ouya IGDB MobyGames PC (Microsoft Windows) win IGDB MobyGames PC Booter pc-booter MobyGames PC Engine SuperGrafx supergrafx IGDB MobyGames PC-50X Family pc-50x-family IGDB PC-6001 pc-6001 MobyGames PC-8000 pc-8000 MobyGames PC-8800 Series pc-8800-series IGDB MobyGames PC-9800 Series pc-9800-series IGDB MobyGames PC-FX pc-fx IGDB MobyGames PDP-1 pdp1 IGDB PDP-10 pdp10 IGDB PDP-11 pdp11 IGDB PDP-8 pdp-8--1 IGDB PICO pico MobyGames PLATO plato--1 IGDB PS Vita psvita MobyGames Palm OS palm-os IGDB MobyGames Panasonic Jungle panasonic-jungle IGDB Panasonic M2 panasonic-m2 IGDB Pandora pandora MobyGames Pebble pebble MobyGames Philips CD-i philips-cd-i IGDB MobyGames Philips VG 5000 philips-vg-5000 MobyGames Photo CD photocd MobyGames Pippin pippin MobyGames PlayStation ps IGDB MobyGames PlayStation 2 ps2 IGDB MobyGames PlayStation 3 ps3 IGDB MobyGames PlayStation 4 ps4--1 IGDB MobyGames PlayStation 5 ps5 IGDB MobyGames PlayStation Now playstation-now MobyGames PlayStation Portable psp IGDB MobyGames PlayStation VR psvr IGDB PlayStation VR2 psvr2 IGDB PlayStation Vita psvita IGDB MobyGames Playdate playdate IGDB MobyGames Playdia playdia IGDB MobyGames Plex Arcade plex-arcade MobyGames Plug & Play plug-and-play IGDB PocketStation pocketstation IGDB Pokitto pokitto MobyGames Pok\u00e9mon mini pokemon-mini IGDB MobyGames Poly-88 poly-88 MobyGames R-Zone r-zone IGDB RCA Studio II rca-studio-ii MobyGames Research Machines 380Z research-machines-380z MobyGames Roku roku MobyGames SAM Coup\u00e9 sam-coupe MobyGames SC/MP scmp MobyGames SD-200/270/290 sd-200270290 MobyGames SDS Sigma 7 sdssigma7 IGDB SEGA 32X sega-32x MobyGames SEGA CD segacd MobyGames SEGA Master System sega-master-system MobyGames SEGA Saturn saturn MobyGames SG-1000 sg1000 IGDB SK-VM sk-vm MobyGames SMC-777 smc-777 MobyGames SRI-500/1000 sri-5001000 MobyGames SWTPC 6800 swtpc-6800 MobyGames Satellaview satellaview IGDB Sega 32X sega32 IGDB MobyGames Sega CD segacd IGDB MobyGames Sega Game Gear gamegear IGDB MobyGames Sega Master System/Mark III sms IGDB Sega Mega Drive/Genesis genesis-slash-megadrive IGDB MobyGames Sega Pico sega-pico IGDB MobyGames Sega Saturn saturn IGDB MobyGames Sharp MZ-2200 sharp-mz-2200 IGDB Sharp MZ-80B/2000/2500 sharp-mz-80b20002500 MobyGames Sharp MZ-80K/700/800/1500 sharp-mz-80k7008001500 MobyGames Sharp X1 x1 IGDB MobyGames Sharp X68000 sharp-x68000 IGDB MobyGames Sharp Zaurus sharp-zaurus MobyGames Signetics 2650 signetics-2650 MobyGames Sinclair QL sinclair-ql IGDB MobyGames Sinclair ZX81 sinclair-zx81 IGDB MobyGames Socrates socrates MobyGames Sol-20 sol-20 IGDB MobyGames Sord M5 sord-m5 MobyGames Spectravideo spectravideo MobyGames Super A'can super-acan MobyGames Super Famicom sfam IGDB Super Nintendo Entertainment System snes IGDB MobyGames Super Vision 8000 super-vision-8000 MobyGames Supervision supervision MobyGames Sure Shot HD sure-shot-hd MobyGames SwanCrystal swancrystal IGDB Symbian symbian MobyGames TADS tads MobyGames TI Programmable Calculator ti-programmable-calculator MobyGames TI-99/4A ti-994a MobyGames TIM tim MobyGames TRS-80 trs-80 IGDB MobyGames TRS-80 Color Computer trs-80-color-computer IGDB MobyGames TRS-80 MC-10 trs-80-mc-10 MobyGames TRS-80 Model 100 trs-80-model-100 MobyGames Taito X-55 taito-x-55 MobyGames Tapwave Zodiac zod IGDB Tatung Einstein tatung-einstein IGDB MobyGames Tektronix 4050 tektronix-4050 MobyGames Tele-Spiel ES-2201 tele-spiel MobyGames Telstar Arcade telstar-arcade MobyGames Terebikko / See 'n Say Video Phone terebikko-slash-see-n-say-video-phone IGDB Terminal terminal MobyGames Texas Instruments TI-99 ti-99 IGDB MobyGames Thomson MO5 thomson-mo5 IGDB MobyGames Thomson TO thomson-to MobyGames Tiki 100 tiki-100 MobyGames Timex Sinclair 2068 timex-sinclair-2068 MobyGames Tizen tizen MobyGames Tomahawk F1 tomahawk-f1 MobyGames Tomy Tutor tomy-tutor MobyGames Triton triton MobyGames TurboGrafx CD turbografx-16-slash-pc-engine-cd MobyGames TurboGrafx-16 turbografx16--1 MobyGames TurboGrafx-16/PC Engine turbografx16--1 IGDB MobyGames Turbografx-16/PC Engine CD turbografx-16-slash-pc-engine-cd IGDB MobyGames V.Flash vflash MobyGames V.Smile vsmile IGDB MobyGames VIS vis MobyGames Vectrex vectrex IGDB MobyGames Versatile versatile MobyGames VideoBrain videobrain MobyGames Videopac+ G7400 videopac-g7400 MobyGames Virtual Boy virtualboy IGDB MobyGames Virtual Console vc IGDB Visual Memory Unit / Visual Memory System visual-memory-unit-slash-visual-memory-system IGDB WIPI wipi MobyGames Wang 2200 wang2200 MobyGames Watara/QuickShot Supervision watara-slash-quickshot-supervision IGDB Web browser browser IGDB MobyGames Wii wii IGDB MobyGames Wii U wiiu IGDB MobyGames Windows win MobyGames Windows 3.x win3x MobyGames Windows Apps windows-apps MobyGames Windows Mobile windows-mobile IGDB MobyGames Windows Phone winphone IGDB MobyGames WonderSwan wonderswan IGDB MobyGames WonderSwan Color wonderswan-color IGDB MobyGames XaviXPORT xavixport MobyGames Xbox xbox IGDB MobyGames Xbox 360 xbox360 IGDB MobyGames Xbox Cloud Gaming xboxcloudgaming MobyGames Xbox One xboxone IGDB MobyGames Xbox Series X series-x IGDB MobyGames Xerox Alto xerox-alto MobyGames Z-machine z-machine MobyGames ZX Spectrum zxs IGDB ZX Spectrum Next zx-spectrum-next MobyGames ZX80 zx80 MobyGames ZX81 sinclair-zx81 MobyGames Zeebo zeebo IGDB MobyGames Zilog Z80 z80 MobyGames Zilog Z8000 zilog-z8000 MobyGames Zodiac zodiac MobyGames Zune zune MobyGames bada bada MobyGames digiBlast digiblast MobyGames iOS ios IGDB MobyGames iPad ipad MobyGames iPod Classic ipod-classic MobyGames iiRcade iircade MobyGames tvOS tvos MobyGames visionOS visionos IGDB watchOS watchos MobyGames webOS webos MobyGames"},{"location":"System-Setup/Synology-Setup-Guide/","title":"Synology Setup","text":""},{"location":"System-Setup/Synology-Setup-Guide/#prerequisites","title":"Prerequisites","text":"This guide assumes you're familiar with Docker and have basic knowledge of server management. You'll need:
Create the following directory structure for game assets and configuration:
mkdir -p /volume1/data/media/games/assets\nmkdir -p /volume1/data/media/games/config\nRomM requires a very specific folder structure for rom files:
mkdir -p /volume1/data/media/games/library/roms\nmkdir -p /volume1/data/media/games/library/bios\nNote: For supported platforms and their specific folder names, refer to the official RomM wiki.
"},{"location":"System-Setup/Synology-Setup-Guide/#docker-data-folders","title":"Docker Data Folders","text":"Create these folders for project and container data:
mkdir -p /volume1/docker/romm-project/\nmkdir -p /volume1/docker/romm/resources\nmkdir -p /volume1/docker/romm/redis-data\nmkdir -p /volume1/docker/mariadb-romm\nCreate a new network bridge named rommbridge following standard Docker networking practices. You can use this guide for reference.
Generate your authentication key using:
openssl rand -hex 32\n> 03a054b6ca27e0107c5eed552ea66bacd9f3a2a8a91e7595cd462a593f9ecd09\nSave the output - you'll need it for the ROMM_AUTH_SECRET_KEY in your configuration.
RomM currently supports 3 metadata sources: IGDB, MobyGames and SteamGridDB. Follow the dedicated wiki page for API key generation to set up your API keys. We recommend setting up IGDG at the minimum.
"},{"location":"System-Setup/Synology-Setup-Guide/#4-mariadb-configuration","title":"4. MariaDB Configuration","text":"Important
Create a docker-compose.yml file with the following content:
version: \"3\"\n\nvolumes:\n mysql_data:\n\nservices:\n romm:\n image: rommapp/romm:latest\n container_name: romm\n restart: unless-stopped\n environment:\n - DB_HOST=romm-db\n - DB_NAME=romm # Should match MARIADB_DATABASE in mariadb\n - DB_USER=romm-user # Should match MARIADB_USER in mariadb\n - DB_PASSWD= # Should match MARIADB_PASSWORD in mariadb\n - ROMM_AUTH_SECRET_KEY= # Generate a key with `openssl rand -hex 32`\n - IGDB_CLIENT_ID= # Generate an ID and SECRET in IGDB\n - IGDB_CLIENT_SECRET= # https://api-docs.igdb.com/#account-creation\n - MOBYGAMES_API_KEY= # https://www.mobygames.com/info/api/\n - STEAMGRIDDB_API_KEY= # https://github.com/rommapp/romm/wiki/Generate-API-Keys#steamgriddb\n volumes:\n - /volume1/docker/romm/resources:/romm/resources\n - /volume1/docker/romm/redis-data:/redis-data\n - /volume1/data/media/games/library:/romm/library\n - /volume1/data/media/games/assets:/romm/assets\n - /volume1/data/media/games/config:/romm/config\n ports:\n - 7676:8080\n network_mode: rommbridge\n depends_on:\n romm-db:\n condition: service_healthy\n restart: true\n\n mariadb-romm:\n image: mariadb:latest\n container_name: mariadb-romm\n restart: unless-stopped\n environment:\n - MARIADB_ROOT_PASSWORD= # Use a unique, secure password\n - MARIADB_DATABASE=romm\n - MARIADB_USER=romm-user\n - MARIADB_PASSWORD=\n ports:\n - 3309:3306\n network_mode: rommbridge\n volumes:\n - /volume1/docker/mariadb-romm:/var/lib/mysql\n healthcheck:\n test: [\"CMD\", \"healthcheck.sh\", \"--connect\", \"--innodb_initialized\"]\n start_period: 30s\n start_interval: 10s\n interval: 10s\n timeout: 5s\n retries: 5\nhttp://your-server-ip:7676Important
This guide is an abridged version of ChopFoo's original guide. If you have any suggestions or improvements, please submit a pull request to the RomM wiki.
"},{"location":"System-Setup/Tinfoil-Integration/","title":"Tinfoil Integration","text":"This will help you configure the Tinfoil integration for your Switch to work with your RomM library.
"},{"location":"System-Setup/Tinfoil-Integration/#prepare","title":"Prepare","text":"Please note down the following in order to make this as smooth as possible, as well as some pre-reqs:
DISABLE_DOWNLOAD_ENDPOINT_AUTH=true to your environment variables and restart the containerhttp or https/api/tinfoil/feedNow it's time to configure your switch - Please follow the steps, this will assume you have Tinfoil installed and know how to use the basic functions of it.
http or https depending on your connectionmotd: \" RomM Switch Library\"Now you will be able to see the files in \"New Games\" tab of Tinfoil OR you can access it within the \"File Browser\" section that you setup earlier.
"},{"location":"System-Setup/Tinfoil-Integration/#additional","title":"Additional","text":"It didn't pull anything through to \"New Games\" and has not parsed any information about the titles?!
That would be because the filename it has tried to pull had no TitleID (Improvement to RomM coming soon )
Make sure the filename has the TitleID within the title like this:
Once this is done, the next time Tinfoil is opened it is always parsed and re-scanned.
"},{"location":"System-Setup/TrueNAS-Setup-Guide/","title":"TrueNAS Setup","text":""},{"location":"System-Setup/TrueNAS-Setup-Guide/#prerequisites","title":"Prerequisites","text":"This guide assumes you're familiar with Docker and have basic knowledge of TrueNAS. You'll need:
Navigate to the App Catalog via Apps (Left navigation bar) -> Discover Apps -> RomM -> Install
"},{"location":"System-Setup/TrueNAS-Setup-Guide/#step-2-installation-configuration","title":"Step 2: Installation configuration","text":"Step through the installation UI. You will need to supply various credentials per the Quick Start Guide. Most of the default values will work.
Note: You will likely want to set certain Storage Configurations to a Dataset within TrueNAS, such as your RomM Library and Assets storage. If you do this, ensure you provide ACL access to the UserID specified above (default: 568, apps user).
"},{"location":"System-Setup/TrueNAS-Setup-Guide/#step-3-save-your-configuration","title":"Step 3: Save your configuration","text":"Save, and you're done! If the app will not boot, refer to Troubleshooting or head on over to the Discord.
"},{"location":"System-Setup/TrueNAS-Setup-Guide/#install-via-yaml","title":"Install via YAML","text":"This installation path should only be used in the event that there is a bug with installing through the App Catalog, or you wish to have more flexibility than is provided by the installation UI.
"},{"location":"System-Setup/TrueNAS-Setup-Guide/#step-1-navigate-to-yaml-install","title":"Step 1: Navigate to YAML install","text":"Navigate to the Install via YAML page via Apps (Left navigation bar) -> Discover Apps -> Install via YAML
Replace any empty values with credentials you've created per the Quick Start Guide.
Example Docker Composeversion: \"3\"\n\nvolumes:\n mysql_data:\n romm_redis_data:\n\nservices:\n romm:\n image: rommapp/romm:latest\n container_name: romm\n restart: unless-stopped\n user: 568:568\n environment:\n - DB_HOST=romm-db\n - DB_NAME=romm # Should match MARIADB_DATABASE in mariadb\n - DB_USER=romm-user # Should match MARIADB_USER in mariadb\n - DB_PASSWD= # Should match MARIADB_PASSWORD in mariadb\n - ROMM_AUTH_SECRET_KEY= # Generate a key with `openssl rand -hex 32`\n - IGDB_CLIENT_ID= # Generate an ID and SECRET in IGDB\n - IGDB_CLIENT_SECRET= # https://api-docs.igdb.com/#account-creation\n - MOBYGAMES_API_KEY= # https://www.mobygames.com/info/api/\n - STEAMGRIDDB_API_KEY= # https://github.com/rommapp/romm/wiki/Generate-API-Keys#steamgriddb\n volumes: # Any /mnt paths may optionally be replaced with a docker volume\n - /mnt/tank/truenas/resources:/romm/resources # Replace /mnt...: file path with your own data structure\n - romm_redis_data:/romm/redis-data # Docker will manage this volume\n - /mnt/tank/truenas/roms:/romm/library # Replace /mnt...: file path with your own data structure\n - /mnt/tank/truenas/assets:/romm/assets # Replace /mnt...: file path with your own data structure\n - /mnt/tank/truenas/config:/romm/config # Replace /mnt...: file path with your own data structure\n ports:\n - 31100:8080\n depends_on:\n romm-db:\n condition: service_healthy\n restart: true\n deploy:\n resources:\n limits:\n cpus: \"2.0\"\n memory: 4g\n\n romm-db:\n image: mariadb:latest\n container_name: romm-db\n restart: unless-stopped\n environment:\n - MARIADB_ROOT_PASSWORD= # Use a unique, secure password\n - MARIADB_DATABASE=romm\n - MARIADB_USER=romm-user\n - MARIADB_PASSWORD=\n volumes:\n - mysql_data:/var/lib/mysql\n healthcheck:\n test: [\"CMD\", \"healthcheck.sh\", \"--connect\", \"--innodb_initialized\"]\n start_period: 30s\n start_interval: 10s\n interval: 10s\n timeout: 5s\n retries: 5\nSave, and you're done! If the app will not boot, refer to Troubleshooting or head on over to the Discord.
"},{"location":"System-Setup/TrueNAS-Setup-Guide/#troubleshooting","title":"Troubleshooting","text":""},{"location":"System-Setup/TrueNAS-Setup-Guide/#general","title":"General","text":"If you are encountering permissions issues with folders internal to the docker image (not your TrueNAS dataset), consider temporarily setting the user to root (user: 0). If you do this, it is recommended you fix local file permissions via shell and return access back to a non-root user.
In my particular setup, I had to create a user/group in TrueNAS with uid:gid of 1000:1000 and auxiliary group apps due to hard-coded values in the RomM docker image. This resolved outstanding issues I had with my instance of RomM talking to its Redis instance.
If you have any suggestions or improvements, please submit a pull request to the RomM wiki.
"},{"location":"System-Setup/Unraid-Setup-Guide/","title":"Unraid Setup","text":""},{"location":"System-Setup/Unraid-Setup-Guide/#prerequisites","title":"Prerequisites","text":"Before getting started, install the Community Apps plugin for Unraid.
"},{"location":"System-Setup/Unraid-Setup-Guide/#docker-network","title":"Docker network","text":"You'll want to create a custom bridge-type network for both containers to communicate with each other. This will prevent a number of common issues Unraid users tend to come across during setup. This can be done with the following command: docker network create romm, and you can verify it worked with docker network ls.
MariaDB is required to run RomM, so install it from the plugin registry. Only the official and linuxserver versions are supported, but the official version is preferred.
Now fill in all the environment variables; descriptions of the options and sensible defaults are listed in the example docker-compose.yml file.
Warning
The network type must be set to Custom: romm
From the Unraid dashboard, click APPS in the navigation bar. In the search bar, search for romm, and install the app listed as \"OFFICIAL\". This one is maintained by our team and is the most up-to-date.
Configure the required environment variables, ports and paths as per the example docker-compose.yml file.
Warning
The network type must also be set to Custom: romm
Apply the changes, then head to the DOCKER tab. You should see both containers in a running state, and can access RomM using the IP:PORT of the container (highlighted below).
**It's strongly recommended to backup the appdata folder (or mount it in a safe location) before updating, since tearing down the container will wipe the resources (covers, screenshots, etc.)
DemonWarriorTech has published How to Install RomM on Unraid (Beginner Friendly) on installing and running RomM on Unraid for Beginners with an in depth instructions and explanation of the software install and how to use it.
AlienTech42 has published a great video on installing and running RomM on Unraid. While a bit out of date vis-a-vis install instructions, it's still very useful for general setup and debugging. Check it out!
"},{"location":"System-Setup/Unraid-Setup-Guide/#shout-outs","title":"Shout-outs","text":"We want to give a special shout-out to @Smurre95 and @sfumat0 for their help documenting this process, and working towards getting RomM listed in CA. \ud83e\udd1d
"},{"location":"Tools/Igir-Collection-Manager/","title":"Igir Collection Manager","text":"Igir is a zero-setup ROM collection manager that sorts, filters, extracts or archives, patches, and reports on collections of any size on any OS. It can be used to rename your ROMs to match the RomM database, and to move them into a new directory structure.
"},{"location":"Tools/Igir-Collection-Manager/#setup","title":"Setup","text":""},{"location":"Tools/Igir-Collection-Manager/#directory-structure","title":"Directory structure","text":"The directory structure is important for running the bulk ROM renaming script. Before running the bulk ROM renaming script, set up your directories as follows:
.\n\u251c\u2500\u2500 dats/ # DAT files from no-intro.org\n\u251c\u2500\u2500 roms/ # Original ROM collection\n\u251c\u2500\u2500 roms-unverified/ # Working copy of ROMs\n\u2514\u2500\u2500 igir-romm-cleanup.sh\nCreate a working copy of your ROMs:
cp -r roms/ roms-unverified/\nThis provides a safe working environment and allows for easy script adjustment if needed.
Download DAT Files:
Extract the DAT files to your dats directory. You can optionally extract a subset of the .dat files into the directory instead.
Create the cleanup script igir-romm-cleanup.sh with the contents below:
#!/usr/bin/env bash\nset -ou pipefail\ncd \"$(dirname \"${0}\")\"\n\nINPUT_DIR=roms-unverified\nOUTPUT_DIR=roms-verified\n\n# Documentation: https://igir.io/\n# Uses dat files: https://datomatic.no-intro.org/index.php?page=download&op=daily\ntime npx -y igir@latest \\\n move \\\n extract \\\n report \\\n test \\\n -d dats/ \\\n -i \"${INPUT_DIR}/\" \\\n -o \"${OUTPUT_DIR}/{romm}/\" \\\n --input-checksum-quick false \\\n --input-checksum-min CRC32 \\\n --input-checksum-max SHA256 \\\n --only-retail\nMake the script executable:
chmod a+x igir-romm-cleanup.sh\nRun the script. It will generate a new output directory named roms-verified, moving the files from roms-unverified if its checksum matches any of the known checksums in the DAT files provided. Any ROMs not identified will remain in the roms-unverified directory.
The script may not identify all of the ROMs in your input directory. You can choose to migrate them over manually:
npx -y igir@latest \\\n move \\\n -i roms-unverified/ \\\n -o roms-verified/ \\\n --dir-mirror\nThis will move your ROMs from the input to the output directory, preserving the subdirectory structure. It also cleans up file extensions in the process.
"},{"location":"Tools/Igir-Collection-Manager/#reorganize-multi-disc-games","title":"Reorganize multi-disc games","text":"The Igir script will move games that have multiple discs to separate folders. This can confuse RomM's game detection, and those games need to be reorganized into single folders with many discs.
To do this enter your platform directory, such as ps or psx and run the following:
ls -d *Disc* | while read dir; do\n game=$(echo \"${dir}\" | sed -r 's/ \\(Disc [0-9]+\\)//')\n mkdir -p \"${game}\"\n mv \"${dir}\"/* \"${game}/\"\n rm -rf \"${dir}\"\ndone\nThis will find any directory with (Disc in the name and move the files into a new directory without the (Disc #) string. For example:
Before:
Final Fantasy VII (Disc 1) (USA)\nFinal Fantasy VII (Disc 2) (USA)\nGets combined to:
Final Fantasy VII (USA)\nUse the side-bar to your left for navigation
"},{"location":"Troubleshooting/Authentication-Issues/","title":"Troubleshooting Authentication","text":""},{"location":"Troubleshooting/Authentication-Issues/#error-403-forbidden","title":"Error:403 Forbidden","text":"When authentication is enabled, most endpoints will return a 403 Forbidden response if you're not authenticated, or if your sessions is in a broken state. The session key can be reset by clearing your cookies.
CSRF protection is also enabled, which helps to mitigates CSRF attacks (useful if your instance is public). If you encounter a Forbidden (403) CSRF verification failed error, simply reloading your browser should force it to fetch a fresh CSRF cookie.
Unable to login: CSRF token verification failed","text":"This error is known to happen on Chrome, but could happen in other browsers; manually clear your cookies (specifically one called csrftoken) and hard reload your browser window (CMD+SHIFT+R on macOS, CTRL+F5 on Windows).
400 Bad Request on the Websocket endpoint","text":"If you're running RomM behind a reverse-proxy (Caddy, Nginx, etc.), ensure that Websockets are supported and enabled. This may vary depending on the reverse proxy solution being used. In the case of Nginx Proxy Manager, enable the \"Websockets Support\" toggle when editing the proxy host.
"},{"location":"Troubleshooting/Miscellaneous-Troubleshooting/","title":"Miscellaneous Troubleshooting","text":""},{"location":"Troubleshooting/Miscellaneous-Troubleshooting/#restarting-the-container-when-using-sqlite-drops-all-the-datarequires-a-full-re-scan","title":"Restarting the container when using SQLite drops all the data/requires a full re-scan","text":"Verify that the database is mapped to a persistent storage volume in your docker compose or Unraid template.
\"/path/to/database:/romm/database\" # [Optional] Only needed if ROMM_DB_DRIVER=sqlite or not set\nCould not get twitch auth token: check client_id and client_secret","text":"This is likely due to mis-configured environment variables; verify that CLIENT_ID and CLIENT_SECRET are set correctly, and that both match the values in IGDB.
There are a few common reasons why a scan may end instantly/without scanning platforms
/romm/libraryls -lhromm folder structure","text":"This is the same issue as the one above, and can be quickly solved by verifying your folder structure. RomM expects a library with a folder named roms in it, for example:
/server/media/library:/romm/library/server/media/games/roms:/romm/library/romsWhen scanning the folders mounted in /library/roms, the scanner tries to match the folder name with the platform's slug in IGDB. If you notice that the scanner isn't detecting a platform, verify that the folder name matches the slug in the URL of the platform in IGDB. For example, the Nintendo 64DD has the URL https://www.igdb.com/platforms/nintendo-64dd, so the folder should be named nintendo-64dd.
The background scan task times out after 4 hours, which can happen if you have a very large library. The easiest work around is to keep running scans every 4 hours, without checking the \"Complete re-scan\" option.
"},{"location":"Troubleshooting/Synology-Issues/","title":"Troubleshooting Synology","text":""},{"location":"Troubleshooting/Synology-Issues/#errno-13-access-denied","title":"ErrNo 13: Access Denied","text":"We have noticed recently a spate of access denied on Synology systems via Portainer or even docker manager. The ErrNo13 is directly related to Synology and it is a simple permission issue. To fix it please do the following:
sudo chown -R user:group /path/to/library
sudo chmod -R a=,a+rX,u+w,g+w /path/to/library
sudo chown -R user:group /path/to/assets
sudo chmod -R a=,a+rX,u+w,g+w /path/to/assets
sudo chown -R user:group /path/to/config
sudo chmod -R a=,a+rX,u+w,g+w /path/to/config
You will find the relevant directories in your compose, this is basically the folders where you store your RomM information and we are just resetting permissions. Restart the containers and you should now have no issues scanning information in!
Any issues please ask in the Discord.
Thanks to Docker IDs - DrFrankenstein for the guidance from his blog.
"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":"Welcome to the RomM Project, the premier self-hosted, open source ROM manager.
Website | DemoRomM (ROM Manager) allows you to scan, enrich, and browse your game collection with a clean and responsive interface. With support for multiple platforms, various naming schemes, and custom tags, RomM is a must-have for anyone who plays on emulators.
To get started with RomM, head over to the Quick Start guide in the main repository.
"},{"location":"#philosophy","title":"Philosophy","text":"At the heart of this project is a commitment to freedom, collaboration, and transparency. We believe that software should be built for the benefit of its users, rather than solely to maximize profit or serve the interests of a few stakeholders, ensuring that it doesn't manipulate, exploit, or prioritize data collection.
By offering RomM as a self-hosted, open-source solution, we ensure that everyone has the ability to manage their game collections on their own terms, and own their data, all without being tied to proprietary systems or services.
Rom is and will always be free and open-source software.
The core app is licensed under GNU AGPLv3, which requires that all modifications to the code be made available under the same license. This ensures that the community can benefit from and build upon the contributions of others, promoting trust and transparency.
Other projects under the umbrella will be licensed under similar permissive licenses, such as GNU GPLv3 for software, or CC0 for documentation.
"},{"location":"#contributing","title":"Contributing","text":"RomM is a collaborative project, and we welcome contributions from the community. Our code is available on GitHub, and we encourage you to contribute to the project by submitting bug reports, feature requests, or pull requests. Please check the contribution guidelines in each project for more information.
"},{"location":"#community","title":"Community","text":"We strive to create a safe and respectful space where everyone can contribute and benefit from the project by fostering a welcoming and inclusive environment for all users, regardless of their background or identity.
Join us on Discord, where you can ask questions, submit ideas, get help, showcase your collection, and discuss RomM with other users.
"},{"location":"Getting-Started/Authentication/","title":"Authentication","text":"RomM provides support for various forms of authentication, granting flexibility in securing access to its features.
"},{"location":"Getting-Started/Authentication/#setup","title":"Setup","text":"You'll want to set the following environment variable before starting RomM:
ROMM_AUTH_SECRET_KEY is required and can be generated with openssl rand -hex 32When the /login endpoint is called with valid credentials, a session_id is generated, stored as a cookie and sent to the browser. The same token is used to create a cache entry in Redis (or in-memory if Redis is disabled) which maps the token to the user. This way no sensitive information is stored on the client.
A user can have one of the following roles:
As permissions are additive, editors will have all permissions of the viewer role, and admins all those of the editor role.
Requests can be made to protected API endpoints with an authorization header. The token is the base64 encoded value of username:password.
Example using cURL:
curl https://romm.local/api/platforms -H 'Authorization: Basic YWRtaW46aHVudGVyMg=='\nAlong with the above forms of authentication, we've added an endpoint to generate expiring, scope-limited authentication tokens (/api/token). Successfully authenticating with that endpoint with return an access_token valid for 15 minutes, and a refresh_token valid for 2 weeks. The refresh_token can be used to generate a new access_token when needed.
The /api/token endpoint requires a username, password, and a list of scopes in the format read:roms write:roms read:platforms .... The list of scopes and endpoints are available to browse via Swagger UI or ReDoc (see next section).
Note: As of now, only the legacy password grant type is supported. We plan to eventually add support for Client Credentials.
"},{"location":"Getting-Started/Authentication/#openapi","title":"OpenAPI","text":"The API endpoints are fully documented and compliant with the OpenAPI specification. Explore the API endpoints using the Swagger UI interface at /api/docs and the ReDoc interface at /api/redoc, or view the raw JSON at /openapi.json.
For more information on OpenAPI, visit the OpenAPI Specification website.
"},{"location":"Getting-Started/Authentication/#faq","title":"FAQ","text":""},{"location":"Getting-Started/Authentication/#can-i-disable-authentication","title":"Can I disable authentication?","text":"No, authentication is required and enabled by default.
"},{"location":"Getting-Started/Authentication/#i-want-to-allow-an-editor-to-edit-roms-but-not-delete-them-can-i-do-that","title":"I want to allow an EDITOR to edit ROMs but not delete them. Can I do that?","text":"At this time, fine-grain control over permissions within a role is not supported. This decision was taking in order to simplify user management in the client, and authentication/permission code on the server.
"},{"location":"Getting-Started/Authentication/#is-authentication-saferobust-can-i-trust-it","title":"Is authentication safe/robust? Can I trust it?","text":"We've done our best to build an authentication system that is simple, clear and comprehensible. We have automated tests which verify that access is granted when it should be, and blocked when not (invalid credentials, missing permissions, expired access tokens, etc.). That being said, we welcome any reviews of our authentication and permission flows, PRs to fix issues, and new tests to cover edge cases.
"},{"location":"Getting-Started/Authentication/#i-found-an-bugissue-with-authentication-how-do-i-report-it","title":"I found an bug/issue with authentication. How do I report it?","text":"Please report bugs in our authentication/permission system privately by submitting a vulnerability report.
"},{"location":"Getting-Started/Environment-Variables/","title":"Environment Variables","text":"This is a complete list of available environment variables; required variables are marked with a \u2713.
Tip
You can also set environment variables with a _FILE suffix, which will load the contents of the file specified in the variable into the variable without the suffix. For example, setting ROMM_AUTH_SECRET_KEY_FILE=/run/secrets/romm_auth_secret_key and creating a file with the secret key at the specified path will set ROMM_AUTH_SECRET_KEY to the contents of the file. Learn more.
openssl rand -hex 32 \u2713 DISABLE_CSRF_PROTECTION Disables CSRF protection (not recommended) false DISABLE_DOWNLOAD_ENDPOINT_AUTH Disable auth on download endpoint (WebRcade, Tinfoil) false DISABLE_USERPASS_LOGIN Disables login with username and password (when using OIDC) false UPLOAD_TIMEOUT Timeout for file uploads (in seconds) 600 SCAN_TIMEOUT Timeout for the background scan/rescan tasks (in seconds) 14400 DISABLE_EMULATOR_JS Disables playing in browser with EmulatorJS false DISABLE_RUFFLE_RS Disables playing flash games with RuffleRS false TZ Sets the timezone UTC GUNICORN_WORKERS Number of processes running the app 2 ROMM_BASE_PATH Base folder path for library, resources and assets /romm LOGLEVEL Logging level for the app INFO FORCE_COLOR Forces color output false NO_COLOR Disables color output false"},{"location":"Getting-Started/Environment-Variables/#dependencies","title":"Dependencies","text":"Variable Description Required Default DB_HOST Host name of database instance \u2713 127.0.0.1 DB_PORT Port number of database instance 3306 DB_NAME Should match MYSQL_DATABASE in MariaDB romm DB_USER Database username (in MariaDB, should match MARIADB_USER) \u2713 DB_PASSWD Database password (in MariaDB, should match MARIADB_PASSWORD) \u2713 ROMM_DB_DRIVER Database driver to use (options: mariadb, mysql, postgresql) mariadb REDIS_HOST Host name of Redis/Valkey instance 127.0.0.1 REDIS_PORT Port number of Redis/Valkey instance 6379 REDIS_USERNAME Username for Redis/Valkey instance REDIS_PASSWORD Password for Redis/Valkey instance REDIS_DB Database number for Redis/Valkey instance 0 REDIS_SSL Enable SSL for Redis instance false SENTRY_DSN DSN for Sentry error tracking"},{"location":"Getting-Started/Environment-Variables/#metadata-providers","title":"Metadata providers","text":"Variable Description Required Default IGDB_CLIENT_ID Client ID for IGDB API IGDB_CLIENT_SECRET Client secret for IGDB API MOBYGAMES_API_KEY MobyGames secret API key STEAMGRIDDB_API_KEY SteamGridDB secret API key"},{"location":"Getting-Started/Environment-Variables/#authentication","title":"Authentication","text":"Variable Description Required Default OIDC_ENABLED Enable OpenID Connect (OIDC) authentication false 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_TLS_CACERTFILE Path to a file containing trusted CA certificates"},{"location":"Getting-Started/Environment-Variables/#background-tasks","title":"Background tasks","text":"Variable Description Required Default ENABLE_RESCAN_ON_FILESYSTEM_CHANGE Enable re-scanning of library when filesystem changes false RESCAN_ON_FILESYSTEM_CHANGE_DELAY Delay in minutes before re-scanning library when filesystem changes 5 ENABLE_SCHEDULED_RESCAN Enable scheduled re-scanning of library false SCHEDULED_RESCAN_CRON Cron expression for scheduled re-scanning \"0 3 * * *\" ENABLE_SCHEDULED_UPDATE_SWITCH_TITLEDB Enable scheduled updating of Switch TitleDB index false SCHEDULED_UPDATE_SWITCH_TITLEDB_CRON Cron expression for scheduled updating of Switch TitleDB \"0 4 * * *\""},{"location":"Getting-Started/Generate-API-Keys/","title":"Generate API Keys","text":""},{"location":"Getting-Started/Generate-API-Keys/#igdb","title":"IGDB","text":"To access the IGDB API you'll need a Twitch account and a valid phone number for 2FA verification. Up-to-date instructions are available in the IGDB API documentation. When registering your application in the Twitch Developer Portal, fill out the form like so:
correct-horse-battery-staple or KVV8NDXMSRFJ2MRNPNRSL7GQTlocalhostApplication IntegrationConfidentialImportant
The name you pick has to be unique! Picking an existing name will fail silently, with no error messages. We recommend using romm-<random hash>, like romm-3fca6fd7f94dea4a05d029f654c0c44b
Note the client ID and secret that appear on screen, and use them to set IGDB_CLIENT_ID and IGDB_CLIENT_SECRET in your environment variables.
To access the MobyGames API, create a MobyGames account and then visit your profile page. Click the API link under your user name to sign up for an API key. Copy the key shown and use it to set MOBYGAMES_API_KEY.
Important
MobyGames API became a paid feature. Any existing key can be used as usual, but any new API key created will be under a paywall
"},{"location":"Getting-Started/Generate-API-Keys/#steamgriddb","title":"SteamGridDB","text":"To access steamGridDB API, you need to login into their website with a steam account. Once logged in, go to your API tab under the preferences page. Copy the key shown and use it to set STEAMGRIDDB_API_KEY.
This quick start guide will help you get a RomM instance up and running. It is split into 3 parts:
This guide will assume that you already have the following done, if not - stop here and come back when you do.
Warning
Not setting up RomM with a metadata API will work for basic operation but can cause issues with, for instance, the Playnite plugin. It is recommended to setup IGDB API keys to avoid issues during setup.
"},{"location":"Getting-Started/Quick-Start-Guide/#twitch-and-mobygames-api-keys","title":"Twitch and MobyGames API Keys","text":"Head over to API key docs to get your Twitch and/or MobyGames keys, then come back here
"},{"location":"Getting-Started/Quick-Start-Guide/#generating-authentication-keys","title":"Generating Authentication Keys","text":"This step will generate a key that is used in the authorization of RomM. Without this, you will be unable to log in and use the platform
Run the following command in a terminal:
openssl rand -hex 32\nThen copy the output and save it to the ROMM_AUTH_SECRET_KEY variable in the docker-compose file. It should look like this:
~$: openssl rand -hex 32\n03a054b6ca27e0107c5eed552ea66becd9f3a2a8a91e7595cd462a593f9ecd09\nNow that we have everything gathered, we can begin getting your instance set up!
MYSQL_ROOT_PASSWORD: Sets the root password of the database. Use a unique and secure password (use a password generator for simplicity)MYSQL_DATABASE: Sets the database name for RomM. This can be modified - but it's not necessaryMYSQL_USER: User to connect to the database with. This can be modified - but it's not necessaryMYSQL_PASSWORD: Password for the user to connect to the database with. Use a unique and secure password (use a password generator for simplicity)DB_NAME: Name of the database set in the database sectionDB_USER: Name of the user to connect to the databaseDB_PASSWD: Password of the user to connect to the database/path/to/library: Path to the directory where your rom files will be stored/path/to/assets: Path to the directory where you will store your saves, etc/path/to/config: Path to the directory where you will store the config.ymlSave the file as docker-compose.yml instead of docker-compose.example.yml. It should look something like this:
Example Docker Composeversion: \"3\"\n\nvolumes:\n mysql_data:\n romm_resources:\n romm_redis_data:\n\nservices:\n romm:\n image: rommapp/romm:latest\n container_name: romm\n restart: unless-stopped\n environment:\n - DB_HOST=romm-db\n - DB_NAME=romm # Should match MARIADB_DATABASE in mariadb\n - DB_USER=romm-user # Should match MARIADB_USER in mariadb\n - DB_PASSWD= # Should match MARIADB_PASSWORD in mariadb\n - ROMM_AUTH_SECRET_KEY= # Generate a key with `openssl rand -hex 32`\n - IGDB_CLIENT_ID= # Generate an ID and SECRET in IGDB\n - IGDB_CLIENT_SECRET= # https://api-docs.igdb.com/#account-creation\n - MOBYGAMES_API_KEY= # https://www.mobygames.com/info/api/\n - STEAMGRIDDB_API_KEY= # https://github.com/rommapp/romm/wiki/Generate-API-Keys#steamgriddb\n volumes:\n - romm_resources:/romm/resources # Resources fetched from IGDB (covers, screenshots, etc.)\n - romm_redis_data:/redis-data # Cached data for background tasks\n - /path/to/library:/romm/library # Your game library. Check https://github.com/rommapp/romm?tab=readme-ov-file#folder-structure for more details.\n - /path/to/assets:/romm/assets # Uploaded saves, states, etc.\n - /path/to/config:/romm/config # Path where config.yml is stored\n ports:\n - 80:8080\n depends_on:\n romm-db:\n condition: service_healthy\n restart: true\n\n romm-db:\n image: mariadb:latest\n container_name: romm-db\n restart: unless-stopped\n environment:\n - MARIADB_ROOT_PASSWORD= # Use a unique, secure password\n - MARIADB_DATABASE=romm\n - MARIADB_USER=romm-user\n - MARIADB_PASSWORD=\n volumes:\n - mysql_data:/var/lib/mysql\n healthcheck:\n test: [\"CMD\", \"healthcheck.sh\", \"--connect\", \"--innodb_initialized\"]\n start_period: 30s\n start_interval: 10s\n interval: 10s\n timeout: 5s\n retries: 5\nOpen the terminal and navigate to the directory containing the docker-compose file
docker compose up -d to kick off the docker pull. You will see it pull the container and set up the volumes and network: RomM docker compose install docker ps -f name=romm to verify that the containers are runninghttp://localhost:8080, where you should be greeted with the RomM setup pageNow that the container is running, we will configure it by importing your ROMs
"},{"location":"Getting-Started/Quick-Start-Guide/#uploading-your-roms-via-web-interface","title":"Uploading Your ROMs via Web Interface","text":"This method is certainly viable, but not recommended if you have a lot of ROMs and/or multiple platforms. It is good for adding after the fact as your collection grows, but wouldn't be recommended for the first set up, nor for multi-file ROMs
roms/platforms you haveThis method is generally the fastest and recommended for first time setup
docker compose down if you are in the terminal and directory containing the docker-compose file, otherwise docker stop romm:/romm/library and create a folder named romsroms folder you createddocker compose up -d if you are in the terminal and directory containing the docker-compose file, otherwise docker start rommHere are some basic configurations for popular reverse proxies. Some installations may require modifications to configuration options not listed below.
"},{"location":"Getting-Started/Reverse-Proxy/#caddy","title":"Caddy","text":"http://romm.mysite.com {\n reverse_proxy romm:8080\n}\nhttps://romm.mysite.com {\n tls mysite.com.crt mysite.com.key # Certificate and key files\n\n encode zstd gzip\n\n header * {\n Strict-Transport-Security \"max-age=31536000;\"\n X-XSS-Protection \"1; mode=block\"\n X-Frame-Options \"SAMEORIGIN\"\n X-Robots-Tag \"noindex, nofollow\"\n -Server\n -X-Powered-By\n }\n\n reverse_proxy romm:8080\n}\nserver {\n listen 80 default_server;\n server_name romm.mysite.com;\n client_max_body_size 0;\n\n location / {\n include /config/nginx/proxy.conf;\n include /config/nginx/resolver.conf;\n set $upstream_app romm;\n set $upstream_port 8080;\n set $upstream_proto http;\n proxy_pass $upstream_proto://$upstream_app:$upstream_port;\n }\n}\nserver {\n listen 80 default_server;\n server_name _;\n return 301 https://$host$request_uri;\n}\n\nserver {\n listen 443 ssl http2;\n listen [::]:443 ssl http2;\n\n server_name romm.mysite.com;\n include /config/nginx/ssl.conf;\n client_max_body_size 0;\n\n location / {\n include /config/nginx/proxy.conf;\n include /config/nginx/resolver.conf;\n set $upstream_app romm;\n set $upstream_port 8080;\n set $upstream_proto http;\n proxy_pass $upstream_proto://$upstream_app:$upstream_port;\n\n # Hide version\n server_tokens off;\n\n # Security headers\n add_header X-Frame-Options \"SAMEORIGIN\" always;\n add_header X-Content-Type-Options \"nosniff\" always;\n add_header X-XSS-Protection \"1; mode=block\" always;\n add_header Strict-Transport-Security \"max-age=31536000; includeSubDomains\" always;\n add_header Referrer-Policy \"no-referrer-when-downgrade\" always;\n }\n}\nItems marked with \u2757 are important to set, as RomM may not correctly otherwise!
"},{"location":"Getting-Started/Reverse-Proxy/#details","title":"\u26a1 Details","text":"romm.example.com (replace example with your own)* Scheme: http8080offonon \u2757Strongly recommended, but only required if you plan to secure your site (use HTTPS)
ononoffonCustom Nginx Configuration \u2757
proxy_max_temp_file_size 0;\nhttp:\n romsdomainse:\n entryPoints:\n - \"https\"\n rule: \"Host(`roms.domain.se`)\"\n middlewares:\n - default-headers\n - https-redirectscheme\n tls:\n certResolver: http\n service: romsdomainse\n\nservices:\n romsdomainse:\n loadBalancer:\n servers:\n - url: \"http://192.168.1.100:8080\"\n passHostHeader: true\nlabels:\n - \"traefik.enable=true\"\n - \"traefik.http.services.romm.loadbalancer.server.port=8080\"\n - \"traefik.http.routers.romm.rule=Host(`romm.YOUR_DOMAIN.com`)\"\n - \"traefik.http.routers.romm.entrypoints=websecure\"\n - \"traefik.http.routers.romm.tls=true\"\n - \"traefik.http.routers.romm.tls.certresolver=https\"\nScheduled tasks can be enabled and configured with the following environment variables:
Variable Description Value ENABLE_SCHEDULED_RESCAN Enable scheduled re-scanning of librarytrue SCHEDULED_RESCAN_CRON Cron expression for scheduled re-scanning \"0 3 * * *\" ENABLE_SCHEDULED_UPDATE_SWITCH_TITLEDB Enable scheduled updating of Switch TitleDB index true SCHEDULED_UPDATE_SWITCH_TITLEDB_CRON Cron expression for scheduled updating of Switch TitleDB \"0 4 * * *\" ENABLE_SCHEDULED_UPDATE_MAME_XML Enable scheduled updating of MAME XML index true SCHEDULED_UPDATE_MAME_XML_CRON Cron expression for scheduled updating of MAME XML \"0 5 * * *\""},{"location":"Maintenance/Scheduled-Tasks/#scheduled-re-scan","title":"Scheduled re-scan","text":"Users can opt to enable scheduled re-scans, and set the interval using Cron notation. Not that the scan will not completely re-scan every file, only catching those which have been added/updated.
"},{"location":"Maintenance/Scheduled-Tasks/#switch-titledb-update","title":"Switch titleDB update","text":"Support was added for Nintendo Switch ROMs with filenames using the titleid/programid format (e.g. 0100000000010000.xci). If a file under the switch folder matches the regex, the scanner will use the index to attempt to match it to a game. If a match is found, the IGDB handler will use the matched name as the search term.
The associated task updates the /fixtures/switch_titledb.json file at a regular interval to support new game releases.
Support was also added for MAME arcade games with shortcode names (e.g. actionhw.zip -> ACTION HOLLYWOOD), and works in the same way as the TitleID matcher (without the regex).
The associated task updates the /fixtures/mame.xml file at a regular interval to support updates to the library.
RomM can also monitor the filesystem for events (files created/moved/deleted) and schedules a re-scan of the platform (or entire library is a new platform was added).
The watcher can be enabled and configured with the following environment variables:
Variable Description Value ENABLE_RESCAN_ON_FILESYSTEM_CHANGE Enable re-scanning of library when filesystem changestrue RESCAN_ON_FILESYSTEM_CHANGE_DELAY Delay in minutes before re-scanning library when filesystem changes 5 The watcher will monitor the /library/roms folder for changes to the filesystem, such as files being added, moved or deleted. It will ignore certain events (like modifying the file content or metadata), and will skip default OS files (like .DS_Store on mac).
When a change is detected, a scan will be scheduled for sometime in the future (default 5 minutes). If other events are triggered between now and the time at which the scan starts, more platforms will be added to the scan list (or the scan may switch to a full scan). This is done to reduce the number of tasks scheduled when many big changes happen to the library (mass upload, new mount, etc.)
"},{"location":"Maintenance/Upgrading-to-3.0/","title":"Upgrading to 3.0","text":"Version 3.0 of RomM introduces a number of breaking changes aimed at improving performance and usability, which will require some users to make specific changes before upgrading to ensure compatibility and to take full advantage of the new features.
All of the following changes are reflected in the example docker-compose.yml file, which has been simplified greatly. Please read this entire file carefully, as failing to do so may cause RomM to become inaccessible or unresponsive.
"},{"location":"Maintenance/Upgrading-to-3.0/#dropped-support-for-sqlite","title":"Dropped support for SQLite","text":"We're removed support for SQLite as we've faced a number of engineering issues with it in the past, and MariaDB has proven more stable and robust. If you currently use SQLite, we'll automatically migrate your data from SQLite to MariaDB, but you'll first need to make the following changes before upgrading to the latest image.
In your environment variables, change ROMM_DB_DRIVER to mariadb (or remove it completely as it's no longer needed). You'll then want to add the following environment variables:
- DB_HOST=mariadb\n- DB_PORT=3306\n- DB_NAME=romm # Should match MYSQL_DATABASE in mariadb\n- DB_USER=romm-user # Should match MYSQL_USER in mariadb\n- DB_PASSWD= # Should match MYSQL_PASSWORD in mariadb\nTo setup a new MariaDB container, have a look at the example docker-compose.yml file.
"},{"location":"Maintenance/Upgrading-to-3.0/#authentication-as-standard","title":"Authentication as standard","text":"To support new features like EmulatorJS and saves/states management, we've decided to require authentication for all users. Anyone currently running RomM with authentication disabled will need to remove the ROMM_AUTH_ENABLED environment variable and add the following ones:
- ROMM_AUTH_SECRET_KEY= # Generate a key with `openssl rand -hex 32`\nWe understand that this requirement for authentication might conflict with the way some users currently share their collection with others (unrestricted access for all). However, given the exciting new features we've built, and the ones we're looking to build in the near future, we feel this is the right decision for the project.
"},{"location":"Maintenance/Upgrading-to-3.0/#redis-is-now-built-in","title":"Redis is now built-in","text":"As Redis is required for authentication to work, we've integrated it directly into the docker image. If you're currently running the experimental Redis container, you can remove it, along with these environment variables:
- ENABLE_EXPERIMENTAL_REDIS\n- REDIS_HOST\n- REDIS_PORT\nMounting the config.yml file is now done by mounting a config folder.. Place your existing config.yml file inside a folder and bind it to /romm/config:
- /path/to/config:/romm/config\nUpdated config.example.yml
"},{"location":"Maintenance/Upgrading-to-3.0/#support-for-saves-states-and-screenshots","title":"Support for saves, states and screenshots","text":"This version introduces preliminary support for uploading/downloading saves, states and screenshots (read more about it in the 3.0 release notes). We've added a new volume mapping for these types of files called assets, which you'll want to bind to a local folder (or volume) so they'll persist. In your volumes section, add the following mapping, where /path/to/assets/ is some folder where you'll want to store these assets (and make sure that folder exists):
- /path/to/assets:/romm/assets\nWe recommend creating a folder next to your library/the one mapped to /romm/library in order to keep all your RomM files in the same place.
PSP emulation with the PPSSPP core requires special setup with a reverse proxy, or launching Chrome browser with the --disable-web-security and --enable-features=SharedArrayBuffer flags, which WE STRONGLY DISCOURAGE as it disables important security features.
When it's ready.
"},{"location":"Miscellaneous/FAQs/#when-will-the-version-after-that-one-release","title":"When will the version after that one release?","text":"After the upcoming version is released.
"},{"location":"Miscellaneous/FAQs/#when-will-x-feature-be-available","title":"When will X feature be available?","text":"Sometime between now and the heat death of the universe.
"},{"location":"Miscellaneous/FAQs/#when-will-version-xxx-of-romm-or-any-of-the-romm-clientsappsplugins-be-released","title":"When will versionx.x.x of RomM (or any of the RomM clients/apps/plugins) be released?","text":"Same as above question.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/","title":"OIDC Setup With Authelia","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#oidc-setup-with-authelia","title":"OIDC Setup With Authelia","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#a-quick-rundown-of-the-technologies","title":"A quick rundown of the technologies","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#what-is-authelia","title":"What is Authelia?","text":"Authelia is an open-source authentication and authorization server providing two-factor authentication and single sign-on (SSO) for your applications via a web portal. It acts as a companion for reverse proxies by allowing, denying, or redirecting requests. Authelia can be deployed alongside your other services to centralize identity management.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#what-is-oauth2","title":"What is OAuth2?","text":"OAuth2 (Open Authorization 2.0) is an industry-standard protocol for authorization. It allows applications (clients) to gain limited access to user accounts on an HTTP service without sharing the user\u2019s credentials. Instead, it uses access tokens to facilitate secure interactions. OAuth2 is commonly used in scenarios where users need to authenticate via a third-party service.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#what-is-openid-connect-oidc","title":"What is OpenID Connect (OIDC)?","text":"OIDC (OpenID Connect) is an identity layer built on top of OAuth2. While OAuth2 primarily handles authorization, OIDC adds authentication, enabling applications to verify a user\u2019s identity and obtain profile information. This makes OIDC suitable for SSO solutions, where user identity is central to access management.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#setting-up-a-provider-and-application-in-authelia","title":"Setting up a Provider and Application in Authelia","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#step-1-install-and-configure-authelia","title":"Step 1: Install and Configure Authelia","text":"Before setting up a provider and app, ensure that Authelia is installed and running by following the getting started and OIDC provider guides.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#step-2-add-a-client","title":"Step 2: Add a client","text":"In Authelia's configuration.yml, under identity_providers \u2192 oidc \u2192 clients, add a new entry:
client_id and client_secretpublic should be set to false.redirect_uris should include your RomM instance's URL + /api/oauth/openid (e.g., http://romm.host.local/api/oauth/openid).scopes includes openid, email and profile.token_endpoint_auth_method should be set to client_secret_basic.userinfo_signed_response_alg should be set to none.Refer to the official docs for more details.
This entry should look like this:
#identity_providers:\n# oidc:\n# clients:\n- client_id: \"<randomly_generated>\" # read above for how generate\n client_name: \"RomM\" # will be displayed in Authelia to users\n client_secret: \"$pbkdf2-sha512$randomly_generated\" # read above for how generate\n public: false\n authorization_policy: \"two_factor\" # or one_factor, depending on your needs\n grant_types:\n - authorization_code\n redirect_uris:\n - \"http://romm.host.local/api/oauth/openid\"\n scopes:\n - \"openid\"\n - \"email\"\n - \"profile\"\n userinfo_signed_response_alg: \"none\"\n token_endpoint_auth_method: \"client_secret_basic\"\nTo enable OIDC authentication in RomM, you need to set the following environment variables:
OIDC_ENABLED: Set to true to enable OIDC authentication.OIDC_PROVIDER: The lowercase name of the provider (authelia).OIDC_CLIENT_ID: The client ID copied from the Authelia application.OIDC_CLIENT_SECRET: The generated output from Random Password.OIDC_REDIRECT_URI: The redirect URI configured in the Authelia provider, in the format http://romm.host.local/api/oauth/openid.OIDC_SERVER_APPLICATION_URL: The base URL for you Authelia instance, e.g. http://authelia.host.local.In RomM, open your user profile and set your email address. This email has to match your user email in Authelia.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authelia/#step-5-test-the-integration","title":"Step 5: Test the Integration","text":"After configuring the environment variables, restart (or stop and remove) your RomM instance and navigate to the login page. You should see an option to log in using OIDC. Click on the OIDC button, and you'll be redirected to Authelia for authentication. Once authenticated, you'll be redirected back to RomM.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/","title":"OIDC Setup With Authentik","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#oidc-setup-with-authentik","title":"OIDC Setup With Authentik","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#a-quick-rundown-of-the-technologies","title":"A quick rundown of the technologies","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#what-is-authentik","title":"What is Authentik?","text":"Authentik is an open-source identity provider (IdP) designed to manage authentication, authorization, and user management across applications. It supports modern authentication protocols and provides tools to simplify integration, including single sign-on (SSO), multi-factor authentication (MFA), and auditing capabilities. Authentik can be deployed alongside your other services to centralize identity management.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#what-is-oauth2","title":"What is OAuth2?","text":"OAuth2 (Open Authorization 2.0) is an industry-standard protocol for authorization. It allows applications (clients) to gain limited access to user accounts on an HTTP service without sharing the user\u2019s credentials. Instead, it uses access tokens to facilitate secure interactions. OAuth2 is commonly used in scenarios where users need to authenticate via a third-party service.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#what-is-openid-connect-oidc","title":"What is OpenID Connect (OIDC)?","text":"OIDC (OpenID Connect) is an identity layer built on top of OAuth2. While OAuth2 primarily handles authorization, OIDC adds authentication, enabling applications to verify a user\u2019s identity and obtain profile information. This makes OIDC suitable for SSO solutions, where user identity is central to access management.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#setting-up-a-provider-and-application-in-authentik","title":"Setting up a Provider and Application in Authentik","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#step-1-install-and-configure-authentik","title":"Step 1: Install and Configure Authentik","text":"Before setting up a provider and app, ensure that Authentik is installed and running by following the official installation guide..
A provider in Authentik acts as the bridge between RomM and Authentik.
/api/oauth/openid (e.g., http://romm.host.local/api/oauth/openid).OIDC_CLIENT_ID and OIDC_CLIENT_SECRET in your RomM instance. An app in Authentik represents the external service (in our case RomM) that will use the provider for authentication.
romm). - Provider: Link the app to the previously created provider, \"RomM OIDC Provider\". To enable OIDC authentication in RomM, you need to set the following environment variables:
OIDC_ENABLED: Set to true to enable OIDC authentication.OIDC_PROVIDER: The lowercase name of the provider (authentik).OIDC_CLIENT_ID: The client ID copied from the Authentik application.OIDC_CLIENT_SECRET: The client secret copied from the Authentik application.OIDC_REDIRECT_URI: The redirect URI configured in the Authentik provider, in the format http://romm.host.local/api/oauth/openid.OIDC_SERVER_APPLICATION_URL: The URL of the Authentik application, e.g., http://authentik.host.local/application/o/romm.In RomM, open your user profile and set your email address. This email has to match your user email in Authentik.
"},{"location":"OIDC-Guides/OIDC-Setup-With-Authentik/#step-6-test-the-integration","title":"Step 6: Test the Integration","text":"After configuring the environment variables, restart (or stop and remove) your RomM instance and navigate to the login page. You should see an option to log in using OIDC. Click on the OIDC button, and you'll be redirected to Authentik for authentication. Once authenticated, you'll be redirected back to RomM.
"},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/","title":"OIDC Setup With PocketID","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#oidc-setup-with-pocket-id","title":"OIDC Setup With Pocket ID","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#a-quick-rundown-of-the-technologies","title":"A quick rundown of the technologies","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#what-is-pocket-id","title":"What is Pocket ID?","text":"Pocket ID is a simple OIDC provider that allows users to authenticate with their passkeys to your services.
The goal of Pocket ID is to be a simple and easy-to-use. There are other self-hosted OIDC providers like Keycloak or ORY Hydra but they are often too complex for simple use cases.
Additionally, what makes Pocket ID special is that it only supports passkey authentication, which means you don\u2019t need a password.
"},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#what-is-oauth2","title":"What is OAuth2?","text":"OAuth2 (Open Authorization 2.0) is an industry-standard protocol for authorization. It allows applications (clients) to gain limited access to user accounts on an HTTP service without sharing the user\u2019s credentials. Instead, it uses access tokens to facilitate secure interactions. OAuth2 is commonly used in scenarios where users need to authenticate via a third-party service.
"},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#what-is-openid-connect-oidc","title":"What is OpenID Connect (OIDC)?","text":"OIDC (OpenID Connect) is an identity layer built on top of OAuth2. While OAuth2 primarily handles authorization, OIDC adds authentication, enabling applications to verify a user\u2019s identity and obtain profile information. This makes OIDC suitable for SSO solutions, where user identity is central to access management.
"},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#setting-up-a-client-in-pocket-id","title":"Setting up a client in Pocket ID","text":""},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#step-1-install-and-configure-pocket-id","title":"Step 1: Install and Configure Pocket ID","text":"Before setting up the OIDC client, ensure that Pocket ID is installed and running by following the setup guide.
"},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#step-2-add-a-client","title":"Step 2: Add a client","text":"Once you have logged in and configured a PassKey you now need to create an OIDC client, this will let Pocket ID know about the application that needs to be configured, and will give you the relevant keys to add to the RomM compose file.
https://{host}/api/oauth/openidTo enable OIDC authentication in RomM, you need to set the following environment variables:
OIDC_ENABLED: Set to true to enable OIDC authentication.OIDC_PROVIDER: The lowercase name of the provider (pocketid).OIDC_CLIENT_ID: The client ID copied from the Pocket ID applicationOIDC_CLIENT_SECRET: The client secret that is showing within your Pocket ID application.OIDC_REDIRECT_URI: The redirect URI configured in the Pocket ID provider, in the format https://{host}/api/oauth/openid.OIDC_SERVER_APPLICATION_URL: The authorization URL for you Pocket ID instance, e.g. https://id.host.local/authorize.In RomM, open your user profile and set your email address. This email has to match your user email in Pocket ID.
"},{"location":"OIDC-Guides/OIDC-Setup-With-PocketID/#step-5-test-the-integration","title":"Step 5: Test the Integration","text":"After configuring the environment variables, restart (or stop and remove) your RomM instance and navigate to the login page. You should see an option to log in using OIDC. Click on the OIDC button, and you'll be redirected to Pocket ID for authentication. Once authenticated, you'll be redirected back to RomM.
"},{"location":"Platforms-and-Players/Custom-Platforms/","title":"Custom Platforms","text":"While RomM supports every platform listed in the Supported Platforms page, the list is not exhaustive, and you may have ROMs in your library for other platforms. To load those files into RomM, place them in a folder for each platform, and give it a name that's all lowercase, with - to separate words, and with no white spaces. For example, pocket-challenge-v2 would map to Pocket Challenge V2, and display the default platform icon in the app.
Furthermore, only a portion of the supported platforms have custom icons built-in. If your library has platforms that aren't listed in the platforms icons list, RomM will display a default fallback icon.
If you'd like to load your own custom icons for missing platforms, you can mount /var/www/html/assets/platforms to some local folder and place all of your custom .ico platform icons in there. You'll also want to download the ones provided in this project and place them in the same folder. If you'd like to use your own icons for platforms already supported by RomM, just replace the file with another using the exact same name.
The name of the .ico file should match the slug of the platform on IGDB. For example, the URL for the AmstradCPC is https://www.igdb.com/platforms/acpc, so the filename should be acpc.ico.
EmulatorJS is a web-based emulator for various system; that is, it allows you to run old games in your web browser. It's based on Emscripten, which is a toolchain for compiling C and C++ code to WebAssembly.
Warning
Due to a change by Apple in iOS 18.2, emulation is severely limited, and likely non-functional, on iOS devices.
Warning
PSP emulation with the PPSSPP core requires special setup with a reverse proxy, or launching Chrome browser with the --disable-web-security and --enable-features=SharedArrayBuffer flags, which WE STRONGLY DISCOURAGE as it disables important security features.
Warning
Emulation is a complex and resource-intensive process. As such, it may not work well in all browser, especially older or less powerful ones. If you're having trouble running a game, try using a different browser or device.
"},{"location":"Platforms-and-Players/EmulatorJS-Player/#loading-saves-and-states","title":"Loading saves and states","text":"Our integration with EmulatorJS automates the process of loading and saving save files and save states. Before starting the game, select a save and/or state file to load (if one is available). Anytime you save the game (or create a save state), the save and state files stored with RomM will be updated, so there's no need to manually download or upload them.
"},{"location":"Platforms-and-Players/EmulatorJS-Player/#supported-systems","title":"Supported systems","text":"Note that only the following systems are currently supported:
Ruffle is a web-based player for flash games. With flash now discontinued, this is the best way to play your flash collection in the browser.
Important
Ruffle will only play games stored in platform folders called flash or browser.
Below is a list of all supported platforms/systems/consoles and their respective folder names. The folder name is case-sensitive and must be used exactly as it appears in the list below.
Platform Name Folder Name IGDB MobyGames 1292 Advanced Programmable Video System1292-advanced-programmable-video-system IGDB MobyGames 3DO Interactive Multiplayer 3do IGDB MobyGames ABC 80 abc-80 MobyGames APF MP1000/Imagination Machine apf MobyGames AY-3-8500 ay-3-8500 IGDB AY-3-8603 ay-3-8603 IGDB AY-3-8605 ay-3-8605 IGDB AY-3-8606 ay-3-8606 IGDB AY-3-8607 ay-3-8607 IGDB AY-3-8610 ay-3-8610 IGDB AY-3-8710 ay-3-8710 IGDB AY-3-8760 ay-3-8760 IGDB Acorn Archimedes acorn-archimedes IGDB MobyGames Acorn Electron acorn-electron IGDB MobyGames Adventure Vision adventure-vision MobyGames AirConsole airconsole IGDB MobyGames Alice 32/90 alice-3290 MobyGames Altair 680 altair-680 MobyGames Altair 8800 altair-8800 MobyGames Amazon Alexa amazon-alexa MobyGames Amazon Fire TV amazon-fire-tv IGDB MobyGames Amiga amiga IGDB MobyGames Amiga CD32 amiga-cd32 IGDB MobyGames Amstrad CPC acpc IGDB MobyGames Amstrad PCW amstrad-pcw IGDB MobyGames Android android IGDB MobyGames Antstream antstream MobyGames Apple I apple-i MobyGames Apple II appleii IGDB MobyGames Apple IIGD apple2gs MobyGames Apple IIGS apple-iigs IGDB MobyGames Apple Pippin apple-pippin IGDB Arcade arcade IGDB MobyGames Arcadia 2001 arcadia-2001 IGDB MobyGames Arduboy arduboy IGDB MobyGames Astral 2000 astral-2000 MobyGames Atari 2600 atari2600 IGDB MobyGames Atari 5200 atari5200 IGDB MobyGames Atari 7800 atari7800 IGDB MobyGames Atari 8-bit atari8bit IGDB MobyGames Atari Jaguar jaguar IGDB MobyGames Atari Jaguar CD atari-jaguar-cd IGDB Atari Lynx lynx IGDB MobyGames Atari ST/STE atari-st IGDB MobyGames Atari VCS atari-vcs MobyGames Atom atom MobyGames BBC Micro bbcmicro MobyGames BBC Microcomputer System bbcmicro IGDB MobyGames BREW brew MobyGames Bally Astrocade astrocade IGDB MobyGames BeOS beos MobyGames BlackBerry OS blackberry IGDB MobyGames Blacknut blacknut MobyGames Blu-ray Player blu-ray-player IGDB MobyGames Bubble bubble MobyGames CD-i philips-cd-i MobyGames CDC Cyber 70 cdccyber70 IGDB CDTV commodore-cdtv MobyGames COSMAC fred-cosmac MobyGames CP/M cpm MobyGames Call-A-Computer time-shared mainframe computer system call-a-computer IGDB Camputers Lynx camputers-lynx MobyGames Casio Loopy casio-loopy IGDB MobyGames Casio PV-1000 casio-pv-1000 MobyGames Casio Programmable Calculator casio-programmable-calculator MobyGames Champion 2711 champion-2711 MobyGames Channel F fairchild-channel-f MobyGames ClickStart clickstart MobyGames Coleco Adam colecoadam MobyGames ColecoVision colecovision IGDB MobyGames Colour Genie colour-genie MobyGames Commodore 128 c128 MobyGames Commodore 16 c16 IGDB MobyGames Commodore C64/128/MAX c64 IGDB MobyGames Commodore CDTV commodore-cdtv IGDB MobyGames Commodore PET cpet IGDB MobyGames Commodore PET/CBM cpet MobyGames Commodore Plus/4 c-plus-4 IGDB MobyGames Commodore VIC-20 vic-20 IGDB MobyGames Compal 80 compal-80 MobyGames Compucolor I compucolor-i MobyGames Compucolor II compucolor-ii MobyGames Compucorp Programmable Calculator compucorp-programmable-calculator MobyGames CreatiVision creativision MobyGames Cybervision cybervision MobyGames DOS dos IGDB MobyGames DVD Player dvd-player IGDB MobyGames Danger OS danger-os MobyGames Dedicated console dedicated-console MobyGames Dedicated handheld dedicated-handheld MobyGames Didj didj MobyGames DoJa doja MobyGames Donner Model 30 donner30 IGDB Dragon 32/64 dragon-32-slash-64 IGDB MobyGames Dreamcast dc IGDB MobyGames ECD Micromind ecd-micromind MobyGames EDSAC edsac--1 IGDB Electron acorn-electron MobyGames Enterprise enterprise MobyGames Epoch Cassette Vision epoch-cassette-vision IGDB MobyGames Epoch Game Pocket Computer epoch-game-pocket-computer MobyGames Epoch Super Cassette Vision epoch-super-cassette-vision IGDB MobyGames Evercade evercade IGDB MobyGames ExEn exen MobyGames Exelvision exelvision MobyGames Exidy Sorcerer exidy-sorcerer IGDB MobyGames FM Towns fm-towns IGDB MobyGames FM-7 fm-7 IGDB MobyGames Fairchild Channel F fairchild-channel-f IGDB MobyGames Family Computer famicom IGDB Family Computer Disk System fds IGDB Feature phone mobile-custom MobyGames Ferranti Nimrod Computer nimrod IGDB Fire TV amazon-fire-tv MobyGames Freebox freebox MobyGames G-cluster g-cluster MobyGames GIMINI gimini MobyGames GNEX gnex MobyGames GP2X gp2x MobyGames GP2X Wiz gp2x-wiz MobyGames GP32 gp32 MobyGames GVM gvm MobyGames Galaksija galaksija MobyGames Gamate gamate IGDB Game & Watch g-and-w IGDB Game Boy gb IGDB MobyGames Game Boy Advance gba IGDB MobyGames Game Boy Color gbc IGDB MobyGames Game Gear gamegear MobyGames Game Wave game-wave MobyGames Game.Com game-dot-com MobyGames Game.com game-dot-com IGDB MobyGames GameStick gamestick MobyGames Gear VR gear-vr IGDB Genesis/Mega Drive genesis-slash-megadrive MobyGames Gizmondo gizmondo IGDB MobyGames Gloud gloud MobyGames Glulx glulx MobyGames Google Stadia stadia IGDB MobyGames HD DVD Player hd-dvd-player MobyGames HP 2100 hp2100 IGDB HP 3000 hp3000 IGDB HP 9800 hp-9800 MobyGames HP Programmable Calculator hp-programmable-calculator MobyGames Handheld Electronic LCD handheld-electronic-lcd IGDB Heath/Zenith H8/H89 heathzenith MobyGames Heathkit H11 heathkit-h11 MobyGames Hitachi S1 hitachi-s1 MobyGames Hugo hugo MobyGames Hyper Neo Geo 64 hyper-neo-geo-64 IGDB HyperScan hyperscan IGDB MobyGames IBM 5100 ibm-5100 MobyGames Ideal-Computer ideal-computer MobyGames Intel 8008 intel-8008 MobyGames Intel 8080 intel-8080 MobyGames Intel 8086 / 8088 intel-8086 MobyGames Intellivision intellivision IGDB MobyGames Intellivision Amico intellivision-amico IGDB Interact Model One interact-model-one MobyGames Interton Video 2000 interton-video-2000 MobyGames Interton VC 4000 vc-4000 IGDB J2ME j2me MobyGames Jolt jolt MobyGames Jupiter Ace jupiter-ace MobyGames KIM-1 kim-1 MobyGames KaiOS kaios MobyGames Kindle Classic kindle MobyGames Laser 200 laser200 MobyGames LaserActive laseractive MobyGames LeapTV leaptv IGDB MobyGames Leapster leapster IGDB MobyGames Leapster Explorer/LeadPad Explorer leapster-explorer-slash-leadpad-explorer IGDB MobyGames Leapster Explorer/LeapPad Explorer leapster-explorer-slash-leadpad-explorer MobyGames Legacy Computer legacy-computer IGDB Legacy Mobile Device mobile IGDB Linux linux IGDB MobyGames Luna luna MobyGames MOS Technology 6502 mos-technology-6502 MobyGames MRE mre MobyGames MSX msx IGDB MobyGames MSX2 msx2 IGDB Mac mac IGDB MobyGames Macintosh mac MobyGames Maemo maemo MobyGames Mainframe mainframe MobyGames Matsushita/Panasonic JR matsushitapanasonic-jr MobyGames Mattel Aquarius mattel-aquarius MobyGames MeeGo meego MobyGames Mega Duck/Cougar Boy mega-duck-slash-cougar-boy IGDB Memotech MTX memotech-mtx MobyGames Meritum meritum MobyGames Meta Quest 2 meta-quest-2 IGDB Meta Quest 3 meta-quest-3 IGDB Microbee microbee MobyGames Microtan 65 microtan-65 MobyGames Microvision microvision--1 IGDB MobyGames Mophun mophun MobyGames Motorola 6800 motorola-6800 MobyGames Motorola 68k motorola-68k MobyGames N-Gage ngage IGDB MobyGames N-Gage (service) ngage2 MobyGames NEC PC-6000 Series nec-pc-6000-series IGDB Nascom nascom MobyGames Neo Geo neogeoaes MobyGames Neo Geo AES neogeoaes IGDB MobyGames Neo Geo CD neo-geo-cd IGDB MobyGames Neo Geo MVS neogeomvs IGDB MobyGames Neo Geo Pocket neo-geo-pocket IGDB MobyGames Neo Geo Pocket Color neo-geo-pocket-color IGDB MobyGames Neo Geo X neo-geo-x MobyGames New Nintendo 3DS new-nintendo-3ds IGDB MobyGames NewBrain newbrain MobyGames Newton newton MobyGames Nintendo 3DS 3ds IGDB MobyGames Nintendo 64 n64 IGDB MobyGames Nintendo 64DD nintendo-64dd IGDB Nintendo DS nds IGDB MobyGames Nintendo DSi nintendo-dsi IGDB MobyGames Nintendo Entertainment System nes IGDB MobyGames Nintendo GameCube ngc IGDB MobyGames Nintendo PlayStation nintendo-playstation IGDB Nintendo Switch switch IGDB MobyGames North Star northstar MobyGames Noval 760 noval-760 MobyGames Nuon nuon IGDB MobyGames OOParts ooparts IGDB MobyGames OS/2 os2 MobyGames Oculus Go oculus-go IGDB MobyGames Oculus Quest oculus-quest IGDB MobyGames Oculus Rift oculus-rift IGDB Odyssey odyssey--1 IGDB MobyGames Odyssey 2/Videopac G7000 odyssey-2-slash-videopac-g7000 IGDB MobyGames Ohio Scientific ohio-scientific MobyGames OnLive Game System onlive-game-system IGDB MobyGames Orao orao MobyGames Oric oric MobyGames Ouya ouya IGDB MobyGames PC (Microsoft Windows) win IGDB MobyGames PC Booter pc-booter MobyGames PC Engine SuperGrafx supergrafx IGDB MobyGames PC-50X Family pc-50x-family IGDB PC-6001 pc-6001 MobyGames PC-8000 pc-8000 MobyGames PC-8800 Series pc-8800-series IGDB MobyGames PC-9800 Series pc-9800-series IGDB MobyGames PC-FX pc-fx IGDB MobyGames PDP-1 pdp1 IGDB PDP-10 pdp10 IGDB PDP-11 pdp11 IGDB PDP-8 pdp-8--1 IGDB PICO pico MobyGames PLATO plato--1 IGDB PS Vita psvita MobyGames Palm OS palm-os IGDB MobyGames Panasonic Jungle panasonic-jungle IGDB Panasonic M2 panasonic-m2 IGDB Pandora pandora MobyGames Pebble pebble MobyGames Philips CD-i philips-cd-i IGDB MobyGames Philips VG 5000 philips-vg-5000 MobyGames Photo CD photocd MobyGames Pippin pippin MobyGames PlayStation ps IGDB MobyGames PlayStation 2 ps2 IGDB MobyGames PlayStation 3 ps3 IGDB MobyGames PlayStation 4 ps4--1 IGDB MobyGames PlayStation 5 ps5 IGDB MobyGames PlayStation Now playstation-now MobyGames PlayStation Portable psp IGDB MobyGames PlayStation VR psvr IGDB PlayStation VR2 psvr2 IGDB PlayStation Vita psvita IGDB MobyGames Playdate playdate IGDB MobyGames Playdia playdia IGDB MobyGames Plex Arcade plex-arcade MobyGames Plug & Play plug-and-play IGDB PocketStation pocketstation IGDB Pokitto pokitto MobyGames Pok\u00e9mon mini pokemon-mini IGDB MobyGames Poly-88 poly-88 MobyGames R-Zone r-zone IGDB RCA Studio II rca-studio-ii MobyGames Research Machines 380Z research-machines-380z MobyGames Roku roku MobyGames SAM Coup\u00e9 sam-coupe MobyGames SC/MP scmp MobyGames SD-200/270/290 sd-200270290 MobyGames SDS Sigma 7 sdssigma7 IGDB SEGA 32X sega-32x MobyGames SEGA CD segacd MobyGames SEGA Master System sega-master-system MobyGames SEGA Saturn saturn MobyGames SG-1000 sg1000 IGDB SK-VM sk-vm MobyGames SMC-777 smc-777 MobyGames SRI-500/1000 sri-5001000 MobyGames SWTPC 6800 swtpc-6800 MobyGames Satellaview satellaview IGDB Sega 32X sega32 IGDB MobyGames Sega CD segacd IGDB MobyGames Sega Game Gear gamegear IGDB MobyGames Sega Master System/Mark III sms IGDB Sega Mega Drive/Genesis genesis-slash-megadrive IGDB MobyGames Sega Pico sega-pico IGDB MobyGames Sega Saturn saturn IGDB MobyGames Sharp MZ-2200 sharp-mz-2200 IGDB Sharp MZ-80B/2000/2500 sharp-mz-80b20002500 MobyGames Sharp MZ-80K/700/800/1500 sharp-mz-80k7008001500 MobyGames Sharp X1 x1 IGDB MobyGames Sharp X68000 sharp-x68000 IGDB MobyGames Sharp Zaurus sharp-zaurus MobyGames Signetics 2650 signetics-2650 MobyGames Sinclair QL sinclair-ql IGDB MobyGames Sinclair ZX81 sinclair-zx81 IGDB MobyGames Socrates socrates MobyGames Sol-20 sol-20 IGDB MobyGames Sord M5 sord-m5 MobyGames Spectravideo spectravideo MobyGames Super A'can super-acan MobyGames Super Famicom sfam IGDB Super Nintendo Entertainment System snes IGDB MobyGames Super Vision 8000 super-vision-8000 MobyGames Supervision supervision MobyGames Sure Shot HD sure-shot-hd MobyGames SwanCrystal swancrystal IGDB Symbian symbian MobyGames TADS tads MobyGames TI Programmable Calculator ti-programmable-calculator MobyGames TI-99/4A ti-994a MobyGames TIM tim MobyGames TRS-80 trs-80 IGDB MobyGames TRS-80 Color Computer trs-80-color-computer IGDB MobyGames TRS-80 MC-10 trs-80-mc-10 MobyGames TRS-80 Model 100 trs-80-model-100 MobyGames Taito X-55 taito-x-55 MobyGames Tapwave Zodiac zod IGDB Tatung Einstein tatung-einstein IGDB MobyGames Tektronix 4050 tektronix-4050 MobyGames Tele-Spiel ES-2201 tele-spiel MobyGames Telstar Arcade telstar-arcade MobyGames Terebikko / See 'n Say Video Phone terebikko-slash-see-n-say-video-phone IGDB Terminal terminal MobyGames Texas Instruments TI-99 ti-99 IGDB MobyGames Thomson MO5 thomson-mo5 IGDB MobyGames Thomson TO thomson-to MobyGames Tiki 100 tiki-100 MobyGames Timex Sinclair 2068 timex-sinclair-2068 MobyGames Tizen tizen MobyGames Tomahawk F1 tomahawk-f1 MobyGames Tomy Tutor tomy-tutor MobyGames Triton triton MobyGames TurboGrafx CD turbografx-16-slash-pc-engine-cd MobyGames TurboGrafx-16 turbografx16--1 MobyGames TurboGrafx-16/PC Engine turbografx16--1 IGDB MobyGames Turbografx-16/PC Engine CD turbografx-16-slash-pc-engine-cd IGDB MobyGames V.Flash vflash MobyGames V.Smile vsmile IGDB MobyGames VIS vis MobyGames Vectrex vectrex IGDB MobyGames Versatile versatile MobyGames VideoBrain videobrain MobyGames Videopac+ G7400 videopac-g7400 MobyGames Virtual Boy virtualboy IGDB MobyGames Virtual Console vc IGDB Visual Memory Unit / Visual Memory System visual-memory-unit-slash-visual-memory-system IGDB WIPI wipi MobyGames Wang 2200 wang2200 MobyGames Watara/QuickShot Supervision watara-slash-quickshot-supervision IGDB Web browser browser IGDB MobyGames Wii wii IGDB MobyGames Wii U wiiu IGDB MobyGames Windows win MobyGames Windows 3.x win3x MobyGames Windows Apps windows-apps MobyGames Windows Mobile windows-mobile IGDB MobyGames Windows Phone winphone IGDB MobyGames WonderSwan wonderswan IGDB MobyGames WonderSwan Color wonderswan-color IGDB MobyGames XaviXPORT xavixport MobyGames Xbox xbox IGDB MobyGames Xbox 360 xbox360 IGDB MobyGames Xbox Cloud Gaming xboxcloudgaming MobyGames Xbox One xboxone IGDB MobyGames Xbox Series X series-x IGDB MobyGames Xerox Alto xerox-alto MobyGames Z-machine z-machine MobyGames ZX Spectrum zxs IGDB ZX Spectrum Next zx-spectrum-next MobyGames ZX80 zx80 MobyGames ZX81 sinclair-zx81 MobyGames Zeebo zeebo IGDB MobyGames Zilog Z80 z80 MobyGames Zilog Z8000 zilog-z8000 MobyGames Zodiac zodiac MobyGames Zune zune MobyGames bada bada MobyGames digiBlast digiblast MobyGames iOS ios IGDB MobyGames iPad ipad MobyGames iPod Classic ipod-classic MobyGames iiRcade iircade MobyGames tvOS tvos MobyGames visionOS visionos IGDB watchOS watchos MobyGames webOS webos MobyGames"},{"location":"System-Setup/Synology-Setup-Guide/","title":"Synology Setup","text":""},{"location":"System-Setup/Synology-Setup-Guide/#prerequisites","title":"Prerequisites","text":"This guide assumes you're familiar with Docker and have basic knowledge of server management. You'll need:
Create the following directory structure for game assets and configuration:
mkdir -p /volume1/data/media/games/assets\nmkdir -p /volume1/data/media/games/config\nRomM requires a very specific folder structure for rom files:
mkdir -p /volume1/data/media/games/library/roms\nmkdir -p /volume1/data/media/games/library/bios\nNote: For supported platforms and their specific folder names, refer to the official RomM wiki.
"},{"location":"System-Setup/Synology-Setup-Guide/#docker-data-folders","title":"Docker Data Folders","text":"Create these folders for project and container data:
mkdir -p /volume1/docker/romm-project/\nmkdir -p /volume1/docker/romm/resources\nmkdir -p /volume1/docker/romm/redis-data\nmkdir -p /volume1/docker/mariadb-romm\nCreate a new network bridge named rommbridge following standard Docker networking practices. You can use this guide for reference.
Generate your authentication key using:
openssl rand -hex 32\n> 03a054b6ca27e0107c5eed552ea66bacd9f3a2a8a91e7595cd462a593f9ecd09\nSave the output - you'll need it for the ROMM_AUTH_SECRET_KEY in your configuration.
RomM currently supports 3 metadata sources: IGDB, MobyGames and SteamGridDB. Follow the dedicated wiki page for API key generation to set up your API keys. We recommend setting up IGDG at the minimum.
"},{"location":"System-Setup/Synology-Setup-Guide/#4-mariadb-configuration","title":"4. MariaDB Configuration","text":"Important
Create a docker-compose.yml file with the following content:
version: \"3\"\n\nvolumes:\n mysql_data:\n\nservices:\n romm:\n image: rommapp/romm:latest\n container_name: romm\n restart: unless-stopped\n environment:\n - DB_HOST=romm-db\n - DB_NAME=romm # Should match MARIADB_DATABASE in mariadb\n - DB_USER=romm-user # Should match MARIADB_USER in mariadb\n - DB_PASSWD= # Should match MARIADB_PASSWORD in mariadb\n - ROMM_AUTH_SECRET_KEY= # Generate a key with `openssl rand -hex 32`\n - IGDB_CLIENT_ID= # Generate an ID and SECRET in IGDB\n - IGDB_CLIENT_SECRET= # https://api-docs.igdb.com/#account-creation\n - MOBYGAMES_API_KEY= # https://www.mobygames.com/info/api/\n - STEAMGRIDDB_API_KEY= # https://github.com/rommapp/romm/wiki/Generate-API-Keys#steamgriddb\n volumes:\n - /volume1/docker/romm/resources:/romm/resources\n - /volume1/docker/romm/redis-data:/redis-data\n - /volume1/data/media/games/library:/romm/library\n - /volume1/data/media/games/assets:/romm/assets\n - /volume1/data/media/games/config:/romm/config\n ports:\n - 7676:8080\n network_mode: rommbridge\n depends_on:\n romm-db:\n condition: service_healthy\n restart: true\n\n mariadb-romm:\n image: mariadb:latest\n container_name: mariadb-romm\n restart: unless-stopped\n environment:\n - MARIADB_ROOT_PASSWORD= # Use a unique, secure password\n - MARIADB_DATABASE=romm\n - MARIADB_USER=romm-user\n - MARIADB_PASSWORD=\n ports:\n - 3309:3306\n network_mode: rommbridge\n volumes:\n - /volume1/docker/mariadb-romm:/var/lib/mysql\n healthcheck:\n test: [\"CMD\", \"healthcheck.sh\", \"--connect\", \"--innodb_initialized\"]\n start_period: 30s\n start_interval: 10s\n interval: 10s\n timeout: 5s\n retries: 5\nhttp://your-server-ip:7676Important
This guide is an abridged version of ChopFoo's original guide. If you have any suggestions or improvements, please submit a pull request to the RomM wiki.
"},{"location":"System-Setup/Tinfoil-Integration/","title":"Tinfoil Integration","text":"This will help you configure the Tinfoil integration for your Switch to work with your RomM library.
"},{"location":"System-Setup/Tinfoil-Integration/#prepare","title":"Prepare","text":"Please note down the following in order to make this as smooth as possible, as well as some pre-reqs:
DISABLE_DOWNLOAD_ENDPOINT_AUTH=true to your environment variables and restart the containerhttp or https/api/tinfoil/feedNow it's time to configure your switch - Please follow the steps, this will assume you have Tinfoil installed and know how to use the basic functions of it.
http or https depending on your connectionmotd: \" RomM Switch Library\"Now you will be able to see the files in \"New Games\" tab of Tinfoil OR you can access it within the \"File Browser\" section that you setup earlier.
"},{"location":"System-Setup/Tinfoil-Integration/#additional","title":"Additional","text":"It didn't pull anything through to \"New Games\" and has not parsed any information about the titles?!
That would be because the filename it has tried to pull had no TitleID (Improvement to RomM coming soon )
Make sure the filename has the TitleID within the title like this:
Once this is done, the next time Tinfoil is opened it is always parsed and re-scanned.
"},{"location":"System-Setup/TrueNAS-Setup-Guide/","title":"TrueNAS Setup","text":""},{"location":"System-Setup/TrueNAS-Setup-Guide/#prerequisites","title":"Prerequisites","text":"This guide assumes you're familiar with Docker and have basic knowledge of TrueNAS. You'll need:
Navigate to the App Catalog via Apps (Left navigation bar) -> Discover Apps -> RomM -> Install
"},{"location":"System-Setup/TrueNAS-Setup-Guide/#step-2-installation-configuration","title":"Step 2: Installation configuration","text":"Step through the installation UI. You will need to supply various credentials per the Quick Start Guide. Most of the default values will work.
Note: You will likely want to set certain Storage Configurations to a Dataset within TrueNAS, such as your RomM Library and Assets storage. If you do this, ensure you provide ACL access to the UserID specified above (default: 568, apps user).
"},{"location":"System-Setup/TrueNAS-Setup-Guide/#step-3-save-your-configuration","title":"Step 3: Save your configuration","text":"Save, and you're done! If the app will not boot, refer to Troubleshooting or head on over to the Discord.
"},{"location":"System-Setup/TrueNAS-Setup-Guide/#install-via-yaml","title":"Install via YAML","text":"This installation path should only be used in the event that there is a bug with installing through the App Catalog, or you wish to have more flexibility than is provided by the installation UI.
"},{"location":"System-Setup/TrueNAS-Setup-Guide/#step-1-navigate-to-yaml-install","title":"Step 1: Navigate to YAML install","text":"Navigate to the Install via YAML page via Apps (Left navigation bar) -> Discover Apps -> Install via YAML
Replace any empty values with credentials you've created per the Quick Start Guide.
Example Docker Composeversion: \"3\"\n\nvolumes:\n mysql_data:\n romm_redis_data:\n\nservices:\n romm:\n image: rommapp/romm:latest\n container_name: romm\n restart: unless-stopped\n user: 568:568\n environment:\n - DB_HOST=romm-db\n - DB_NAME=romm # Should match MARIADB_DATABASE in mariadb\n - DB_USER=romm-user # Should match MARIADB_USER in mariadb\n - DB_PASSWD= # Should match MARIADB_PASSWORD in mariadb\n - ROMM_AUTH_SECRET_KEY= # Generate a key with `openssl rand -hex 32`\n - IGDB_CLIENT_ID= # Generate an ID and SECRET in IGDB\n - IGDB_CLIENT_SECRET= # https://api-docs.igdb.com/#account-creation\n - MOBYGAMES_API_KEY= # https://www.mobygames.com/info/api/\n - STEAMGRIDDB_API_KEY= # https://github.com/rommapp/romm/wiki/Generate-API-Keys#steamgriddb\n volumes: # Any /mnt paths may optionally be replaced with a docker volume\n - /mnt/tank/truenas/resources:/romm/resources # Replace /mnt...: file path with your own data structure\n - romm_redis_data:/romm/redis-data # Docker will manage this volume\n - /mnt/tank/truenas/roms:/romm/library # Replace /mnt...: file path with your own data structure\n - /mnt/tank/truenas/assets:/romm/assets # Replace /mnt...: file path with your own data structure\n - /mnt/tank/truenas/config:/romm/config # Replace /mnt...: file path with your own data structure\n ports:\n - 31100:8080\n depends_on:\n romm-db:\n condition: service_healthy\n restart: true\n deploy:\n resources:\n limits:\n cpus: \"2.0\"\n memory: 4g\n\n romm-db:\n image: mariadb:latest\n container_name: romm-db\n restart: unless-stopped\n environment:\n - MARIADB_ROOT_PASSWORD= # Use a unique, secure password\n - MARIADB_DATABASE=romm\n - MARIADB_USER=romm-user\n - MARIADB_PASSWORD=\n volumes:\n - mysql_data:/var/lib/mysql\n healthcheck:\n test: [\"CMD\", \"healthcheck.sh\", \"--connect\", \"--innodb_initialized\"]\n start_period: 30s\n start_interval: 10s\n interval: 10s\n timeout: 5s\n retries: 5\nSave, and you're done! If the app will not boot, refer to Troubleshooting or head on over to the Discord.
"},{"location":"System-Setup/TrueNAS-Setup-Guide/#troubleshooting","title":"Troubleshooting","text":""},{"location":"System-Setup/TrueNAS-Setup-Guide/#general","title":"General","text":"If you are encountering permissions issues with folders internal to the docker image (not your TrueNAS dataset), consider temporarily setting the user to root (user: 0). If you do this, it is recommended you fix local file permissions via shell and return access back to a non-root user.
In my particular setup, I had to create a user/group in TrueNAS with uid:gid of 1000:1000 and auxiliary group apps due to hard-coded values in the RomM docker image. This resolved outstanding issues I had with my instance of RomM talking to its Redis instance.
If you have any suggestions or improvements, please submit a pull request to the RomM wiki.
"},{"location":"System-Setup/Unraid-Setup-Guide/","title":"Unraid Setup","text":""},{"location":"System-Setup/Unraid-Setup-Guide/#prerequisites","title":"Prerequisites","text":"Before getting started, install the Community Apps plugin for Unraid.
"},{"location":"System-Setup/Unraid-Setup-Guide/#docker-network","title":"Docker network","text":"You'll want to create a custom bridge-type network for both containers to communicate with each other. This will prevent a number of common issues Unraid users tend to come across during setup. This can be done with the following command: docker network create romm, and you can verify it worked with docker network ls.
MariaDB is required to run RomM, so install it from the plugin registry. Only the official and linuxserver versions are supported, but the official version is preferred.
Now fill in all the environment variables; descriptions of the options and sensible defaults are listed in the example docker-compose.yml file.
Warning
The network type must be set to Custom: romm
From the Unraid dashboard, click APPS in the navigation bar. In the search bar, search for romm, and install the app listed as \"OFFICIAL\". This one is maintained by our team and is the most up-to-date.
Configure the required environment variables, ports and paths as per the example docker-compose.yml file.
Warning
The network type must also be set to Custom: romm
Apply the changes, then head to the DOCKER tab. You should see both containers in a running state, and can access RomM using the IP:PORT of the container (highlighted below).
**It's strongly recommended to backup the appdata folder (or mount it in a safe location) before updating, since tearing down the container will wipe the resources (covers, screenshots, etc.)
DemonWarriorTech has published How to Install RomM on Unraid (Beginner Friendly) on installing and running RomM on Unraid for Beginners with an in depth instructions and explanation of the software install and how to use it.
AlienTech42 has published a great video on installing and running RomM on Unraid. While a bit out of date vis-a-vis install instructions, it's still very useful for general setup and debugging. Check it out!
"},{"location":"System-Setup/Unraid-Setup-Guide/#shout-outs","title":"Shout-outs","text":"We want to give a special shout-out to @Smurre95 and @sfumat0 for their help documenting this process, and working towards getting RomM listed in CA. \ud83e\udd1d
"},{"location":"Tools/Igir-Collection-Manager/","title":"Igir Collection Manager","text":"Igir is a zero-setup ROM collection manager that sorts, filters, extracts or archives, patches, and reports on collections of any size on any OS. It can be used to rename your ROMs to match the RomM database, and to move them into a new directory structure.
"},{"location":"Tools/Igir-Collection-Manager/#setup","title":"Setup","text":""},{"location":"Tools/Igir-Collection-Manager/#directory-structure","title":"Directory structure","text":"The directory structure is important for running the bulk ROM renaming script. Before running the bulk ROM renaming script, set up your directories as follows:
.\n\u251c\u2500\u2500 dats/ # DAT files from no-intro.org\n\u251c\u2500\u2500 roms/ # Original ROM collection\n\u251c\u2500\u2500 roms-unverified/ # Working copy of ROMs\n\u2514\u2500\u2500 igir-romm-cleanup.sh\nCreate a working copy of your ROMs:
cp -r roms/ roms-unverified/\nThis provides a safe working environment and allows for easy script adjustment if needed.
Download DAT Files:
Extract the DAT files to your dats directory. You can optionally extract a subset of the .dat files into the directory instead.
Create the cleanup script igir-romm-cleanup.sh with the contents below:
#!/usr/bin/env bash\nset -ou pipefail\ncd \"$(dirname \"${0}\")\"\n\nINPUT_DIR=roms-unverified\nOUTPUT_DIR=roms-verified\n\n# Documentation: https://igir.io/\n# Uses dat files: https://datomatic.no-intro.org/index.php?page=download&op=daily\ntime npx -y igir@latest \\\n move \\\n extract \\\n report \\\n test \\\n -d dats/ \\\n -i \"${INPUT_DIR}/\" \\\n -o \"${OUTPUT_DIR}/{romm}/\" \\\n --input-checksum-quick false \\\n --input-checksum-min CRC32 \\\n --input-checksum-max SHA256 \\\n --only-retail\nMake the script executable:
chmod a+x igir-romm-cleanup.sh\nRun the script. It will generate a new output directory named roms-verified, moving the files from roms-unverified if its checksum matches any of the known checksums in the DAT files provided. Any ROMs not identified will remain in the roms-unverified directory.
The script may not identify all of the ROMs in your input directory. You can choose to migrate them over manually:
npx -y igir@latest \\\n move \\\n -i roms-unverified/ \\\n -o roms-verified/ \\\n --dir-mirror\nThis will move your ROMs from the input to the output directory, preserving the subdirectory structure. It also cleans up file extensions in the process.
"},{"location":"Tools/Igir-Collection-Manager/#reorganize-multi-disc-games","title":"Reorganize multi-disc games","text":"The Igir script will move games that have multiple discs to separate folders. This can confuse RomM's game detection, and those games need to be reorganized into single folders with many discs.
To do this enter your platform directory, such as ps or psx and run the following:
ls -d *Disc* | while read dir; do\n game=$(echo \"${dir}\" | sed -r 's/ \\(Disc [0-9]+\\)//')\n mkdir -p \"${game}\"\n mv \"${dir}\"/* \"${game}/\"\n rm -rf \"${dir}\"\ndone\nThis will find any directory with (Disc in the name and move the files into a new directory without the (Disc #) string. For example:
Before:
Final Fantasy VII (Disc 1) (USA)\nFinal Fantasy VII (Disc 2) (USA)\nGets combined to:
Final Fantasy VII (USA)\nUse the side-bar to your left for navigation
"},{"location":"Troubleshooting/Authentication-Issues/","title":"Troubleshooting Authentication","text":""},{"location":"Troubleshooting/Authentication-Issues/#error-403-forbidden","title":"Error:403 Forbidden","text":"When authentication is enabled, most endpoints will return a 403 Forbidden response if you're not authenticated, or if your sessions is in a broken state. The session key can be reset by clearing your cookies.
CSRF protection is also enabled, which helps to mitigates CSRF attacks (useful if your instance is public). If you encounter a Forbidden (403) CSRF verification failed error, simply reloading your browser should force it to fetch a fresh CSRF cookie.
Unable to login: CSRF token verification failed","text":"This error is known to happen on Chrome, but could happen in other browsers; manually clear your cookies (specifically one called csrftoken) and hard reload your browser window (CMD+SHIFT+R on macOS, CTRL+F5 on Windows).
400 Bad Request on the Websocket endpoint","text":"If you're running RomM behind a reverse-proxy (Caddy, Nginx, etc.), ensure that Websockets are supported and enabled. This may vary depending on the reverse proxy solution being used. In the case of Nginx Proxy Manager, enable the \"Websockets Support\" toggle when editing the proxy host.
"},{"location":"Troubleshooting/Miscellaneous-Troubleshooting/","title":"Miscellaneous Troubleshooting","text":""},{"location":"Troubleshooting/Miscellaneous-Troubleshooting/#restarting-the-container-when-using-sqlite-drops-all-the-datarequires-a-full-re-scan","title":"Restarting the container when using SQLite drops all the data/requires a full re-scan","text":"Verify that the database is mapped to a persistent storage volume in your docker compose or Unraid template.
\"/path/to/database:/romm/database\" # [Optional] Only needed if ROMM_DB_DRIVER=sqlite or not set\nCould not get twitch auth token: check client_id and client_secret","text":"This is likely due to mis-configured environment variables; verify that CLIENT_ID and CLIENT_SECRET are set correctly, and that both match the values in IGDB.
There are a few common reasons why a scan may end instantly/without scanning platforms
/romm/libraryls -lhromm folder structure","text":"This is the same issue as the one above, and can be quickly solved by verifying your folder structure. RomM expects a library with a folder named roms in it, for example:
/server/media/library:/romm/library/server/media/games/roms:/romm/library/romsWhen scanning the folders mounted in /library/roms, the scanner tries to match the folder name with the platform's slug in IGDB. If you notice that the scanner isn't detecting a platform, verify that the folder name matches the slug in the URL of the platform in IGDB. For example, the Nintendo 64DD has the URL https://www.igdb.com/platforms/nintendo-64dd, so the folder should be named nintendo-64dd.
The background scan task times out after 4 hours, which can happen if you have a very large library. The easiest work around is to keep running scans every 4 hours, without checking the \"Complete re-scan\" option.
"},{"location":"Troubleshooting/Synology-Issues/","title":"Troubleshooting Synology","text":""},{"location":"Troubleshooting/Synology-Issues/#errno-13-access-denied","title":"ErrNo 13: Access Denied","text":"We have noticed recently a spate of access denied on Synology systems via Portainer or even docker manager. The ErrNo13 is directly related to Synology and it is a simple permission issue. To fix it please do the following:
sudo chown -R user:group /path/to/library
sudo chmod -R a=,a+rX,u+w,g+w /path/to/library
sudo chown -R user:group /path/to/assets
sudo chmod -R a=,a+rX,u+w,g+w /path/to/assets
sudo chown -R user:group /path/to/config
sudo chmod -R a=,a+rX,u+w,g+w /path/to/config
You will find the relevant directories in your compose, this is basically the folders where you store your RomM information and we are just resetting permissions. Restart the containers and you should now have no issues scanning information in!
Any issues please ask in the Discord.
Thanks to Docker IDs - DrFrankenstein for the guidance from his blog.
"}]} \ No newline at end of file