.env.example

DATABASE_URL=postgresql://username:password@localhost:5432/playmatch
REDIS_URL=redis://localhost:6379

# Metadata providers. Each is optional; comment out to disable a provider.
# Disabling all providers leaves the API live but the background match cron
# becomes a no-op and the corresponding `/api/<provider>/*` routes are not
# registered.
IGDB_CLIENT_ID=YOUR_CLIENT_ID
IGDB_CLIENT_SECRET=YOUR_CLIENT_SECRET
STEAMGRIDDB_API_KEY=YOUR_STEAMGRIDDB_API_KEY
SCREENSCRAPER_DEV_ID=YOUR_SCREENSCRAPER_DEV_ID
SCREENSCRAPER_DEV_PASSWORD=YOUR_SCREENSCRAPER_DEV_PASSWORD
# Optional. Without user credentials ScreenScraper heavily throttles and
# frequently rejects requests with "API closed for non-members" during peak
# hours. Both must be set together to take effect.
# SCREENSCRAPER_USER_ID=YOUR_SCREENSCRAPER_USER_ID
# SCREENSCRAPER_USER_PASSWORD=YOUR_SCREENSCRAPER_USER_PASSWORD
# MobyGames requires a paid subscription. The cheapest tier permits one
# request every five seconds; higher tiers raise the budget. Without this
# key the MobyGames provider is disabled.
MOBYGAMES_API_KEY=YOUR_MOBYGAMES_API_KEY

# LaunchBox is a bulk metadata source. Setting LAUNCHBOX_ENABLED=true enables a
# daily download of the LaunchBox metadata zip (~70 MB) and the import of
# ~700k game records into local Postgres tables. Requires ~700 MB of scratch
# disk space under tmp/launchbox/ during import. Disable on resource-
# constrained deployments.
# LAUNCHBOX_ENABLED=true
# Optional override for the metadata zip URL. Defaults to the upstream URL
# when omitted.
# LAUNCHBOX_METADATA_URL=https://gamesdb.launchbox-app.com/metadata.zip

# EmuReady provides community-driven emulator compatibility data. Set the
# flag below to join EmuReady to the daily match cycle. The provider only
# populates signature_metadata_mapping rows; downstream consumers fetch
# listings via gameId on demand from the EmuReady API. No proxy routes are
# exposed by playmatch for this provider.
# EMUREADY_ENABLED=true

# Hasheous provides hash-based ROM matching against public signature DATs
# (No-Intros, Redump, TOSEC, MAMEArcade, etc.). Set the flag below to join
# Hasheous to the daily match cycle. The hash-lookup endpoints are open and
# require no API key.
# HASHEOUS_ENABLED=true

# OpenVGDB is a bulk metadata source distributed as a small SQLite snapshot
# (~9 MB zip). Setting OPENVGDB_ENABLED=true enables a daily download of the
# OpenVGDB release zip and the import of its ROMs and RELEASES tables into
# local Postgres tables. Matching is hash-first (CRC, MD5, SHA1) against the
# imported tables; no calls leave the box at match time. The dataset is
# updated infrequently upstream, so the md5-skip check normally short-circuits
# subsequent imports at no cost.
# OPENVGDB_ENABLED=true
# Optional override for the release zip URL. Defaults to the GitHub latest
# release asset when omitted.
# OPENVGDB_METADATA_URL=https://github.com/OpenVGDB/OpenVGDB/releases/latest/download/openvgdb.zip

# RetroAchievements requires a username + web API key (free; get one from
# https://retroachievements.org/controlpanel.php). Both must be set together.
# When enabled the provider bulk-imports every RA system, game, and MD5 hash
# once per cycle (one API call per system, ~70 calls total with a 1s courtesy
# delay between calls) and matches local ROMs by MD5 hash first then by name.
# Custom-hash consoles (PS1, GameCube/DS, Dreamcast/Saturn, PCE-CD, 3DO,
# Arcade) only match by name; plain-MD5 consoles match by hash.
# RETROACHIEVEMENTS_USERNAME=YOUR_RA_USERNAME
# RETROACHIEVEMENTS_API_KEY=YOUR_RA_WEB_API_KEY

# TheGamesDB. Match-only provider with no proxy routes. The ~120k row catalogue
# (every game id + canonical title + alternate names) is seeded once via a
# database migration from an upstream CSV export, so no daily bulk import runs.
# TGDB_API_KEY is optional: when set, games not present in the seeded local
# dataset trigger a name search against the TheGamesDB API capped at 30 calls
# per match cycle (~900/month, within the free tier's 1000/month limit). The
# remaining monthly allowance is cached in Redis and recovered via a single
# probe call if Redis loses the value. Without the API key the provider runs
# but only matches against the seeded dataset.
# TGDB_ENABLED=true
# TGDB_API_KEY=YOUR_TGDB_API_KEY

# Pepper used for HMAC-SHA256 hashing of API keys. Generate with `openssl rand -hex 32`.
# Must be at least 16 raw bytes (32 hex chars). Treat like a production secret.
API_KEY_PEPPER=REPLACE_WITH_OUTPUT_OF_openssl_rand_hex_32

INITIAL_DATA_INIT=true