How to Set Up RomM with Docker Compose: A Complete Guide

RomM is a self-hosted ROM manager that deploys via Docker Compose using a multi-container stack consisting of a FastAPI backend, Vue 3 frontend, Valkey cache, and MariaDB database, configured through environment variables defined in an .env file.

RomM is a powerful self-hosted ROM manager built by the rommapp/romm community that organizes your retro gaming library with modern web technologies. This guide walks you through deploying the complete RomM stack using Docker Compose, covering both development and production configurations based on the official repository structure.

Understanding the RomM Architecture

Before deploying, understand the containerized components defined in the project's docker-compose.yml files. The stack consists of four core services working together:

• romm: The main application container running the FastAPI backend and compiled Vue 3 frontend assets (image: rommapp/romm:latest)
• romm-db: Database layer using mariadb:11.3.2 (or optionally postgres:16-alpine) for storing library metadata and user accounts
• romm-valkey: In-memory cache using valkey/valkey:8 for background task processing and session storage
• romm-authentik-server/worker: Optional OpenID Connect authentication using ghcr.io/goauthentik/server:2024.10.4 when OIDC_ENABLED=true

The backend connects to MariaDB using DB_HOST, DB_NAME, DB_USER, and DB_PASSWD variables, while the Valkey cache uses REDIS_HOST and REDIS_PORT. The Vue frontend communicates with the backend through /api/* endpoints defined in the OpenAPI schema.

Prerequisites

Ensure you have the following before starting:

• Docker Engine 20.10+ and Docker Compose v2.0+
• Git for cloning the rommapp/romm repository
• A host directory containing your ROM library for bind-mounting
• OpenSSL for generating the required ROMM_AUTH_SECRET_KEY

Step-by-Step Docker Compose Setup

1. Clone the Repository

Download the source files to access the compose configurations:

git clone https://github.com/rommapp/romm.git
cd romm

2. Configure Environment Variables

Copy the template and generate required secrets:

cp env.template .env
openssl rand -hex 32

Edit .env to configure database credentials matching the MariaDB container settings:

• DB_HOST=romm-db
• DB_USER=romm-user
• DB_PASSWD=your-secure-password
• ROMM_AUTH_SECRET_KEY=<generated-key>

Optional: Add SCREENSCRAPER_USER, STEAMGRIDDB_API_KEY, and other provider keys for metadata enrichment.

3. Choose Your Compose Configuration

The repository provides two distinct configurations:

Development Stack (docker-compose.yml): Builds from source for testing contributions:

docker compose -f docker-compose.yml up --build -d

Production Stack (examples/docker-compose.example.yml): Uses pre-built images for stable deployments:

docker compose -f examples/docker-compose.example.yml up -d

The production example mounts your library at /path/to/library (update to your actual host path) and exposes port 8080.

4. Launch the Stack

Initialize the containers:

docker compose up -d

Verify service health:

docker compose ps

You should see romm, romm-db, and romm-valkey containers running (plus romm-authentik-server if using OIDC).

Post-Installation Configuration

Access the web interface based on your deployment:

• Development: http://localhost:3000 (Vite dev server) or http://localhost:5000 (API)
• Production: http://localhost:8080 (or your configured ROMM_BASE_URL)

Complete the setup wizard to point RomM to your library folder mounted at /romm/library. The scanner will walk the file tree and populate the database with your collection.

Essential Docker Compose Commands

Manage your RomM deployment with these commands:

# View logs from all services

docker compose logs -f

# Run database migrations after updates

docker compose exec romm uv run alembic upgrade head

# Stop and remove containers (preserve data)

docker compose down

# Complete cleanup including volumes

docker compose down -v

Key Configuration Files Reference

• docker-compose.yml: Development configuration building from source
• examples/docker-compose.example.yml: Production-ready template with pre-built images
• env.template: Complete environment variable reference
• docs/BACKEND_ARCHITECTURE.md: Database schema and service internals
• docs/FRONTEND_ARCHITECTURE.md: Vue 3 frontend and API contract details

Summary

• RomM deploys as a multi-container Docker Compose stack with FastAPI, Vue 3, Valkey, and MariaDB
• Use env.template to create your .env file with database credentials and ROMM_AUTH_SECRET_KEY
• Development deployments build from source using docker-compose.yml, while production environments should use examples/docker-compose.example.yml
• Bind-mount your ROM library to /romm/library to enable the scanner to access your collection
• Persistent data uses named volumes (romm_resources, romm_redis_data, mysql_data) for safe updates

Frequently Asked Questions

Can I use PostgreSQL instead of MariaDB?

Yes. While the default docker-compose.yml uses MariaDB (mariadb:11.3.2), you can substitute postgres:16-alpine in your compose file. Update DB_HOST and related variables in your .env file to match your PostgreSQL configuration, and ensure the romm container can reach the database host.

How do I enable OpenID Connect authentication?

Set OIDC_ENABLED=true in your .env file and configure the AUTHENTIK_* environment variables. The stack includes optional romm-authentik-server and romm-authentik-worker services using the ghcr.io/goauthentik/server:2024.10.4 image. When enabled, the backend redirects authentication requests to your Authentik instance.

Where is my ROM library stored when using Docker Compose?

Your library resides in a host directory that you bind-mount into the container at /romm/library. This path is specified in the volumes section of your docker-compose.yml file. The database stores only metadata and paths, while the actual ROM files remain in your host filesystem.

How do I update RomM to the latest version?

For production deployments using the example file, pull the latest image and restart:

docker compose -f examples/docker-compose.example.yml pull
docker compose -f examples/docker-compose.example.yml up -d

Then run migrations: docker compose exec romm uv run alembic upgrade head.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}