media-vault

Working name — placeholder. A self-hosted, open-source catalog for physical media collections: video games, movies, vinyl LPs & singles, CDs. Your data lives on your server. Think "Jellyfin for physical-media collectors."

Each item automatically gets a cover image, a rating, and a description, fetched from the right database per media type (IGDB for games, TMDB for films & series, Discogs or MusicBrainz for vinyl/CD) and unified into one browsable spine shelf.

📖 New here? Follow the Installation & Setup Guide — install the app + database, get the free artwork keys, and add them in the app, step by step.

Why self-hosted

People who collect physical media do so precisely because they distrust digital-only, cloud-locked ownership. So this app is one you run on your own server, with your own data and your own free API keys. No global accounts, no SaaS lock-in.

Features (v1)

• Unified catalog across games / movies / vinyl LPs / singles / CDs — one item model.
• Automatic artwork — cover image + rating + description auto-fetched per media type.
• Signature spine-shelf view (colour = platform/format) plus a gallery grid.
• Add flows: title search with auto-fill, CSV bulk import, best-effort in-browser barcode scan.
• Server-side metadata cache — each title fetched once, respecting API terms.
• Valuation — per-item market value + a collection total, condition-aware. Music via Discogs marketplace (free), games via eBay used-listing prices (free API key) — or PriceCharting if you have a paid token — and manual values for anything else.
• Multi-user within one instance (e.g. a household) via local email + password.

Metadata sources (bring your own free keys)

Enrichment stays idle for any source whose keys are blank — the app still runs. Music is the exception: without Discogs credentials it falls back to MusicBrainz, which needs no key (Discogs still adds liner notes and marketplace valuation when configured).

Every matched item also has a Choose cover… picker: browse every alternate the source knows — TMDB posters per language (and per season for series boxes), IGDB regional box art, Discogs scans of the release and its other pressings, Cover Art Archive fronts — and pick the one that matches the disc on your shelf.

Quick start (Docker)

cp .env.example .env      # then fill in your keys + a SESSION_SECRET
docker compose up -d      # pulls the prebuilt image (no build step)

Open http://localhost:8080, log in as the seed user (admin@media-vault.local / SEED_USER_PASSWORD), then click Enrich collection to fetch covers/ratings/descriptions. The app is a single image (API + UI on one port) plus a Postgres container.

Updating is just a pull — no rebuild:

docker compose pull && docker compose up -d

Images are published automatically to ghcr.io/halvar20000/media-vault on every commit.

Unraid

Install a postgres:16-alpine container first and point the DB variables at it, then either:

• Community Applications — search for media-vault in the Apps tab (once listed), or
• Docker → Add Container → Template with: https://raw.githubusercontent.com/halvar20000/media-vault/main/templates/media-vault.xml, or
• the Docker Compose Manager plugin with the docker-compose.yml above.

The CA store listing is defined by ca_profile.xml + templates/media-vault.xml.

Local development (no Docker)

Requires Node 20+ and a local Postgres.

# 1. Postgres — create a db matching your .env, then:
cd backend && npm install && npm run migrate && npm run seed && npm run dev   # API on :4000
cd frontend && npm install && npm run dev                                     # UI on :5173 (proxies /api)

Configuration

All config is via environment variables — see .env.example for the full list (database, session secret, app origin, and the three metadata-source keys).

API keys (IGDB, TMDB, Discogs, eBay, PriceCharting) can be added in-app via the ⚙ Settings panel — no env editing or restart. They're stored on your server, shown masked, and override the env defaults below. IGDB unlocks game covers + the catalogue, TMDB movies, Discogs music.

Shops can be configured in-app via the ⚙ Settings panel — toggle the built-in shops, set an Easy Cash store, and add your own custom shops by search-URL (use {query} as the placeholder, e.g. https://shop.xy/search?q={query}). Changes save to the database and apply instantly. The env vars below are just the initial defaults used until you save settings in the app.

MARKETPLACE picks the initial second-hand marketplace(s) for the find deals / bundles buttons, so titles and lot phrasing come out in each site's language. Comma-separated — each value adds its own button (e.g. MARKETPLACE=leboncoin,medimops,kleinanzeigen). Values: leboncoin (France, default), kleinanzeigen (Germany), ebay-de, ebay-com, ebay-uk, ebay-fr, marktplaats (Netherlands), wallapop (Spain), medimops (German used-media shop), easycash (French used-goods shop), gamestop (US game shop), craigslist (US classifieds — set CRAIGSLIST_SITE to your city, e.g. newyork), or none to hide the buttons.

Releasing (versioned images)

Images are tagged by version. Pushing a vX.Y.Z git tag builds and publishes ghcr.io/halvar20000/media-vault:X.Y.Z, :X.Y, and :latest. The running version is shown in the app header and at GET /api/health.

To cut a release:

# bump the version in backend/package.json + frontend/package.json to X.Y.Z, commit, then:
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z

Every push to main still publishes :latest, so Unraid's "check for updates" keeps working. Pin a specific version by setting the container's repository to …/media-vault:X.Y.Z.

Tech stack

• Backend — Node.js + TypeScript + Express, PostgreSQL (pg, plain SQL migrations).
• Frontend — React + Vite + TypeScript.
• Packaging — docker-compose (Postgres + backend + nginx). Works behind Cloudflare Tunnel / nginx / Traefik.

Project docs

• docs/INSTALL.md — installation & setup guide (start here).
• docs/CSV_IMPORT.md — the universal CSV format (incl. an AI prompt to fill it from photos).
• CHANGELOG.md — version history (also viewable in-app via the version badge).
• PROJECT_BRIEF.md — founding spec.
• CHAT_SUMMARY.md — design reasoning.
• media-vault-prototype.html — original design prototype.

Feedback and ideas

One shelf in one household is a narrow test. If your collection has a media type, a region, a format or a source this does not handle, that is exactly what is worth hearing.

• Crash, missing artwork, wrong match? Open a bug report — version (click the badge in the header), media type, and the exact title.
• Want something? Say so in Discussions → Ideas, or 👍 an idea already there. The roadmap thread lists what is being considered, and the votes decide the order.
• Setup or API-key trouble? Discussions → Q&A.
• Proud of your shelf? Show and tell is there for it.

License

AGPL-3.0 — anyone who offers this as a network service must share their changes back to the community.