RetroAssembly Setup Guide

Introduction

RetroAssembly is a web-based retro game library manager and launcher. Running as a lightweight service on your server, it centralizes your ROMs, BIOS files, and save states into a single web interface, allowing clients across your network to browse and play classic games directly in the browser using integrated emulators.

---

Step 1: Initial Container Deployment

1. Ensure the required environment variables are set in your root .env file:

RETROASSEMBLY_PORT=8000
NAS_GAMEDIR=/path/to/your/games

2. Copy the retroassembly.yaml file into your active server compose directory:

cp compose/templates/retroassembly.yaml compose/server1/retroassembly.yaml

3. Create host directories for configuration, logs, and game storage:

sudo mkdir -p ${DOCKERDIR}/retroassembly ${DOCKERDIR}/logs/retroassembly
sudo mkdir -p ${NAS_GAMEDIR}/roms ${NAS_GAMEDIR}/bios ${NAS_GAMEDIR}/saves

4. Launch the container:

docker compose -p mediaserver -f docker-compose-server1.yaml up -d retroassembly

---

Step 2: Service Definition (retroassembly.yaml)

# ------------------------------------------------------------------------------
# retroassembly - Web-based Retro Game Library + Launcher
# ------------------------------------------------------------------------------
services:
  retroassembly:
    container_name: retroassembly.${HOST_NAME}
    hostname: retroassembly.${HOST_NAME}.lan
    image: arianrhodsandlot/retroassembly:latest
    environment:
      TZ: ${TZ}
      PUID: ${PUID}
      PGID: ${PGID}
      # Optional: enable verbose logging
      # LOG_LEVEL: debug
    networks:
      - mediaserver
    ports:
      - ${RETROASSEMBLY_PORT}:8000
    volumes:
      - ${DOCKERDIR}/retroassembly:/app/data
      - ${NAS_GAMEDIR}/roms:/roms
      - ${NAS_GAMEDIR}/bios:/bios
      - ${NAS_GAMEDIR}/saves:/saves
      - ${DOCKERDIR}/logs/retroassembly:/var/log
    restart: always
    security_opt:
      - no-new-privileges:true
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
      - "homepage.group=Other"
      - "homepage.name=retroassembly"
      - "homepage.icon=gamevault.png"
      - "homepage.href=https://retro.${DOMAINNAME}/"
      - "homepage.description=web-based retro game library + launcher"

---

Step 3: Accessing the UI & Onboarding

1. Open your browser and navigate to http://<your-ip-address>:8000 or your reverse proxy URL (https://retro.${DOMAINNAME}).
2. Create your administrator credentials upon first login.
3. Access the web administration panel to initiate a media scan across your /roms volume to detect newly placed game files.

---

Step 4: Library & Media Setup

Directory Organization

Organize your host game files within ${NAS_GAMEDIR} according to the system console subfolders expected by RetroAssembly:

${NAS_GAMEDIR}/
├── roms/
│   ├── nes/
│   ├── snes/
│   ├── gba/
│   └── psx/
├── bios/
│   ├── scph1001.bin
│   └── gba_bios.bin
└── saves/

Custom Art & Metadata

• Scraping: Use the built-in library scanner to automatically download game box art, screenshots, and metadata.
• BIOS Files: Ensure required system BIOS files (e.g., PlayStation, Game Boy Advance) are placed inside ${NAS_GAMEDIR}/bios so web emulators can load hardware-dependent games properly.

---

Step 5: Backup & Restore

Backing Up

• Stop the container and back up the persistent application state along with save files:

  docker compose -p mediaserver -f docker-compose-server1.yaml stop retroassembly
  tar -czvf retroassembly_backup.tar.gz ${DOCKERDIR}/retroassembly ${NAS_GAMEDIR}/saves
  docker compose -p mediaserver -f docker-compose-server1.yaml start retroassembly
  

Restoring

1. Stop the container.
2. Extract your backup archive back into ${DOCKERDIR}/retroassembly and ${NAS_GAMEDIR}/saves.
3. Restart the container.

---

Step 6: Troubleshooting

• Blank Screen / Emulator Fails to Load Game: Verify that necessary BIOS files exist in /bios and that file permissions on ${NAS_GAMEDIR} allow read access for PUID/PGID.
• Save States Not Persisting: Ensure ${NAS_GAMEDIR}/saves is writable by the container user.
• Logs: Check real-time log outputs for error traces:

  docker logs -f retroassembly.${HOST_NAME}