Installation

retroBITE is intended to run in Docker, and Docker is the only supported way to install it. It runs as 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) and vsftpd FTP, 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.

INFO

For legally made backups of media you own. retroBITE does not endorse piracy.

Requirements

• Docker Engine with the Compose plugin (docker compose).
• A Linux host on your local network. The share container uses host networking so consoles can reach it directly.
• Free ports on the host: 81 for the web interface, 139 and 445 for SMB, and 20, 21 and 21100-21110 for FTP.

1. Create a folder

Make a folder for retroBITE and move into it. The Compose file, the .env file and, by default, your games all live here.

mkdir retrobite && cd retrobite

2. Create docker-compose.yml

Save this as docker-compose.yml in the folder:

services:
  retrobite-web:
    image: retrobite/retrobite:latest
    container_name: retrobite-web
    env_file:
      - .env
    environment:
      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}
      TRANSFER_LOCALHOST_URL: ${TRANSFER_LOCALHOST_URL:-http://localhost:81}
      SERVE_WITH_NGINX: "true"
    ports:
      - "81:80"
    volumes:
      - ${GAMES_PATH:-./games}:/app/storage/app/games
      - ${DOCS_PATH:-./storage/app/docs}:/app/storage/app/docs
      - retrobite-media:/app/storage/app/media
    depends_on:
      retrobite-db:
        condition: service_healthy
    restart: on-failure

  retrobite-db:
    image: mariadb:11.4
    container_name: retrobite-mariadb
    environment:
      MARIADB_DATABASE: ${DB_DATABASE:-retrobite}
      MARIADB_USER: ${DB_USERNAME:-retrobite}
      MARIADB_PASSWORD: ${DB_PASSWORD:-retrobite}
      MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:-retrobite}
    volumes:
      - retrobite-db:/var/lib/mysql
    expose:
      - "3306"
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 5s
      timeout: 5s
      retries: 20
      start_period: 30s
    restart: on-failure

  retrobite-share:
    image: retrobite/share:latest
    container_name: retrobite-share
    env_file:
      - .env
    restart: on-failure
    network_mode: host
    volumes:
      - ${GAMES_PATH:-./games}:/games
    cap_add:
      - NET_ADMIN
      - SYS_ADMIN
    init: true
    # Prefer bridge networking? Drop network_mode and uncomment these.
    # ports:
    #   - "139:139"     # SMB
    #   - "445:445"     # SMB
    #   - "20:20"       # FTP data
    #   - "21:21"       # FTP control
    #   - "21100-21110:21100-21110"  # FTP passive ports

volumes:
  retrobite-db:
  retrobite-media:

latest is the newest release. Use develop for the newest pre-release, or a date tag such as 20260930 to stay on one version.

Bridge networking

The share container uses host networking by default. To use Docker's bridge network instead, remove network_mode: host and uncomment the ports list under retrobite-share.

3. Create .env

Download the example settings and give them an application key:

curl -o .env https://raw.githubusercontent.com/retroBITE-app/retroBITE/develop/.env.example
key=$(docker run --rm --entrypoint php retrobite/retrobite:latest artisan key:generate --show)
sed -i.bak "s|^APP_KEY=.*|APP_KEY=$key|" .env && rm .env.bak

Then set at least:

Setting	What it is
AUTH_USER / AUTH_PASS	The account consoles use for SMB and FTP. Change the password.
HOST_IP	This machine's LAN address. FTP passive mode hands it to consoles, so localhost will not do.
GAMES_PATH	Where your library is on this machine. Defaults to ./games.
DB_PASSWORD / DB_ROOT_PASSWORD	The database passwords. Change them before the first start: they are set when the database is created.

Every other setting is optional. See Configuration for the full list.

4. Start the stack

docker compose up -d

The first start pulls the images and creates the database. The web container waits for MariaDB to be ready before it runs its migrations.

5. Open retroBITE

Open http://localhost:81 on the host, or http://<HOST_IP>:81 from another device, and follow the four-step setup: your account, the interface, ScreenScraper and RetroAchievements.

Where your data lives

Where	What
GAMES_PATH (default ./games)	Your ROM library, one folder per console. Shared as /games over SMB and FTP.
retrobite-db volume	The MariaDB database: your games, their metadata and your settings.
retrobite-media volume	The artwork and media retroBITE downloads.

The volumes survive docker compose down and updates. ROMs are never served straight over the web: downloads go through a signed-in route only.

Updating

Pull the newest images and recreate the containers:

docker compose pull
docker compose up -d

Your library, database and media are kept. Database migrations run automatically when the web container starts.