Configuration

retroBITE is configured through the .env file next to your docker-compose.yml. Installation covers the settings you need for a first start. This page lists the rest.

After changing .env, apply it by recreating the containers:

docker compose up -d

Settings that are commented out in .env use the default shown here.

App

Setting	Default	What it does
APP_KEY	none	Encryption key for sessions and stored secrets. Generated during installation. Keep it: changing it signs everyone out.
APP_ENV	local in the example	Set production on a normal install.
APP_DEBUG	true in the example	Set false on a normal install. Debug mode shows stack traces and settings in the browser when something fails.
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.

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 and FTP status to be accurate.

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.
DOCS_PATH	./storage/app/docs	Where your hardware docs are kept on the host. The mount is what keeps them through docker compose down.

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.

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, so nothing needs filling in. To pin them, set REVERB_APP_ID, REVERB_APP_KEY and REVERB_APP_SECRET.