Skip to content
SHC Docs

builtin/ vs deploy/: the placement axis is UNIVERSALITY, not dependency

Owner ruling, 2026-08-18, verbatim:

“builtin are part of every shc cluster”

“Deploy is where I deploy my custom infra stuff like license marketplace portal etc…”

★ ANSWERED SAME DAY: owner: “Both.” Both packages named “license” move: license-broker/ gets a deployfile (deploy/license-broker.shc.yaml), and the builtin/license app-licence socket is amputated, per the architecture statement below. See “The answer, and what was done” at the end.

The architecture that governs licensing, verbatim (owner, 2026-08-18)

Section titled “The architecture that governs licensing, verbatim (owner, 2026-08-18)”

“SHCD is supposed to handle the cluster side of license… the license management itself, it’s keygen and any custom business logic, custom APIs… is supposed to be on the portal frappe. The marketplace, the portal, those are both backed by the same frappe back end. A license is backed by the frappe back end except for the keygen part. The modules are only for traefik, Keycloak, OpenObserve, and Postgres.”

Consequences, spelled out:

  • shcd owns cluster-side licence ENFORCEMENT (modules/license: the shclic verify/refresh engine, entitlement gates). No estate APP carries licence machinery.
  • The portal Frappe backend owns licence MANAGEMENT (purchase records, custody, vendor APIs, custom business logic), the same bench that backs the marketplace and the portal (deploy/shc/marketplace). Keygen stays its own service beside it.
  • The end state of builtin/ is exactly four packages: traefik, keycloak, openobserve, postgres. license leaves in this lane; branding leaves in its own concurrent lane. Anything else that wants to be a builtin re-litigates against the owner’s sentence above.
  • The builtin postgres is deliberately SEPARATE from the catalogue postgres, for stability: the master-tenant system postgres is pinned to the recorded package digest at install (applySystemAppVersionPin) and never auto-updates when the catalogue postgres moves. One byte-shape, two roles, independent update cadences; the dual nature is the ruling, not an accident to clean up.

The rule, stated once so nobody re-litigates it

Section titled “The rule, stated once so nobody re-litigates it”
treewhat belongs theretest to apply
builtin/<app>packages every SHC cluster carries because the platform itself is made of them, or because any cluster may need to bind themwould a customer’s own estate ever run this?
deploy/<stack>.shc.yaml (+ deploy/shc/<app>)BitSpur’s own infra deployments: marketplace, portal, and the vendor-side licensing planeis this a singleton of the vendor’s SaaS?

The axis is not “does it have dependencies” and not “is it proprietary”. builtin/branding stays where it is: any cluster’s gitea or gitlab plugs into the branding socket, so it is universal even though it is EE-only code. Vendor singletons go to deploy/, whatever they are written in.

deploy/*.shc.yaml is a glob the pipeline discovers (.gitlab-ci.yml, “THE SET IS A GLOB, NOT A LIST”) and it is armed: SHC_DEPLOY_ENABLED is set on this project and marketplace/production carries real deployments. A file landed in deploy/ is a stack this repo’s CI deploys onto the vendor estate. That is the whole meaning of the tree.

What the 2026-08-14 “System-app split” actually ruled, and why

Section titled “What the 2026-08-14 “System-app split” actually ruled, and why”

docs/decisions/2026-08-14-capability-and-backlog-rulings.md, one paragraph:

The catalogue app and the system app split into distinct kinds; “pinned” means the recorded package digest. keycloak/traefik/openobserve/branding become builtin-only system apps invisible to catalogue walkers; postgres keeps its ruled dual nature (builtin AND published catalogue app). The §0.2 materialised-builtin false-red trap dies structurally.

It ruled on VISIBILITY, not on placement. The defect it closed is HANDOFF.md §0.2: catalogue walkers keyed on whether apps/<name>/ happened to exist after make builtin/stage, so a staged tree and a clean tree gave different catalogue answers and a local run could go red on something not in the repo. The fix was to make walkers key on the package’s declared kind: (appcatalog.ScanCatalogue, catalog.CatalogueAppDirs). kind: system is a walker instruction; it never meant “this is vendor infra”.

Today’s ruling therefore does not overturn that one; the two axes are orthogonal. kind: says who may SEE a package; builtin/ vs deploy/ says who RUNS it.

The one package the axis does not resolve mechanically: builtin/license

Section titled “The one package the axis does not resolve mechanically: builtin/license”

builtin/license is the provider behind the third-party app-licence socket (Windmill EE keys, Metabase tokens, plane.so registrations), not SHC’s own entitlement licence, which is modules/license + license-broker/. The two were deliberately kept in separate modules.

Moving it to deploy/ was proposed under this ruling. It cannot be done as a move. Three independent structural facts, each measured against the pinned ce (v0.0.57-0.20260818144102-30dc5d3bd507), not reasoned about:

  1. The LICENSE magic token hard-resolves to (master, default). ce/modules/app/integration_magic.go: magicProviderTenant() returns auth.MasterRealm, MagicProviderEnvironment = "default". Measured: -i license=LICENSE → tenant="master" env="default" stack="license".

  2. Only a registered system app may deploy into master. GuardMasterTenantDeploy rule 1 admits SystemAppSpecs membership only, and app.RegisterSystemApp("license") in modules/applicense/register.go is the sole thing that grants it. Measured with that registration dropped:

    shc install license -t master
    => [X403978SYSTNT] app license cannot deploy into the master tenant,
    master is reserved for SHC's own platform stacks
    -i license=LICENSE still resolves to tenant="master" env="default"
    => [X404906STKNOF] stack license not found in tenant master environment default

    The deployfile happily installs it at (shc, prod), where no consumer can ever reach it.

  3. A deploy/-sourced package is refused in master on provenance. A deployfile’s app: is a directory path, i.e. a path source, and rule 3 refuses operator-supplied packaging in master. Measured:

    shc install ./deploy/shc/license -t master
    => [X403979SYSSRC] platform stack license cannot be installed into the
    master tenant from path, SHC's own tenant deploys SHC's own packaging

So deploy/ and “magic socket provider” are mutually exclusive addresses. A package in deploy/ cannot be a magic provider; a magic provider cannot come from deploy/.

For the record, because it is the risk everyone reaches for first and it is not where the risk actually is:

  • shc install windmill with no -i: unaffected. license.plug.yaml declares required: false. Measured: ValidateRequiredPlugs over windmill with zero integrations names postgres and not license: [X400994PLGREQ] app windmill required plugs not connected, postgres.

  • shc install windmill -i license=LICENSE with no license stack: a hard, coded refusal that names the missing deployment and the command that fixes it, never a silent partial install:

    [X404906STKNOF] stack license not found in tenant master environment default
    hint: install the dependency first with `shc install license -t master`

    The daemon records that string as the stack row’s error_message and the row lands failed (measured live: rows 522/533 on the workstation daemon, both removed afterwards).

That design was already correct on ordering: license was deliberately not in shc init’s install order, and a consumer binding it early got the coded hint. The measurement is kept because it establishes the invariant the amputation must preserve (and does, see the end of this doc): a missing provider is a hard coded refusal, never a silent partial install.

The question below was put to the owner (the ruling’s “license” could mean two packages), and he answered “Both”, with the architecture statement at the top of this doc. Both halves are landed in this lane:

  1. license-broker/ → deploy/license-broker.shc.yaml. The vendor-only activation service now deploys through the same primitive as marketplace. The app package stays at license-broker/app (the SHC-INFRA index publish and the live estate’s repo-qualified updates read that path); the deployfile is the move that matters. Its header records the sequencing trap (do not play the gate before the corp→shc tenant move lands) and the long-term shape: brokerd’s business logic migrates onto the portal Frappe backend; only the signing seed and the shclic mint boundary stay outside Frappe, placement decided in that migration’s own lane.

  2. builtin/license: amputated, not moved. The measurements above are WHY it could not move; the owner’s architecture statement is why it does not survive as an app at all. Removed: builtin/license/ (the nginx provider and license.socket.yaml), modules/applicense (the LICENSE magic token + the license system-app registration + the five mode stubs), apps/enterprise/windmill/license.plug.yaml, the license entry in BUILTIN_APPS, both goreleaser payload blocks, both payload-check assertions, and the arch-fitness floor (6 → 5). BYOL is a plain consumer var: shc install windmill --var license.key=<key>; windmill’s compose already if-guarded on vars.license.key, and the amputated provider’s whole byol-var job was an emptiness check.

    Measured after the amputation: -i license=LICENSE no longer crosses any tenant boundary; LICENSE parses as an ordinary unknown stack and the install refuses hard with X404906STKNOF (no silent partial install); a plain shc install windmill names only postgres in its required-plugs refusal, exactly as before.

    Residual, stated: an estate that had bound a license edge before this lands would re-emit -i license=LICENSE on backup recovery and refuse with the same coded error. No estate carries such an edge (the socket was days old and deliberately not in init’s install order); if one ever surfaces, the repair is to drop the edge and set the var.

  1. Ask “would a customer’s estate ever run this?”: yes ⇒ builtin/ (or apps/), no ⇒ deploy/.
  2. Then ask “is it a magic-socket provider?”; if yes, deploy/ is structurally unavailable to it, whatever the answer to (1). Magic providers live at (master, <stack>, default), and that address only accepts SHC-shipped packaging registered through app.RegisterSystemApp.
  3. Then ask “is it licensing machinery?”; the owner’s architecture statement above already placed all of it: enforcement in shcd, management on the portal Frappe backend, Keygen beside it. No new licensing app, builtin or catalogue, without superseding that statement.