Skip to content
SHC Docs

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.

A product deployment is FOUR stacks, wired by plugs/sockets: the multiplatform app bundles neither the bench nor the IdP:

StackCatalog appCarries
<product>multiplatformOne-app SSR (web) + single-hostname router (nginx)
<product>-erpfrappethe product’s bench image (images.frappe, bakeApps=true): ERPNext + the product’s frappe apps; sites + files state
<product>-kckeycloakthe product’s OWN Keycloak (SHC image) + a keycloak/realm vapp for the product realm
shared or per-productmariadb / postgresthe 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.

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:

Terminal window
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 --public

In 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.

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:

CapabilitySHC Keycloak imageBYO Keycloak / generic OIDC
OIDC login (web + frappe)yesyes (configure the client by hand)
Auto client mint + redirect-URI reconcile (oidc socket jobs)yesno
Per-product realm create/import/theme (keycloak/realm vapp)yesno: bring your own realm
Realm management / role-vocabulary + permissions seedingyesno: permissions are not created
Floating-menu integrationyesno
PAT grant (urn:multiplatform:params:oauth:grant-type:pat)yesno
multiplatform login theme (keycloakify)yesno (ship your own)

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.