Installation
retroBITE runs in Docker, and Docker is the only supported way to install it. It is a Docker Compose stack of three containers:
| Container | Image | What it does |
|---|---|---|
retrobite-web | retrobite/retrobite | The web interface, queue workers and live updates |
retrobite-share | retrobite/share | Samba (SMBv1 to SMB3), vsftpd FTP and ps3netsrv, serving the library to consoles |
retrobite-db | mariadb:11.4 | The library database |
Both retroBITE images are published to Docker Hub for linux/amd64 and linux/arm64, so they run on an Intel or AMD NAS, a Raspberry Pi 4 or 5 and Apple silicon alike.
You need two files:
docker-compose.yml, the stack. It runs as it is: every setting has a default..env.example, the handful of settings worth changing. Save it as.env, or type the same names into your container manager.
There is no key to generate and nothing to run inside a container. On the first start retroBITE creates its database, makes its own application key and opens a short setup in the browser.
Before the first start
Change AUTH_PASS, DB_PASSWORD and DB_ROOT_PASSWORD, and set GAMES_PATH to your library. The database passwords are read only once, when the database is created.
INFO
For legally made backups of media you own. retroBITE does not endorse piracy.
Linux, from the command line
You need Docker Engine with Compose 2.24 or newer (docker compose version).
mkdir retrobite && cd retrobite
curl -LO https://retrobite.app/docker-compose.yml
curl -L -o .env https://raw.githubusercontent.com/retroBITE-app/retroBITE/develop/.env.example
nano .env # passwords, GAMES_PATH, HOST_IP, APP_TIMEZONE
docker compose up -dOpen http://<HOST_IP>:81 and follow the setup: your account, the interface, ScreenScraper and RetroAchievements. docker compose logs -f retrobite-web shows what it is doing, including a warning for each setting still at its default.
The docker-compose.yml you downloaded:
# retroBITE: save as docker-compose.yml, then docker compose up -d.
#
# Every setting has a default, so this runs as it is. Change them in a .env
# file beside it, or in your container manager's variables: at least
# AUTH_PASS, DB_PASSWORD, DB_ROOT_PASSWORD and GAMES_PATH. The full list is
# at https://retrobite.app/docs/getting-started/configuration
#
# Needs Docker Compose 2.24 or newer. Runs develop, the newest pre-release;
# set RETROBITE_TAG to a version, such as 20261006-BETA, to stay on one.
services:
retrobite-web:
image: retrobite/retrobite:${RETROBITE_TAG:-develop}
container_name: retrobite-web
# Anything not listed under environment below — queue workers,
# ScreenScraper and RetroAchievements timeouts, conversion tools — is read
# from .env when there is one. See the Configuration docs.
env_file:
- path: .env
required: false
environment:
APP_ENV: ${APP_ENV:-production}
APP_DEBUG: ${APP_DEBUG:-false}
APP_URL: ${APP_URL:-http://localhost:${WEB_PORT:-81}}
APP_TIMEZONE: ${APP_TIMEZONE:-UTC}
# Left empty, a key is generated on first start and kept in the state
# volume below. It encrypts the passwords retroBITE stores, so set it
# only to keep one you already have.
APP_KEY: ${APP_KEY:-}
LOG_LEVEL: ${LOG_LEVEL:-warning}
DB_CONNECTION: mariadb
DB_HOST: retrobite-db
DB_PORT: 3306
DB_DATABASE: ${DB_DATABASE:-retrobite}
DB_USERNAME: ${DB_USERNAME:-retrobite}
DB_PASSWORD: ${DB_PASSWORD:-retrobite}
# This machine's LAN address: shown as the address consoles connect to,
# used to check SMB and FTP are up, and the network Settings →
# Destinations searches. The web container is behind Docker's bridge and
# cannot work it out itself.
HOST_IP: ${HOST_IP:-}
# The SMB and FTP account, shown on the Network page.
AUTH_USER: ${AUTH_USER:-retrobite}
# Transfers write to a USB drive from the browser, which Chrome allows
# only on https or localhost; a page opened another way links here.
TRANSFER_LOCALHOST_URL: ${TRANSFER_LOCALHOST_URL:-http://localhost:${WEB_PORT:-81}}
# nginx is in front, so game files and artwork are sent by it rather
# than streamed by PHP (App\Support\NginxFile).
SERVE_WITH_NGINX: "true"
# Whether retrobite-share runs ps3netsrv, what it serves and to whom,
# so its card is shown with the right consoles and says when it is open.
PS3NETSRV: ${PS3NETSRV:-true}
PS3NETSRV_FOLDERS: ${PS3NETSRV_FOLDERS:-PS3ISO=ps3 PS2ISO=ps2 PSXISO=psx}
PS3NETSRV_WHITELIST: ${PS3NETSRV_WHITELIST:-}
ports:
- "${WEB_PORT:-81}:80"
volumes:
# The ROM library, shared with retrobite-share below.
- ${GAMES_PATH:-./games}:/app/storage/app/games
# The markdown knowledge base, a folder beside this file.
- ${DOCS_PATH:-./docs}:/app/storage/app/docs
# Artwork retroBITE downloads itself, kept out of the games tree so a
# console browsing the share never sees it.
- ${MEDIA_PATH:-retrobite-media}:/app/storage/app/media
# The application key and Reverb's keys. Back it up with the database.
- ${STATE_PATH:-retrobite-state}:/app/storage/state
depends_on:
retrobite-db:
condition: service_healthy
restart: unless-stopped
retrobite-db:
image: mariadb:11.4
container_name: retrobite-mariadb
environment:
# Read once, when the database is first created: change them before the
# first start, or change them inside MariaDB afterwards as well.
MARIADB_DATABASE: ${DB_DATABASE:-retrobite}
MARIADB_USER: ${DB_USERNAME:-retrobite}
MARIADB_PASSWORD: ${DB_PASSWORD:-retrobite}
MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:-retrobite}
volumes:
- ${DB_PATH:-retrobite-db}:/var/lib/mysql
# Not published to the host: nothing outside the compose network needs it,
# and this box sits on a LAN with consoles on it.
expose:
- "3306"
healthcheck:
# The web container's migrate races the database otherwise: the server
# reports started long before InnoDB will accept a connection.
test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
interval: 5s
timeout: 5s
retries: 20
start_period: 30s
restart: unless-stopped
retrobite-share:
image: retrobite/share:${RETROBITE_TAG:-develop}
container_name: retrobite-share
env_file:
- path: .env
required: false
environment:
AUTH_USER: ${AUTH_USER:-retrobite}
AUTH_PASS: ${AUTH_PASS:-retrobite}
# Advertised to FTP clients for passive mode. Empty, it is read off the
# default route on every start.
HOST_IP: ${HOST_IP:-}
# The console folders created in the library, and those that also get
# an SMB share of their own (what Open PS2 Loader connects to).
GAME_FOLDERS: ${GAME_FOLDERS:-}
SMB_SHARES: ${SMB_SHARES:-}
# ps3netsrv on port 38008, serving the PS3, PS2 and PS1 folders to
# webMAN MOD as its PS3ISO, PS2ISO and PSXISO lists. Read-only, and with
# no login: the whitelist (such as 192.168.1.*) limits who can read it.
PS3NETSRV: ${PS3NETSRV:-true}
PS3NETSRV_WHITELIST: ${PS3NETSRV_WHITELIST:-}
PS3NETSRV_FOLDERS: ${PS3NETSRV_FOLDERS:-PS3ISO=ps3 PS2ISO=ps2 PSXISO=psx}
# On the host's network, so consoles find it by NetBIOS and passive FTP
# works without a port range published. Ports 445, 139, 21 and 38008 must
# be free: on a NAS they are its own file sharing; see the Installation docs.
network_mode: host
volumes:
- ${GAMES_PATH:-./games}:/games
cap_add:
- NET_ADMIN
- SYS_ADMIN
init: true
restart: unless-stopped
volumes:
retrobite-db:
retrobite-media:
retrobite-state:It runs develop, the newest pre-release, so docker compose pull always brings the newest beta. To stay on one version, set RETROBITE_TAG to it, such as 20261006-BETA; once there is a full release, latest follows releases.
The share container uses the host's network, so consoles find it by name. That needs ports 445, 139, 21 and 38008 free, which they are unless Samba, an FTP server or ps3netsrv already runs on the machine. If one does, see When ports 445, 139 and 21 are taken.
ps3netsrv has no login
The share container runs ps3netsrv on port 38008, so webMAN MOD on a PS3 can play games straight from the library. It is read-only, but anyone on the network can read the folders it serves. Set PS3NETSRV_WHITELIST to your PS3's address or your network, such as 192.168.1.*, or PS3NETSRV=false to turn it off. See Configuration.
Portainer and Dockhand
Both deploy a compose file as a stack and fill its ${VARIABLES} from their own editor, so no .env file is needed.
Stacks → Add stack (Dockhand: Stacks → New). Name it
retrobite.Choose one source:
- Web editor: paste the contents of
docker-compose.yml. - Repository:
https://github.com/retroBITE-app/retroBITE, compose pathdocker-compose.yml. For the reference, use a release's tag, such asrefs/tags/20261006-BETA, and setRETROBITE_TAGto the same version below, so the file and the images match.
- Web editor: paste the contents of
Under Environment variables, add at least:
AUTH_PASS,DB_PASSWORDandDB_ROOT_PASSWORDGAMES_PATH, as an absolute path on the Docker hostHOST_IPandAPP_TIMEZONE
In Portainer, Load variables from .env file takes
.env.exampleas a starting point.Deploy the stack. A container's Logs shows its start, including a warning for every setting still left at its default.
Settings not in the compose file, such as QUEUE_WORKERS_MEDIA, go in the same editor and are added under the service's environment: in the compose file. See Configuration.
Synology
DSM 7.2 or later, with Container Manager from the Package Center.
- Make the folders in File Station.
- Use your library's shared folder, such as
/volume1/games, with one folder per console inside it. - Make a folder for the project, such as
/volume1/docker/retrobite.
- Use your library's shared folder, such as
- Put the files in the project folder. Save
.env.examplethere as.envand edit it:GAMES_PATH=/volume1/games- the passwords
HOST_IP(the NAS's address) andAPP_TIMEZONE- optionally
DB_PATH,MEDIA_PATHandSTATE_PATHunder/volume1/docker/retrobite/, to include them in Hyper Backup
- Create the project. In Container Manager go to Project → Create, set the path to the project folder, and choose Upload docker-compose.yml.
- Free the SMB and FTP ports. DSM's own file sharing already uses 445, 139 and 21, so the share container cannot start as it is. Either:
- give it an address of its own, as described in When ports 445, 139 and 21 are taken. The parent interface is
eth0, orovs_eth0with Open vSwitch on. - or turn off SMB and FTP in Control Panel → File Services, if the NAS shares nothing else.
- give it an address of its own, as described in When ports 445, 139 and 21 are taken. The parent interface is
- Build starts it. Open
http://<NAS address>:81.
The containers run as whoever owns the games folder. If a console cannot write over SMB and the log says the library is not writable, give that folder's owner read and write in File Station → Properties → Permission.
QNAP
Container Station 3:
- Go to Applications → Create, name it
retrobite, and pastedocker-compose.yml. - Container Station has no variables editor, so change the defaults in the file itself. In
${GAMES_PATH:-./games}, the part after:-is the value used. SetGAMES_PATHto the library's absolute path, such as/share/Games, and change the passwords there. - QTS's own SMB and FTP use 445, 139 and 21, as on Synology. Use macvlan with the parent interface
eth0(or the virtual switch's name), or turn off QTS's Microsoft Networking and FTP.
Unraid
Install Docker Compose Manager from Community Applications.
- Go to Docker → Compose → Add new stack, name it
retrobite, and pastedocker-compose.ymlwith Edit stack → Compose file. - Under Edit stack → Env file, paste
.env.exampleand set:GAMES_PATH=/mnt/user/gamesDB_PATH=/mnt/user/appdata/retrobite/dbMEDIA_PATH=/mnt/user/appdata/retrobite/mediaSTATE_PATH=/mnt/user/appdata/retrobite/state- the passwords,
HOST_IPandAPP_TIMEZONE
- Unraid's own SMB uses 445 and 139. Use macvlan with
SHARE_PARENT=br0(Unraid's default bridge), or stop Unraid's SMB if nothing else uses it. - Compose up.
TrueNAS SCALE
TrueNAS SCALE 24.10 (Electric Eel) or later runs compose files directly.
- Make datasets for the library and for retroBITE's data, such as
/mnt/tank/gamesand/mnt/tank/apps/retrobite/{db,media,state}. - Go to Apps → Discover Apps → ⋮ → Install via YAML and paste
docker-compose.yml. - The YAML editor has no variables, so replace the
${…:-default}values you need with your own. At least set:GAMES_PATH,DB_PATH,MEDIA_PATHandSTATE_PATHto the datasets- the passwords
HOST_IP
- If TrueNAS shares anything over SMB itself, the share container needs macvlan, with the parent interface from Network → Interfaces.
Docker Desktop on Windows and macOS
Docker Desktop runs the web interface well, and is a good way to try retroBITE. Serving consoles from it is another matter:
- Windows holds port 445 for its own file sharing.
- macOS holds port 445 whenever File Sharing is on.
- Docker Desktop supports neither the host network the share container uses by default nor macvlan.
So start the web interface and the database alone:
docker compose up -d retrobite-web retrobite-dband serve the library to consoles from the computer itself, or from a NAS. On Windows, put the library on the Windows drive (GAMES_PATH=C:/Games), and expect scanning to be slower than on a Linux disk.
Send to → USB drive works from Docker Desktop. It needs Chrome or Edge on http://localhost:81.
When ports 445, 139 and 21 are taken
A NAS's own file sharing, and Samba, an FTP server or ps3netsrv on a Linux machine, already listen on the ports consoles connect to (445, 139, 21 and 38008). docker-compose.macvlan.yml gives the share container an address of its own on the LAN, as though it were another computer, and leaves the NAS's sharing alone.
Pick an address. It must be free, and outside the router's DHCP range so nothing else is handed it.
Add these settings to
.envor to the stack's variables:bashSHARE_IP=192.168.1.250 # the address consoles will use SHARE_SUBNET=192.168.1.0/24 # your LAN SHARE_GATEWAY=192.168.1.1 # your router SHARE_PARENT=eth0 # the host's LAN interface: `ip route` shows itStart it with both files:
bashcurl -LO https://raw.githubusercontent.com/retroBITE-app/retroBITE/develop/docker-compose.macvlan.yml docker compose -f docker-compose.yml -f docker-compose.macvlan.yml up -dIn Portainer, Dockhand or Container Manager, paste the two files together: the
networks:block and theretrobite-shareandretrobite-webchanges fromdocker-compose.macvlan.yml, merged intodocker-compose.yml.
Consoles connect to SHARE_IP. The NAS itself cannot reach that address, which is how macvlan works and nothing to fix: retroBITE checks the share over a network of its own.
Updating
The Compose file runs develop, the newest pre-release, so an update is:
docker compose pull
docker compose up -dIn Portainer and Dockhand, use Pull and redeploy. In Container Manager, use Action → Build.
If you set RETROBITE_TAG to one version, change it to the next version first.
The database is brought up to date on start. Your library, database, artwork and keys are kept: they live in the volumes or folders above, not in the containers.
Backing up
| What | Where | Why |
|---|---|---|
| The database | DB_PATH, or volume retrobite-db | Your games, metadata, settings and accounts. |
| The keys | STATE_PATH, or volume retrobite-state | Without the application key, the stored passwords in the database cannot be read. Always back it up with the database. |
| The library | GAMES_PATH | Your files. retroBITE only changes them when you ask it to. |
| Artwork | MEDIA_PATH, or volume retrobite-media | Optional: it can be downloaded again. |
For a consistent copy of the database, stop the stack first (docker compose stop), or take a dump while it runs:
docker exec retrobite-mariadb mariadb-dump -u root -p"$DB_ROOT_PASSWORD" retrobite > retrobite.sql