Ludarium

A local-first, self-hosted catalog for game archives. Ludarium turns read-only folders of ROMs, disc images and archived Windows installers into a searchable library with provenance, integrity evidence and an explicit review queue. It is built for Unraid, but the supplied Compose deployment also works on a regular Docker host.

What you can do

discover and fingerprint files without renaming, moving or executing them;
group multi-file games, discs, installers, patches and DLC into useful catalog entries;
review uncertain matches instead of silently accepting guesses;
find duplicates and integrity problems while retaining the evidence behind each result;
organise games with collections, tags, favourites, play status, ratings and notes;
enrich metadata from optional providers while keeping manual values authoritative;
export JSON, EmulationStation and Pegasus-compatible catalog data;
keep emulator saves and savestates as bounded, immutable revisions in the Game Data Vault;
optionally launch supported browser or isolated native players.

The source libraries are mounted read-only. Ludarium writes only to its own PostgreSQL database, cache, exports and explicitly configured player data. Scanned native files are never executed by the cataloging pipeline.

Quick start

You need Docker with Compose, three directories to expose as read-only libraries, and two independent random secrets of at least 32 characters.

cp deploy/.env.example deploy/.env
# Edit deploy/.env: set POSTGRES_PASSWORD, LUDARIUM_ADMIN_TOKEN and your library paths.
docker compose --env-file deploy/.env -f deploy/compose.yml up -d --build

Open http://localhost:1230. Check liveness at /health/live and database readiness at /health/ready. API routes require Authorization: Bearer <LUDARIUM_ADMIN_TOKEN>; the web interface stores that token in the browser session after you enter it.

Before scanning, confirm in the container details that every /library/* mount is read-only. The application refuses unsafe paths and does not need write access to your originals. See deploy/README.md for Unraid templates, backups, upgrades, optional providers and isolated player sidecars.

How the workflow feels

Add one or more library roots and run a quick inventory.
Open the review queue for unknown files, ambiguous matches and incomplete bundles.
Accept or correct proposed identities; Ludarium preserves the evidence and confidence behind them.
Browse the resulting catalog, build collections and inspect integrity or duplicate reports.
Run deeper hashes or exports only when useful; the original files remain untouched throughout.

Ludarium is an archive manager, not a downloader, storefront or rights-management bypass. It does not ship games, firmware, console keys, provider datasets or third-party credentials. You are responsible for the content you index and for complying with the rules that apply to it.

Security and privacy

Keep Ludarium on a trusted network or place it behind an authenticated HTTPS reverse proxy.
Use a unique admin token; production startup rejects missing, short and obvious placeholder tokens.
Treat the browser-player origin as privileged. A distinct player origin is recommended when exposing browser emulation beyond a trusted LAN.
Optional metadata providers receive only the requests required for enrichment and are disabled when no credentials are configured.
Report vulnerabilities privately using SECURITY.md.

Development

The backend targets .NET 10, the UI uses React 19 and Vite, and controller helpers use Python's standard library. Run the complete source-only validation without Docker privileges:

sh deploy/run-managed-validation.sh source

The canonical development repository also contains hardened image and release gates for trusted revisions. The public validation workflow deliberately needs no Docker daemon or deployment secrets.

Project status and licensing

Ludarium is release-candidate software. Back up app data before upgrades and qualify optional native players against your own hardware. First-party source code in this repository is licensed under AGPL-3.0-or-later; see LICENSE. Third-party components and assets remain subject to their own documented terms.

Third-party and generated visual assets are documented in THIRD_PARTY_NOTICES.md and their adjacent provenance records. Game metadata, DAT files, ROMs, firmware and proprietary keys are not part of the project.

4.6 KiB Raw Permalink Blame History