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

> Easily set up RomM the self-hosted ROM manager using Docker Compose. This guide covers the complete setup for the FastAPI, Vue 3, Valkey, and MariaDB stack.

- Repository: [The RomM Project/romm](https://github.com/rommapp/romm)
- Tags: how-to-guide
- Published: 2026-07-07

---

**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`](https://github.com/rommapp/romm/blob/main/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:

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

```

### 2. Configure Environment Variables

Copy the template and generate required secrets:

```bash
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`](https://github.com/rommapp/romm/blob/main/docker-compose.yml)): Builds from source for testing contributions:

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

```

**Production Stack** ([`examples/docker-compose.example.yml`](https://github.com/rommapp/romm/blob/main/examples/docker-compose.example.yml)): Uses pre-built images for stable deployments:

```bash
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:

```bash
docker compose up -d

```

Verify service health:

```bash
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:

```bash

# 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`](https://github.com/rommapp/romm/blob/main/docker-compose.yml): Development configuration building from source
- [`examples/docker-compose.example.yml`](https://github.com/rommapp/romm/blob/main/examples/docker-compose.example.yml): Production-ready template with pre-built images
- `env.template`: Complete environment variable reference
- [`docs/BACKEND_ARCHITECTURE.md`](https://github.com/rommapp/romm/blob/main/docs/BACKEND_ARCHITECTURE.md): Database schema and service internals
- [`docs/FRONTEND_ARCHITECTURE.md`](https://github.com/rommapp/romm/blob/main/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`](https://github.com/rommapp/romm/blob/main/docker-compose.yml), while production environments should use [`examples/docker-compose.example.yml`](https://github.com/rommapp/romm/blob/main/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`](https://github.com/rommapp/romm/blob/main/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`](https://github.com/rommapp/romm/blob/main/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:

```bash
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`.