Skip to content
Getting startedConfiguration

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:

bash
docker compose up -d

Settings 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 ​

SettingDefaultWhat it does
AUTH_USER / AUTH_PASSretrobiteThe account consoles use for SMB and FTP. Change the password.
DB_PASSWORD / DB_ROOT_PASSWORDretrobiteThe database passwords. Set them before the first start.
GAMES_PATH./gamesWhere your ROM library is on the host.
HOST_IPnoneThis machine's LAN address.
PS3NETSRV_WHITELISTnoneWho may connect to ps3netsrv, such as 192.168.1.*. It has no login, so leave it empty only on a network you trust.
APP_TIMEZONEUTCYour time zone, such as Europe/Stockholm.
WEB_PORT81The host port the web interface answers on.
RETROBITE_TAGdevelopThe 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 ​

SettingDefaultWhat it does
APP_KEYgeneratedEncrypts 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_ENVproductionLeave it as it is. local is for development.
APP_DEBUGfalseShows stack traces and settings in the browser when something fails. Turn it on only to diagnose a problem.
APP_URLhttp://localhost:81The address retroBITE is reached at. Set it behind a reverse proxy.
LOG_LEVELwarningdebug, info, warning or error.
APP_TIMEZONEUTCThe 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 ​

SettingDefaultWhat it does
AUTH_USERretrobiteThe account consoles use for SMB and FTP. One account serves both.
AUTH_PASSretrobiteIts password. Change it.
HOST_IPdetectedThis machine's LAN address, which vsftpd hands to consoles for passive-mode FTP.
GAME_FOLDERSps2 ps3 gc wii xbox dreamcastThe console folders created in the library on start.
SMB_SHARESps2 gc wiiFolders 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.

SettingDefaultWhat it does
PS3NETSRVtrueRuns ps3netsrv. false turns it off.
PS3NETSRV_FOLDERSPS3ISO=ps3 PS2ISO=ps2 PSXISO=psxWhich 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_WHITELISTnoneWho 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 ​

SettingDefaultWhat it does
GAMES_PATH./gamesWhere 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./docsWhere your hardware docs are kept on the host.
DB_PATHvolume retrobite-dbThe database.
MEDIA_PATHvolume retrobite-mediaDownloaded artwork. It can be fetched again.
STATE_PATHvolume retrobite-stateThe 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 ​

SettingDefaultWhat it does
DB_DATABASEretrobiteThe database name.
DB_USERNAMEretrobiteThe database user.
DB_PASSWORDretrobiteThe database user's password.
DB_ROOT_PASSWORDretrobiteMariaDB'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.

SettingDefaultWhat it does
SHARE_IPnoneThe share container's own LAN address. Consoles connect here.
SHARE_SUBNETnoneThe LAN, such as 192.168.1.0/24.
SHARE_GATEWAYnoneThe router, such as 192.168.1.1.
SHARE_PARENTeth0The host's LAN interface.

Reverse proxy ​

SettingDefaultWhat it does
TRUSTED_PROXIESnoneProxies 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 ​

SettingDefaultWhat it does
TRANSFER_LOCALHOST_URLhttp://localhost:81Copying 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_NAMESbatocera,recalbox,retropieHost names to look for when searching the network for shares in Settings → Destinations.
TRANSFER_DISCOVERY_SUBNETSthe HOST_IP networkNetworks 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.

SettingDefaultQueue
QUEUE_WORKERS_SCRAPER1Identification and ratings
QUEUE_WORKERS_MEDIA1Artwork downloads from ScreenScraper
QUEUE_WORKERS_DEFAULT1Scans and file counts
QUEUE_WORKERS_TOOLBOX1Loader exports and license ID reading
QUEUE_WORKERS_CONVERSION1Disc image conversion, one disc at a time
QUEUE_WORKERS_THUMBNAILS1Cover thumbnails
QUEUE_WORKERS_RA1RetroAchievements identification and sets
QUEUE_WORKERS_RA_PROGRESS1RetroAchievements unlocks
QUEUE_WORKERS_HASH1Checksums and RetroAchievements hashes
QUEUE_WORKERS_TRANSFER3Copies 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 ​

SettingDefaultWhat it does
SCREENSCRAPER_DEV_IDbuilt inYour own ScreenScraper developer ID, in place of the one retroBITE ships with. Set both or neither.
SCREENSCRAPER_DEV_PASSWORDbuilt inIts password.
SCREENSCRAPER_CONNECT_TIMEOUT15Seconds to wait for a connection.
SCREENSCRAPER_TIMEOUT90Seconds to wait for an answer.

Your personal ScreenScraper account goes in Settings → ScreenScraper, not in .env.

RetroAchievements ​

SettingDefaultWhat it does
RETROACHIEVEMENTS_CONNECT_TIMEOUT15Seconds to wait for a connection.
RETROACHIEVEMENTS_TIMEOUT180Seconds to wait for an answer.
RA_HASHER_PATH/usr/local/bin/RAHasherThe RAHasher binary in the web image.
RA_HASHER_TIMEOUT1800Seconds 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.

SettingDefaultWhat it does
CONVERSION_CONCURRENCY1Conversions run at once. Raise QUEUE_WORKERS_CONVERSION to match. Past the disk's speed, a second conversion only slows both.
CONVERSION_TIMEOUT7000Seconds one conversion may take, every disc and step included.
CHDMAN_PATH/usr/local/bin/chdmanchdman
MAXCSO_PATH/usr/local/bin/maxcsomaxcso
ECM_PATH / UNECM_PATH/usr/local/bin/ecm, /usr/local/bin/unecmecm and unecm
CUE2POPS_PATH / POPS2CUE_PATH/usr/local/bin/cue2pops, /usr/local/bin/pops2cuecue2pops and pops2cue
NODTOOL_PATH/usr/local/bin/nodtoolnodtool
EXTRACT_XISO_PATH/usr/local/bin/extract-xisoextract-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.

Released under the MIT License.retroBITE