The Portal: architecture, RULED 2026-08-14
Status: open design. The 2026-08-14 rulings stand, and the portal is not built in this repo. Every item marked (ruled) was decided by the owner in the 2026-08-14 architecture Q&A, quoted where his words carry the definition. (design) items are elaboration consistent with the rulings. Companion doc:
2026-08-14-marketplace-architecture.md; the two products share an identity, a Keygen spine, and the registration gate defined here.
2026-08-16: superseded in part. Who is logged in where, and how a click in a cluster console becomes an install, is ruled in
../decisions/2026-08-16-marketplace-identity-and-install.md: three populations (anonymous browsers · central accounts own purchases · cluster tenant users do installs), entitlement follows the cluster not the person, federation is one-way only (our IdP into a customer master realm; the reverse is refused), and §4’s linked-out consoles are carried by a short-lived daemon-minted signed assertion rather than a bare link. Four questions there remain open for the owner, including whether free installs require a portal account at all, which decides whether a per-cluster storefront surface has to exist.
1. What it is (ruled)
Section titled “1. What it is (ruled)”The Portal: the centralized product at my.selfhostedcloud.org
(name “portal”, host my., an explicit owner exception to the
name-the-service hostname rule the license./marketplace. hosts established).
“The point of the portal is registering your clusters.” It is the third
*.selfhostedcloud.org product, run by us, never self-hosted.
Functions: central accounts · cluster registration · fleet view · marketplace install dispatch · support bundles · license/billing self-serve · cloud provisioning.
2. Identity (ruled)
Section titled “2. Identity (ruled)”2026-08-16: extended and constrained by
../decisions/2026-08-16-portal-cluster-identity.md. The carve-out below now serves many portal users per cluster, strictly by federation: the portal never creates users in a customer’s Keycloak. That decision record also defines the L0/L1/L2 compliance ladder (the customer can seal the cluster by deleting the IdP entry, and we structurally cannot undo it) and rules purchasing authority as request-and-approve.
Keycloak accounts managed by selfhosted-cloud (the multiplatform.one pattern), shared with the marketplace, one Apple-ID-style login across both.
Federation carve-out: master realm only (ruled, refined 2026-08-14):
registering a cluster federates the Portal’s vendor IdP into the cluster’s
master Keycloak realm only: “you can login to your cluster to your master
keycloak realm using your portal username. but all users on your system would
be in your keycloak.” The cluster’s users live entirely in the cluster’s own
Keycloak; the portal identity is operator access, established at registration
and removed at deregistration. Because the sso entitlement gates external
IdPs for user realms, the gate is untouched: free accounts still have
user-facing SSO off. Enforcement (design): the FederationGuard carries one
named exemption, provider == the vendor portal IdP AND realm == master,
never a general weakening.
Placement (ruled): ce definitively does not support portal registration or federation. The whole cluster-side portal surface, registration agent, outbound channel, master-realm federation, support-bundle grants, is shc-proprietary, like the branding and license sockets.
3. The registration gate (ruled)
Section titled “3. The registration gate (ruled)”- Registration is the key that unlocks the centralized services: no registration → no marketplace, no support bundles.
- Airgapped estates get no marketplace, “unless they explicitly open up on their end our ips and register it.” Registration stays optional in every tier (an unregistered cluster is fully operable; self-hosted premise intact).
- Portal-provisioned clusters are born fully registered with full support-bundle access, “because it’s managed shc.”
4. Cluster channel (ruled)
Section titled “4. Cluster channel (ruled)”- Agent-initiated outbound persistent channel: the daemon opts in
(
shc portal register <code>(design: verb name)) and maintains an outbound connection carrying heartbeats up (version, health, license posture, app inventory) and install dispatch + catalog queries down. The Portal holds no cluster credential; works behind NAT/LAN. - v1 capability ceiling: status + install dispatch. No general admin verbs (upgrade/restart/etc. arrive later behind scoped tokens; the daemon-side PAT/token mint is the prerequisite product gap).
- Consoles are linked out in new tabs, never embedded, consistent with the no-iframe ruling; cluster admin stays on cluster credentials.
5. Support bundles (ruled)
Section titled “5. Support bundles (ruled)”Customer-enabled, two consent modes:
- One-off, rotating code: the cluster displays a constantly-rotating code; the customer reads it to support; a staff member enters it in the Portal dashboard and may pull one bundle that time.
- Standing full access: the customer grants it once; support may pull bundles whenever needed. Managed clusters have this by definition.
6. Provisioning (ruled)
Section titled “6. Provisioning (ruled)”- Phase order: register → provision → managed.
- Provision v1: the Portal runs Terraform (our shipped
terraform/modules/shc/*+ provider) with the customer’s own cloud credentials. - Managed (later): “there will be a day when i also support us managing all the infra on our side completely. of course that will have an upcharge on all the infra provisioned.”
- Custody: customer cloud credentials and Terraform state (which contains the cluster SSH key and vault password; custody of state is custody of the cluster) live in a dedicated OpenBao/KMS, not the estate vault and never the bench database.
- Cloud allowlist at launch: the LIVE six: hetzner, aws, azure, digitalocean, scaleway, exoscale. Every further cloud earns its way in via a live-exercise pass (PROVIDER-MATRIX honesty: 3 modules have no reaper, hostinger’s firewall var is a silent no-op; those never ship push-button until fixed).
7. Billing (ruled)
Section titled “7. Billing (ruled)”The Portal is the self-serve purchase/license front-end that drives ERPNext + Keygen; the Sales Invoice stays the source of truth, Keygen stays the entitlement store, processors are pluggable underneath (Hyperswitch the likely orchestrator). Deep Keygen integration: registering a cluster binds its domain into the appropriate paid tier; Keygen also carries store-sold app licenses; the Portal proxies third-party license systems where vendors permit (see the marketplace doc §5 brokerage modes).
8. Free/paid line (ruled, declared now per the TIERS no-rug promise)
Section titled “8. Free/paid line (ruled, declared now per the TIERS no-rug promise)”- Free: one registered cluster: fleet view, marketplace installs, one-off support codes.
- Paid: multi-cluster fleet views, provisioning, standing full-access support bundles.
- Refinement (2026-08-14): the permanent free tier carries no launcher menu and no SSO into apps; a registered free cluster still gets portal SSO into the master realm (admin access). Likely funnel (directional): Hobby free for the first 3 months so users experience app-SSO.
- Cross-cluster navigation is portal-only: the Portal logs you into any of your consoles; a console never switches to another console (ruled).
9. Stack (ruled)
Section titled “9. Stack (ruled)”All portal-side logic on Frappe. The owner explicitly declined a separate Go broker service. (design) The realtime channel rides Frappe’s socketio sidecar or long-poll against bench endpoints; Terraform runs as background jobs with state/credentials fetched from OpenBao per-run. Whether the Portal shares the marketplace’s m1-template bench or gets a sibling bench is an open operational detail (shared presumed; one backend, two hostnames).
10. Owed work (build list)
Section titled “10. Owed work (build list)”- Central Keycloak realm (shared with marketplace) + Frappe portal app: accounts, cluster registry doctypes, dashboard.
- Daemon-side registration agent + outbound channel, in shc, never ce (ruled), heartbeat schema, install-dispatch + catalog-query verbs, master-realm federation edge lifecycle.
- Support-bundle machinery: rotating-code surface on the cluster, dashboard redemption, standing-grant flag, bundle transport.
- Keygen tier-binding on registration; self-serve billing front-end over ERPNext/Keygen; Hyperswitch spike.
- OpenBao/KMS deployment + per-customer scoping.
- Terraform runner (background jobs, LIVE-six allowlist, reap-on-failure);
publish the terraform provider + pkg/apiclient (today a
replace ../shcdev pin, a hard prerequisite). - Managed-infra phase: vendor cloud accounts, infra upcharge metering.