Configuration
retroBITE is configured through environment variables. Set them in a .env file next to your docker-compose.yml, or in your container manager's variables (Portainer, Dockhand, Synology, Unraid, TrueNAS). Installation covers the settings you need for a first start. This page lists them all.
Everything in the first tables reaches the containers through the Compose file, so a variables editor is enough. The rest is read from .env. In a stack without one, add the setting under the service's environment: in the Compose file.
After changing a setting, apply it by recreating the containers:
docker compose up -dSettings left out use the default shown here. At start, the containers write a warning to their log for a default password, debug left on and a missing HOST_IP.
The ones to set
| Setting | Default | What it does |
|---|---|---|
AUTH_USER / AUTH_PASS | retrobite | The account consoles use for SMB and FTP. Change the password. |
DB_PASSWORD / DB_ROOT_PASSWORD | retrobite | The database passwords. Set them before the first start. |
GAMES_PATH | ./games | Where your ROM library is on the host. |
HOST_IP | none | This machine's LAN address. |
PS3NETSRV_WHITELIST | none | Who may connect to ps3netsrv, such as 192.168.1.*. It has no login, so leave it empty only on a network you trust. |
APP_TIMEZONE | UTC | Your time zone, such as Europe/Stockholm. |
WEB_PORT | 81 | The host port the web interface answers on. |
RETROBITE_TAG | develop | The images to run. develop is the newest pre-release, and a version such as 20261006-BETA stays on that version. latest, the newest full release, exists from the first one on. |
App
| Setting | Default | What it does |
|---|---|---|
APP_KEY | generated | Encrypts sessions and the passwords retroBITE stores. When it is empty, a key is generated on the first start and kept in the state volume (STATE_PATH). Set it only to keep a key you already have, such as one an older install had in .env. |
APP_ENV | production | Leave it as it is. local is for development. |
APP_DEBUG | false | Shows stack traces and settings in the browser when something fails. Turn it on only to diagnose a problem. |
APP_URL | http://localhost:81 | The address retroBITE is reached at. Set it behind a reverse proxy. |
LOG_LEVEL | warning | debug, info, warning or error. |
APP_TIMEZONE | UTC | The zone the app tells time in: the dashboard greeting, the times it shows and when the nightly RetroAchievements jobs run. A PHP zone name such as Europe/Stockholm. |
Changing the timezone later
Timestamps are stored in the app's timezone without an offset. Changing APP_TIMEZONE on an install that already has data shifts the dates written before the change.
Network shares
| Setting | Default | What it does |
|---|---|---|
AUTH_USER | retrobite | The account consoles use for SMB and FTP. One account serves both. |
AUTH_PASS | retrobite | Its password. Change it. |
HOST_IP | detected | This machine's LAN address, which vsftpd hands to consoles for passive-mode FTP. |
GAME_FOLDERS | ps2 ps3 gc wii xbox dreamcast | The console folders created in the library on start. |
SMB_SHARES | ps2 gc wii | Folders that also get an SMB share of their own, such as the one Open PS2 Loader connects to. |
Left blank, the share container detects HOST_IP from its default route on every start, which suits a laptop that changes networks. Set it to pin one interface on a machine with several. The web container cannot detect it from Docker's bridge network, so set it if you want the dashboard's SMB, FTP and ps3netsrv status to be accurate.
ps3netsrv
The share container runs ps3netsrv on port 38008, so webMAN MOD on a PS3 with custom firmware lists and plays games straight from the library, without copying them over. In webMAN MOD's setup page, add a network server with this machine's address and port 38008.
| Setting | Default | What it does |
|---|---|---|
PS3NETSRV | true | Runs ps3netsrv. false turns it off. |
PS3NETSRV_FOLDERS | PS3ISO=ps3 PS2ISO=ps2 PSXISO=psx | Which of webMAN MOD's lists ps3netsrv serves, and the library folder behind each. Add PSPISO=psp for PSP games, and list a console folder here if you moved it. Only webMAN's own names (PS3ISO, PS2ISO, PSXISO, PSPISO, BDISO, DVDISO, GAMES, PKG) are taken. |
PS3NETSRV_WHITELIST | none | Who may connect: one address, with * for any part, such as 192.168.1.* or one PS3's address. A range such as 192.168.1.0/24 is not understood, and ps3netsrv then does not start at all (the log says why). |
Set these on both containers, as the Compose file does: the share container runs ps3netsrv from them, and the web container shows its status card, the consoles it serves and who may connect.
No login
ps3netsrv is read-only: webMAN MOD can list and stream, but nothing can be created, changed or deleted through it. It has no username or password, though, so anyone else on the network can read the folders it serves. Set PS3NETSRV_WHITELIST to limit who connects.
webMAN MOD mounts PS1 games as .bin/.cue, .iso or .img, and PS2 games as .iso, not .chd, .cso, .zso or .ecm. Conversion turns those back into ISO or BIN. PS2 games run through the PS3's own PS2 emulation, so compatibility depends on the PS3 model.
Paths
| Setting | Default | What it does |
|---|---|---|
GAMES_PATH | ./games | Where your ROM library is on the host. Mounted into both containers and shared as /games over SMB and FTP, and to webMAN MOD over ps3netsrv. |
DOCS_PATH | ./docs | Where your hardware docs are kept on the host. |
DB_PATH | volume retrobite-db | The database. |
MEDIA_PATH | volume retrobite-media | Downloaded artwork. It can be fetched again. |
STATE_PATH | volume retrobite-state | The application key and the live-update keys. Back it up with the database: the stored passwords cannot be read without the key. |
Point the volumes at folders of your own, such as /volume1/docker/retrobite/db, to keep them with the rest of a NAS's backed-up shares.
Database
| Setting | Default | What it does |
|---|---|---|
DB_DATABASE | retrobite | The database name. |
DB_USERNAME | retrobite | The database user. |
DB_PASSWORD | retrobite | The database user's password. |
DB_ROOT_PASSWORD | retrobite | MariaDB's root password. Only the database container reads it. |
MariaDB sets these when the database is first created. Change them before the first start: editing them afterwards does not change the existing database.
Share on its own address
Only with docker-compose.macvlan.yml. See When ports 445, 139 and 21 are taken.
| Setting | Default | What it does |
|---|---|---|
SHARE_IP | none | The share container's own LAN address. Consoles connect here. |
SHARE_SUBNET | none | The LAN, such as 192.168.1.0/24. |
SHARE_GATEWAY | none | The router, such as 192.168.1.1. |
SHARE_PARENT | eth0 | The host's LAN interface. |
Reverse proxy
| Setting | Default | What it does |
|---|---|---|
TRUSTED_PROXIES | none | Proxies whose X-Forwarded-* headers are trusted, comma-separated, or * for any. |
Set this when retroBITE sits behind a reverse proxy that serves HTTPS. Without it, links come out as http:// and the browser blocks them.
Transfers
| Setting | Default | What it does |
|---|---|---|
TRANSFER_LOCALHOST_URL | http://localhost:81 | Copying to a USB drive or SD card works only on HTTPS or localhost in Chrome and Edge. Pages opened another way link here. The Compose file sets it to the published port. |
TRANSFER_DISCOVERY_NAMES | batocera,recalbox,retropie | Host names to look for when searching the network for shares in Settings → Destinations. |
TRANSFER_DISCOVERY_SUBNETS | the HOST_IP network | Networks to scan for the SMB port, such as 192.168.1.0/24. |
Docker's bridge network blocks mDNS and NetBIOS, so the destination search scans the network HOST_IP is on, or the subnets set here. Copying to a share you add by hand works either way.
Queue workers
Background jobs run on separate queues, each with its own workers. One worker per queue unless set here. 0 starts none.
| Setting | Default | Queue |
|---|---|---|
QUEUE_WORKERS_SCRAPER | 1 | Identification and ratings |
QUEUE_WORKERS_MEDIA | 1 | Artwork downloads from ScreenScraper |
QUEUE_WORKERS_DEFAULT | 1 | Scans and file counts |
QUEUE_WORKERS_TOOLBOX | 1 | Loader exports and license ID reading |
QUEUE_WORKERS_CONVERSION | 1 | Disc image conversion, one disc at a time |
QUEUE_WORKERS_THUMBNAILS | 1 | Cover thumbnails |
QUEUE_WORKERS_RA | 1 | RetroAchievements identification and sets |
QUEUE_WORKERS_RA_PROGRESS | 1 | RetroAchievements unlocks |
QUEUE_WORKERS_HASH | 1 | Checksums and RetroAchievements hashes |
QUEUE_WORKERS_TRANSFER | 3 | Copies to network shares |
Media and hash are the ones worth raising on a machine with room to spare. Scraper workers only add speed up to the number of threads your ScreenScraper account allows: 1 on a free account, 6 on Gold. Settings → ScreenScraper shows yours.
ScreenScraper
| Setting | Default | What it does |
|---|---|---|
SCREENSCRAPER_DEV_ID | built in | Your own ScreenScraper developer ID, in place of the one retroBITE ships with. Set both or neither. |
SCREENSCRAPER_DEV_PASSWORD | built in | Its password. |
SCREENSCRAPER_CONNECT_TIMEOUT | 15 | Seconds to wait for a connection. |
SCREENSCRAPER_TIMEOUT | 90 | Seconds to wait for an answer. |
Your personal ScreenScraper account goes in Settings → ScreenScraper, not in .env.
RetroAchievements
| Setting | Default | What it does |
|---|---|---|
RETROACHIEVEMENTS_CONNECT_TIMEOUT | 15 | Seconds to wait for a connection. |
RETROACHIEVEMENTS_TIMEOUT | 180 | Seconds to wait for an answer. |
RA_HASHER_PATH | /usr/local/bin/RAHasher | The RAHasher binary in the web image. |
RA_HASHER_TIMEOUT | 1800 | Seconds one hash may take. A CHD on a slow disk can take minutes. |
Conversion
The conversion tools ship in the web image. Override a path only to use a different build.
| Setting | Default | What it does |
|---|---|---|
CONVERSION_CONCURRENCY | 1 | Conversions run at once. Raise QUEUE_WORKERS_CONVERSION to match. Past the disk's speed, a second conversion only slows both. |
CONVERSION_TIMEOUT | 7000 | Seconds one conversion may take, every disc and step included. |
CHDMAN_PATH | /usr/local/bin/chdman | chdman |
MAXCSO_PATH | /usr/local/bin/maxcso | maxcso |
ECM_PATH / UNECM_PATH | /usr/local/bin/ecm, /usr/local/bin/unecm | ecm and unecm |
CUE2POPS_PATH / POPS2CUE_PATH | /usr/local/bin/cue2pops, /usr/local/bin/pops2cue | cue2pops and pops2cue |
NODTOOL_PATH | /usr/local/bin/nodtool | nodtool |
EXTRACT_XISO_PATH | /usr/local/bin/extract-xiso | extract-xiso |
Live updates
Pages update live over Laravel Reverb, which runs inside the web container. Its keys are generated on first start and kept in the state volume, so nothing needs filling in. To pin them, set REVERB_APP_ID, REVERB_APP_KEY and REVERB_APP_SECRET.