Skip to content

Romm

ROM Manager for retrogaming - Self-hosted platform with web-based emulator (EmulatorJS).

Informations

Accès

  • URL publique: https://retro.ncls.ltd
  • Backend: http://192.168.1.104:8082
  • Authentification: Authelia SSO + Romm login
  • First-time setup: Complete wizard to create admin account

Configuration

Structure

104-services/
└── romm/
    ├── config/
    │   └── config.yml    # Configuration persistence (backed up)
    └── assets/           # Saves, states, screenshots (backed up)

/mnt/media/games/         # ROM files (not backed up)

Note: The config.yml file must exist for Romm to persist configuration changes made through the web UI. A minimal template:

system:
  version: 1

Services Docker

Déployé via Portainer Stack sur LXC 104 :

  • romm: Application principale (Python)
  • romm-db: Base de données MariaDB

Volumes

  • romm_resources: Metadata IGDB (covers, screenshots)
  • romm_redis_data: Cache Redis
  • /opt/docker/romm/config: Configuration files
  • /opt/docker/romm/assets: User uploads (saves/states)
  • /mnt/games: ROM library (bind mount from /mnt/media/games)

Configuration Portainer

Path: /mnt/lxc-data/104-services/romm/PORTAINER_STACK_REFERENCE.md

Stack managé via Portainer UI -> LXC 104 endpoint.

Fonctionnalités

  • ROM Management: Organization, metadata, covers
  • EmulatorJS: Play ROMs in browser (NES, SNES, PSX, etc.)
  • Metadata Providers: IGDB, ScreenScraper, RetroAchievements
  • Multi-user: User management with roles (ADMIN, EDITOR, VIEWER)
  • Saves Management: Upload/download game saves and states
  • Gamepad Support: USB controllers via HTML5 Gamepad API

ROM Organization

Romm expects ROMs in this structure:

/mnt/media/games/
├── roms/
│   ├── nintendo - nintendo entertainment system/
│   ├── nintendo - super nintendo entertainment system/
│   ├── sony - playstation/
│   └── ...
└── bios/
    └── (BIOS files for systems requiring them)

Inside container: /romm/library/

Metadata Providers

IGDB Setup

  1. Register at dev.twitch.tv/console
  2. Create application
  3. Get Client ID and Client Secret
  4. Add to Portainer stack environment variables
  5. Redeploy stack

Optional Providers

Commandes Utiles

# Check stack status
pct exec 104 -- docker ps --filter "name=romm"

# View Romm logs
pct exec 104 -- docker logs -f romm

# View MariaDB logs
pct exec 104 -- docker logs -f romm-db

# Check ROM library mount
pct exec 104 -- docker exec romm ls -la /romm/library

# Restart via Portainer
# UI: Stacks → romm → Stop → Start

Backup

Automatique (via script)

Path: /usr/local/bin/backup-docker-configs.sh

Sauvegardé quotidiennement (05:00):

  • /mnt/lxc-data/104-services/romm/config/ - Configuration
  • /mnt/lxc-data/104-services/romm/assets/ - Saves et states

Non sauvegardé:

  • /mnt/media/games/ - ROM files (user responsibility, re-downloadable)
  • Named volumes romm_resources, romm_redis_data (metadata re-scrapable)

Destination: Google Drive gdrive:backup/homeserver/lxc-data/

Manuel Database Backup

pct exec 104 -- docker exec romm-db mariadb-dump -uromm-user -p romm > romm-backup-$(date +%Y%m%d).sql

Mise à Jour

Via Portainer UI:

  1. Navigate to LXC 104 endpoint
  2. Go to Stacks → romm
  3. Click "Pull and redeploy"

Note: Check release notes for breaking changes

Reverse Proxy

Config : caddy/Caddyfile sur LXC 103 (bloc retro.ncls.ltd)

  • Frontend: https://retro.ncls.ltd
  • Backend: http://192.168.1.104:8082
  • Auth: Authelia Forward Auth (one_factor)
  • WebSocket: Enabled for EmulatorJS

Troubleshooting

Config File Warning

Error: "Config file not found! Changes will not persist after restart"

Solution:

# Create config.yml if missing
cat > /mnt/lxc-data/104-services/romm/config/config.yml << 'EOF'
system:
  version: 1
EOF

# Fix permissions
chown 100000:100000 /mnt/lxc-data/104-services/romm/config/config.yml
chmod 644 /mnt/lxc-data/104-services/romm/config/config.yml

# Restart container
pct exec 104 -- docker restart romm

ROMs Not Detected

# Check mount inside container
pct exec 104 -- docker exec romm ls -la /romm/library/

# Verify ownership
ls -la /mnt/media/games/
# Should show: 100000:100000

Metadata Not Loading

  • Verify IGDB credentials in Portainer environment variables
  • Check Romm logs for API errors
  • Ensure internet connectivity from LXC 104

EmulatorJS Not Starting

  • Check browser console for JavaScript errors
  • Verify BIOS files present in /mnt/media/games/bios/ for systems requiring them
  • Test with different browser (compatibility)

Resources