Skip to content
SHC Docs

Marketplace architecture: RULED 2026-08-14

Status: open design. Ruled on 2026-08-14. The marketplace app is in the repo (apps/marketplace), and the portal-dependent items are not closed. Every item marked (ruled) below was decided by the owner in the 2026-08-14 architecture Q&A, in his own words where quoted. Items marked (design) are elaboration consistent with the rulings but open to revision. Items marked (portal-dependent) cannot close until the portal lane’s rulings land. This is the marketplace’s first design document; before it, every marketplace decision lived only in code comments, READMEs and handoffs.

2026-08-16: extended. The identity and install model this doc left open is ruled in ../decisions/2026-08-16-marketplace-identity-and-install.md. Read it before implementing §1 (no-iframe; a second, browser-level reason is recorded there), §2 (accounts own purchases is extended by entitlement follows the cluster, not the person), or §6’s install path (the store learns which cluster from a daemon-minted, cluster-bound, single-use assertion carried on the new-tab link, no cluster picker). It also rules that users may add repos via the CLI but never the marketplace, records that SHC does not currently store who installed a deployment (verified against ce), and leaves four questions open for the owner.

The App Store analogy, verbatim intent: “just like with apple app store you have to login to the marketplace with your own credentials. kinda like you can access an iphone but not the app store until you’re logged in.”

  • The cluster is the iPhone, fully usable without the store.

  • The marketplace is the App Store, centralized at marketplace.selfhostedcloud.org, run by us, login required (central account) for anything beyond browsing.

  • Portal registration is the CHANNEL (ruled; amended 2026-08-16): an unregistered cluster cannot use the marketplace (or support bundles). Airgapped estates get no marketplace unless they explicitly open our IPs and register. See 2026-08-14-portal-architecture.md §3.

    ★ AMENDED 2026-08-16: registration is no longer the whole gate. As written above, and as shipped, registration was the ONLY condition on using the store, and registration is optional and available in every tier, so a free estate that registered could install from the marketplace. The owner then ruled the store FREE TO BROWSE and HOBBY TO INSTALL (he was offered “make the whole store a Hobby entitlement” and rejected it for this split). Registration is now the CHANNEL and the licence is the PERMISSION: browsing needs neither, a store-dispatched install needs both. The single account of the rule is ../../TIERS.md → The marketplace line; this bullet points there rather than restating it, because two accounts of a pricing rule is how the four contradictory copies in modules/portal came to exist.

  • Clusters reach it in a new tab, never an iframe: “it comes from marketplace.selfhostedcloud.org not an iframe. it opens in a new tab like everything else.”

Consequences (ruled by implication, retirements owed):

  • packages/marketplace-bridge (postMessage v1, iframe-only-asks) is retired. The principle survives (cluster daemon credentials never enter the store); the iframe does not.
  • The console /apps dock (cb8a125f1, iframe embed) becomes a plain new-tab link. The CONSOLE_WEB_URL / MARKETPLACE_WEB_URL origin-pin pair and frame-ancestors machinery go with the bridge.
  • The GitLab Pages catalog at selfhostedcloud.org/apps is removed completely: “everything is through the marketplace.” Keep a redirect for inbound links; retire the Pages build.

2026-08-16: see ../decisions/2026-08-16-portal-cluster-identity.md for who administers a registered cluster: many portal users per cluster by federation only, the L0/L1/L2 compliance seal, and the ruling that a paid-app purchase a cluster is not entitled to creates a request the registering portal account approves. Entitlement still rides the cluster; the approval is a billing act in the portal, so it survives a sealed cluster untouched.

“the portal and marketplace accounts are keycloak accounts managed by selfhosted cloud” (the multiplatform.one pattern). One central identity serves portal and marketplace.

  • You register clusters against your account (portal function).
  • Registration wires Keygen: the registered cluster’s domain is placed into the appropriate Keygen tier based on what was paid: “there’s a deep integration between this portal and keygen.”
  • Keygen also carries licenses for first-class paid apps sold in the store.
  • The portal/marketplace additionally proxies third-party license systems: “at least the 3rd party ones that will let me” (see §5).
  • Entitlement binding (design, follows from the above): accounts own purchases; the portal claims them onto registered clusters by writing the cluster domain into the right Keygen tier/policy. This extends, not replaces, the proven domain-bound broker machinery (license-broker → Keygen → shclic.v1).
  • Backend: a dedicated small Frappe bench stack built from the multiplatform.one template bench (core + frappe_keycloak + live) with frappe/apps/marketplace added, baked as a digest-pinned tarball (the frappe_keycloak pattern). Its own stack, never the corp ERPNext bench, not static JSON.
  • Seeding: import_catalog.py runs on release tags, so listings always describe an installable release. (design) Add a dry-run of the seeder on main pushes; a tag-only job otherwise gets zero non-tag exposure (HANDOFF §0.4 trap).
  • Go-live: SHC_DEPLOY_ENABLED is armed only after the bench serves data. The shc deploy verb is not a prerequisite; CI-side rendering is the shipped path (deployfile proposal §5.5).

The v1 target is the full paid-app program, with one absolute rule: open-source apps are never sold through the store.

  • Publishing: vendor portal, staged: self-serve developer accounts submit packages through a review queue (invite-only first). The existing guard apparatus (taxonomy, license doctrine, pin-liveness, fitness) is the automated half of review; human approval is the other half.
  • Payments: a pluggable payment layer: “keep things flexible … prob hyperswitch is the best route”. Hyperswitch as the likely orchestrator; ERPNext-direct provider integrations as an alternative; Stripe Connect acceptable behind the abstraction. Revenue share on store-native sales (percentage TBD).
  • Metering: a flexible YAML meter spec per app. Meterable signals: anything SHC has information on (deployments, seats, nodes, …) plus an SHC API apps push their own metrics into (“like x rows in a given table”). Strategies all supported: one-time, subscription, per-seat, usage-metered, per-deployment.
  • The store’s own money path connects to the existing mint pipeline (ERPNext Sales Invoice → license-broker /record → Keygen → domain-bound license) rather than growing a parallel one (design).

5. License brokerage: upstream commercial licenses (ruled)

Section titled “5. License brokerage: upstream commercial licenses (ruled)”

For apps whose upstream sells its own license (GitLab, SonarQube, PostHog, plane.so, …), the store supports all three modes:

  1. BYOL: the user provides the license; we provision it (usually a deployment var; largely supported today).
  2. Custodial: “we purchase it and provision for them and we custodian the license”, held in our DB when it is not a key at all but a vendor-side registration (plane.so-style: “you give plane the domain, we do that”).
  3. Vendor-API auto-provision: “I want the marketplace built where we can auto provision for platforms that support it and provide apis to do so.” Vendors that do not permit third-party provisioning are simply not brokered.

Mechanism (ruled): a first-class license plug in app.yaml declaring the mode(s) and the provisioning recipe (env var / license file / vendor domain-registration / vendor API), plus the licensing audit’s requires_paid_license boolean + reason so listings badge honestly (“commercial license, available through us”).

Placement (ruled, 2026-08-14): the license socket is implemented in shc, not ce, a proprietary magic socket in the OTEL/branding mold (the branding socket set this exact precedent: shc-side after a revision wrongly said CE). ce never carries the license-brokerage machinery.

  • Install path: the store pushes via the portal: a logged-in user picks one of their registered clusters and the install dispatches over the portal↔cluster channel (portal-dependent: the channel’s shape).
  • Version gap: the store overlays per-cluster truth: it queries a registered cluster’s actual catalog/version through the portal channel and disables or caveats Install per cluster up front (portal-dependent).
  • Reviews from day one, tied to central accounts (moderation accepted).

7. Owed work (build list, roughly ordered)

Section titled “7. Owed work (build list, roughly ordered)”
  1. Marketplace bench stack (m1 template + marketplace bench app, tarball bake), prod MARKETPLACE_API_URL/edge wiring, seeder on release tags + dry-run on main. Then arm SHC_DEPLOY_ENABLED.
  2. Retire the iframe path: bridge package, console dock → new-tab link, frame-ancestors machinery. Replace ContactForm.tsx stub.
  3. Remove the Pages /apps catalog; redirect apex /apps → marketplace.
  4. app.yaml: license plug schema + requires_paid_license + reason; seeder forwards them; storefront badges.
  5. Central identity realm (portal lane owns sequencing) → store login.
  6. Portal↔cluster channel: install dispatch + catalog-query (portal lane).
  7. Payments abstraction (Hyperswitch spike), vendor portal + review queue, meter-spec YAML + metrics-push API, Keygen policy layout for store apps.
  8. Reviews (accounts + moderation).

apps/marketplace stays a FRONTEND_APP, never a bucket (taxonomy guard); TIERS.md’s no-rug promise: no paid gate on currently-free catalog installs; open-source apps never sold (ruled, this doc); flagship-payment-axis ruling governs posture presentation; the deployfile’s domain/prod-only/manual-promote choices stand.