Skip to content
Getting startedInstallation

Installation ​

retroBITE runs in Docker, and Docker is the only supported way to install it. It is a Docker Compose stack of three containers:

ContainerImageWhat it does
retrobite-webretrobite/retrobiteThe web interface, queue workers and live updates
retrobite-shareretrobite/shareSamba (SMBv1 to SMB3), vsftpd FTP and ps3netsrv, serving the library to consoles
retrobite-dbmariadb:11.4The 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).

bash
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 -d

Open 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:

yml
# 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.

  1. Stacks → Add stack (Dockhand: Stacks → New). Name it retrobite.

  2. Choose one source:

    • Web editor: paste the contents of docker-compose.yml.
    • Repository: https://github.com/retroBITE-app/retroBITE, compose path docker-compose.yml. For the reference, use a release's tag, such as refs/tags/20261006-BETA, and set RETROBITE_TAG to the same version below, so the file and the images match.
  3. Under Environment variables, add at least:

    • AUTH_PASS, DB_PASSWORD and DB_ROOT_PASSWORD
    • GAMES_PATH, as an absolute path on the Docker host
    • HOST_IP and APP_TIMEZONE

    In Portainer, Load variables from .env file takes .env.example as a starting point.

  4. 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.

  1. 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.
  2. Put the files in the project folder. Save .env.example there as .env and edit it:
    • GAMES_PATH=/volume1/games
    • the passwords
    • HOST_IP (the NAS's address) and APP_TIMEZONE
    • optionally DB_PATH, MEDIA_PATH and STATE_PATH under /volume1/docker/retrobite/, to include them in Hyper Backup
  3. Create the project. In Container Manager go to Project → Create, set the path to the project folder, and choose Upload docker-compose.yml.
  4. 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, or ovs_eth0 with Open vSwitch on.
    • or turn off SMB and FTP in Control Panel → File Services, if the NAS shares nothing else.
  5. 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:

  1. Go to Applications → Create, name it retrobite, and paste docker-compose.yml.
  2. 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. Set GAMES_PATH to the library's absolute path, such as /share/Games, and change the passwords there.
  3. 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.

  1. Go to Docker → Compose → Add new stack, name it retrobite, and paste docker-compose.yml with Edit stack → Compose file.
  2. Under Edit stack → Env file, paste .env.example and set:
    • GAMES_PATH=/mnt/user/games
    • DB_PATH=/mnt/user/appdata/retrobite/db
    • MEDIA_PATH=/mnt/user/appdata/retrobite/media
    • STATE_PATH=/mnt/user/appdata/retrobite/state
    • the passwords, HOST_IP and APP_TIMEZONE
  3. 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.
  4. Compose up.

TrueNAS SCALE ​

TrueNAS SCALE 24.10 (Electric Eel) or later runs compose files directly.

  1. Make datasets for the library and for retroBITE's data, such as /mnt/tank/games and /mnt/tank/apps/retrobite/{db,media,state}.
  2. Go to Apps → Discover Apps → ⋮ → Install via YAML and paste docker-compose.yml.
  3. The YAML editor has no variables, so replace the ${…:-default} values you need with your own. At least set:
    • GAMES_PATH, DB_PATH, MEDIA_PATH and STATE_PATH to the datasets
    • the passwords
    • HOST_IP
  4. 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:

bash
docker compose up -d retrobite-web retrobite-db

and 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.

  1. Pick an address. It must be free, and outside the router's DHCP range so nothing else is handed it.

  2. Add these settings to .env or to the stack's variables:

    bash
    SHARE_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 it
  3. Start it with both files:

    bash
    curl -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 -d

    In Portainer, Dockhand or Container Manager, paste the two files together: the networks: block and the retrobite-share and retrobite-web changes from docker-compose.macvlan.yml, merged into docker-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:

bash
docker compose pull
docker compose up -d

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

WhatWhereWhy
The databaseDB_PATH, or volume retrobite-dbYour games, metadata, settings and accounts.
The keysSTATE_PATH, or volume retrobite-stateWithout the application key, the stored passwords in the database cannot be read. Always back it up with the database.
The libraryGAMES_PATHYour files. retroBITE only changes them when you ask it to.
ArtworkMEDIA_PATH, or volume retrobite-mediaOptional: 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:

bash
docker exec retrobite-mariadb mariadb-dump -u root -p"$DB_ROOT_PASSWORD" retrobite > retrobite.sql
Released under the MIT License.retroBITE