multiplatform
THE standard way a multiplatform.one product deploys on SHC. One app
package (apps/integrated/multiplatform), parameterized per product by
its deployment vars. The canonical definition lives in the multiplatform.one
monorepo (deploy/shc/multiplatform,
https://gitlab.com/bitspur/frappe/multiplatform.one); the catalog entry
is the synced reference copy.
Architecture
Section titled “Architecture”A product deployment is FOUR stacks, wired by plugs/sockets: the multiplatform app bundles neither the bench nor the IdP:
| Stack | Catalog app | Carries |
|---|---|---|
<product> | multiplatform | One-app SSR (web) + single-hostname router (nginx) |
<product>-erp | frappe | the product’s bench image (images.frappe, bakeApps=true): ERPNext + the product’s frappe apps; sites + files state |
<product>-kc | keycloak | the product’s OWN Keycloak (SHC image) + a keycloak/realm vapp for the product realm |
| shared or per-product | mariadb / postgres | the bench DB (via the frappe app’s mysql plug); keycloak’s DB (postgres plug) |
The single-hostname invariant: frappe’s socket.io middleware rejects any
handshake whose Origin hostname differs from Host, so product pages,
desk (/app), API (/api), realtime (/socket.io) and files all live
behind ONE hostname. The in-stack nginx does path routing; the estate’s
Traefik does hostname routing. Route exactly one host, at nginx:8080.
Runbook
Section titled “Runbook”A product is a deployment of the multiplatform package, set entirely by
vars. The catalogue ships no product and no per-product add-on, so
vars.product and vars.images.web are required, like vars.domain.
The shop names below are placeholders. The first line selects the tenant
the product goes into, and every command after it runs in that tenant:
shc ctx -t <tenant>
shc install frappe --stack shop-erp \ --var images.frappe=<registry>/shop/frappe:<tag>@sha256:<digest> \ --var siteName=shop.example.com -i mysql=<mariadb-stack>
shc install keycloak --stack shop-kc -i postgres=<postgres-stack>shc install keycloak/realm --into shop-kc --instance shop \ --var loginTheme=platform-keycloak
shc update shop-erp -i oidc=shop-kc \ --var oidc.connector=frappe_keycloak
shc install multiplatform --stack shop \ -i erpnext=shop-erp -i oidc=shop-kc \ --var product=shop --var bench.kind=erpnext \ --var domain=shop.example.com --var publicUrl=https://shop.example.com \ --var images.web=<registry>/shop/web:<tag>@sha256:<digest> \ --expose shop.example.com=nginx:8080 --publicIn a product repo the same vars live in its deployfile; see the package
README (apps/integrated/multiplatform/README.md). A product whose images
are private brings the docker connection for its registry.
Why a per-product Keycloak
Section titled “Why a per-product Keycloak”multiplatform.one ships its own Keycloak themes and SPIs: your theme on
your realm. Every product deploys its own keycloak catalog-app stack
on the SHC Keycloak image
(registry.gitlab.com/bitspur/selfhosted-cloud/keycloak lineage: the
multiplatform.one bundle: realm management, permissions/role seeding,
floating-menu integration, PAT grant, keycloakify themes; the catalog
pins the SHC-layered build in apps/keycloak/vars.yaml). The catalog
keycloak app is PUBLIC (access: open) by contract: login pages take
no forward-auth gate.
Bring-your-own-Keycloak: allowed, degraded
Section titled “Bring-your-own-Keycloak: allowed, degraded”Any OIDC provider satisfies the oidc plug (point it at an
external-oidc shim, or pin keycloak.issuer). What a plain-upstream
or third-party Keycloak LOSES against the SHC image:
| Capability | SHC Keycloak image | BYO Keycloak / generic OIDC |
|---|---|---|
| OIDC login (web + frappe) | yes | yes (configure the client by hand) |
| Auto client mint + redirect-URI reconcile (oidc socket jobs) | yes | no |
Per-product realm create/import/theme (keycloak/realm vapp) | yes | no: bring your own realm |
| Realm management / role-vocabulary + permissions seeding | yes | no: permissions are not created |
| Floating-menu integration | yes | no |
PAT grant (urn:multiplatform:params:oauth:grant-type:pat) | yes | no |
| multiplatform login theme (keycloakify) | yes | no (ship your own) |
CI deploys
Section titled “CI deploys”Product repos deploy through the shared cicd templates
(bitspur/selfhosted-cloud/cicd, templates/shc-deployfile.yml): the
pipeline rsyncs the app package and runs shc install/shc update over
ssh, binding ONE host at nginx:8080 per environment. Each product’s
contract (stack name, host, env fan-out, vars/images keys) lives in that
product repo’s deployfile.