Deploying Retrom

Introduction

Retrom is a self-hosted retro game library manager that helps you organize, catalog, and access your retro game collection through a beautiful web interface. It automatically fetches metadata, cover art, and information for your games, transforming a folder of ROM files into a navigable, searchable library.

Key highlights of Retrom:

• Library Management: Organize ROMs across multiple platforms and systems
• Metadata Fetching: Automatic game information and cover art from various sources
• Modern Interface: Clean, responsive web UI for browsing your collection
• Platform Support: Support for numerous retro gaming platforms
• Search and Filter: Find games quickly with powerful search
• Collections: Create custom game collections and playlists
• Multi-User: Support for multiple user accounts
• REST API: API for integrations and automation
• Docker Native: Designed for containerized deployment
• Open Source: Self-hosted with full control over your data

This guide walks through deploying Retrom on Klutch.sh using Docker and configuring your retro game library.

Why Deploy Retrom on Klutch.sh

Deploying Retrom on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically builds and deploys Retrom without complex configuration.

Persistent Storage: Attach persistent volumes for your game library and metadata that survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL for secure access to your library from anywhere.

Always-On Availability: Your retro game library remains accessible 24/7.

Prerequisites

Before deploying Retrom on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Retrom configuration
• Your ROM collection organized by platform
• Basic familiarity with Docker

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for Retrom deployment.

Repository Structure

retrom-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/jmberesern/retrom:latest

# Create necessary directories
RUN mkdir -p /retrom/library /retrom/config

# Expose the web interface port
EXPOSE 5101

# The base image includes the default entrypoint

Environment Variables Reference

Variable	Required	Description
RETROM_CONFIG	No	Path to configuration directory

Deploying Retrom on Klutch.sh

Push Your Repository to GitHub

Commit and push your Dockerfile to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project with a descriptive name like “retrom” or “retro-library”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select the repository containing your Retrom Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 5101

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/retrom/library	100+ GB	Your ROM collection
/retrom/config	1 GB	Configuration and metadata

Deploy Your Application

Click Deploy to start the build process.

Access Retrom

Once deployment completes, access Retrom at your app URL.

Initial Configuration

First-Time Setup

1. Access the Retrom web interface
2. Create your administrator account
3. Configure initial settings

Adding Your Library

1. Upload your ROM files to the library volume
2. Organize by platform (e.g., /retrom/library/nes, /retrom/library/snes)
3. Trigger a library scan from the settings

Recommended Directory Structure

/retrom/library/
├── nes/
│   └── Game Title.nes
├── snes/
│   └── Game Title.sfc
├── genesis/
│   └── Game Title.md
├── gba/
│   └── Game Title.gba
└── n64/
    └── Game Title.z64

Metadata Configuration

1. Navigate to Settings > Metadata
2. Configure metadata providers
3. Run metadata matching for your library
4. Review and correct any mismatches

Using Retrom

Browsing Your Library

• Browse by platform
• Search for specific games
• Filter by genre, year, or other metadata
• View detailed game information

Creating Collections

1. Click Collections > New Collection
2. Name your collection
3. Add games to the collection
4. Collections appear in your library navigation

Additional Resources

• Retrom GitHub Repository

Conclusion

Deploying Retrom on Klutch.sh gives you a beautiful, organized way to manage and access your retro game collection. With automatic metadata fetching and a modern interface, Retrom transforms your ROM collection into a proper game library accessible from anywhere with secure HTTPS access.