This commit is contained in:
Ludarium release export
@@ -0,0 +1,89 @@
|
||||
# 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.
|
||||
|
||||
```sh
|
||||
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`](deploy/README.md) for Unraid templates, backups, upgrades, optional providers and
|
||||
isolated player sidecars.
|
||||
|
||||
## How the workflow feels
|
||||
|
||||
1. Add one or more library roots and run a quick inventory.
|
||||
2. Open the review queue for unknown files, ambiguous matches and incomplete bundles.
|
||||
3. Accept or correct proposed identities; Ludarium preserves the evidence and confidence behind them.
|
||||
4. Browse the resulting catalog, build collections and inspect integrity or duplicate reports.
|
||||
5. 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`](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
|
||||
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`](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`](THIRD_PARTY_NOTICES.md) and their adjacent provenance records. Game metadata,
|
||||
DAT files, ROMs, firmware and proprietary keys are not part of the project.
|
||||
Reference in New Issue
Block a user