LibrePortal/docs/roadmap/marketplace-website.md

# LibrePortal Marketplace — the marketplace app (Roadmap / Design)

**Status:** direction decided 2026-07-03 (container MVP planned; submissions phase 2) ·
**Audience:** us, future-self · **Scope:** the browsable marketplace *system* — the
apps.nextcloud.com analogue — shipped as a LibrePortal app, and how community
submissions eventually flow through it · Builds on `updates-and-distribution.md` §3/§8.

---

## 1. The decided shape: the marketplace is a LibrePortal app

The marketplace server ships **in this repo as `containers/libreportal-marketplace/`**
— a normal app definition installed through the normal pipeline, with one twist:
it is **dev-mode-only** (see §4). The official `marketplace.libreportal.org` is
simply *our* instance of this app running on our own box — full dogfooding — and
anyone who wants their own marketplace enables Developer Mode and installs the
same app. "Open source and self-hostable" is therefore not a promise, it's the
literal distribution mechanism.

The marketplace has two user-facing surfaces over **one source of truth**:

```
                    ┌────────────────────────────────────────────┐
                    │  THE SIGNED CATALOG (the source of truth)  │
                    │  <base>/<channel>/index.json (+ .minisig)  │
                    │  <base>/<channel>/payloads/<id>.tar.gz     │
                    └───────────┬───────────────────┬────────────┘
                                │                   │
              boxes fetch + verify it        the marketplace app
                                │              serves + renders it
                 ┌──────────────▼─────────┐  ┌──────▼──────────────────┐
                 │ IN-APP (every box)     │  │ libreportal-marketplace │
                 │ App Center grid shows  │  │ (dev-mode app): hosts   │
                 │ "Available — Add"      │  │ the catalog tree + a    │
                 │ cards; Add = task →    │  │ browsable website:      │
                 │ verify → drop-in       │  │ browse, search, per-app │
                 └────────────────────────┘  │ pages, submit info      │
                                             └─────────────────────────┘
```

Boxes never talk to the website and never trust it — they only trust the
minisign signature on the catalog. A marketplace instance can be compromised,
defaced, or down and no install is ever at risk. That property is load-bearing;
every choice below preserves it.

## 2. What the container serves

One app, one docroot, two things in it:

- **The catalog tree itself** — `/<channel>/index.json(.minisig)` +
  `/<channel>/payloads/…`, exactly the layout `make_app.sh` / `make_hotfix.sh`
  emit into `dist/`. A box pointed at this instance via `CFG_RELEASE_BASE_URL`
  consumes it directly.
- **The browse UI** — static pages (no third-party assets, same rule as the
  WebUI) rendered **client-side from the same `index.json`**: front page by
  category, search, one page per app (title, description, icon, publisher +
  trust badge, version), a copyable `libreportal app add <slug>` snippet, and a
  "run your own marketplace" page documenting exactly this app + the
  `CFG_RELEASE_BASE_URL` knob. Client-side rendering means the UI needs no build
  step and can never disagree with the catalog it serves.

**No backend.** No accounts, no database, no API server in the MVP. Publishing
*to* a marketplace = running the publisher tools and syncing their `dist/`
output into the app's docroot (its bind-mounted data dir).

**Server:** `nginx:alpine` static serving (the pattern the retired
`getlibreportal` container established: JSON no-cache, tarballs/sigs immutable).
Traefik routing, ports, backup labels — all standard app-definition machinery.

## 3. Community submissions (phase 2 — the F-Droid flow, not the Play flow)

When community apps open up (demand-gated, per `updates-and-distribution.md`
§8.5 fork 4), submission is a **pull request, not an upload**:

1. Author PRs their app folder (`containers/<app>/` shape — the drop-in contract
   in `docs/contributing/development.md`) to a public catalog repo.
2. CI validates mechanically: the bundle tarball contract, compose lint, no
   host-script hooks unless flagged for review, icon/meta present.
3. A maintainer reviews — *especially* any `tools/*.sh` (the one genuinely
   dangerous surface, §3.2) — then signs and publishes with the same tools used
   for first-party apps. The entry lands in the index with `publisher:<author>`,
   `trust:"community"`.
4. The marketplace site renders the submission queue from the PR list (links,
   not accounts) and the published result from the index.

Everything ends in "reviewed → signed → one public catalog" because the boxes
only trust the signature. An account-based submission portal could be added to
the marketplace app later, but it would only ever be a nicer way to open the PR
— it can never become an unreviewed upload channel.

## 4. Dev-mode gating (the important part)

The marketplace app must not confuse regular users browsing their App Center —
running a marketplace is an operator/developer act. So it ships **hidden unless
Developer Mode is on**, riding the existing `CFG_DEV_MODE` machinery (10-click
logo easter egg; auto-enabled on git/local installs):

- New app-level convention: `CFG_<APP>_DEV_ONLY=true` in the app's `.config`.
- `webuiGenerateLibrePortalConfig` emits it as `dev_only: true` in `apps.json`.
- The App Center filters `dev_only` apps out of the grid/search unless
  `window.systemConfigs.CFG_DEV_MODE === 'true'` (the same flag the `**DEV**`
  config-field filter uses — see `field-factory.js` `_filterDevKeys`).
- The CLI stays honest: `libreportal app install libreportal-marketplace` works
  regardless (dev-only is decluttering, not a security boundary — the security
  boundary is the signing key, which the app never contains).

The convention is generic — any future operator-grade app (build servers, relay
infrastructure) can reuse it.

## 5. Explicitly not doing

- **No dynamic marketplace backend** (accounts / uploads / ratings) in the MVP —
  re-affirming §3's decision; nothing in the in-app UX needs it, and phase 2
  submissions stay review-and-sign whatever front door exists.
- **No telemetry** on the marketplace site (same rule as the product); download
  counts, if ever wanted, come from static server logs on *our* instance only.
- **No website-only metadata.** If the site needs a field (e.g. screenshots
  later), it enters the catalog format as an optional envelope/`meta` addition
  so in-app and website stay one source of truth.

## 6. Sequencing

1. **Now:** the in-app registry slice (`updates-and-distribution.md` §8.7) —
   catalog format gains `meta` (category/description/icon), `make_app.sh`
   publishes app bundles. The catalog becomes real.
2. **Now (after the publisher tool exists):** `containers/libreportal-marketplace/`
   MVP — nginx app serving the catalog tree + client-rendered browse UI, plus
   the `CFG_<APP>_DEV_ONLY` gating convention. End-to-end tests then run against
   a real marketplace instance instead of `python3 -m http.server`.
3. **Demand-gated:** the community submission flow (public catalog repo + CI
   validation + review/sign tooling), yellow-tier rendering, and the in-app
   community trust-tier UX (host-script quarantine — §8.7 deferred).