Skip to content
SHC Docs

Custom builds

Most of the catalog pins unmodified upstream images. A small number of apps and system services run images SHC builds itself, and this page is the registry of them: what each build adds, where its source lives, how it is rebuilt, and what its license asks of a distributor. None of them lifts a seat cap or a licence check by patching: the forks add sign-in or packaging, and the one that exists because of a cap (affine-rs) is a server written from scratch.

Two rules shape everything here:

  1. The catalog is pull-only. No app carries a compose build: stanza: a build context would have to exist on every node a stack lands on, two replicas of one “version” could run different bytes, and images: would stop describing what is deployed. Every custom build is produced out-of-band, published to a registry, and consumed digest-pinned exactly like a third-party image. The Dockerfile in the repo is the record of what the image contains, not a node-side build instruction.
  2. A custom build needs a reason upstream cannot provide. The reasons in practice are two: zero-touch SSO (the integration works at install time, with no manual step; see the SSO coverage policy), and capability gaps upstream will not close (or has removed; see licensing postures).

Every estate’s identity provider is a custom Keycloak image, built from keycloak/docker/Dockerfile in the SHC repo and published to registry.gitlab.com/bitspur/selfhosted-cloud/shc/keycloak. The ce keycloak addon consumes it by digest.

What it is. A thin layer over the multiplatform.one Keycloak bundle (registry.git.corp.bitspur.com/multiplatform.one/mpo/keycloak, digest-pinned). The pinned base already carries three extensions SHC’s packaging depends on: a personal-access-token SPI (the urn:multiplatform:params:oauth:grant-type:pat grant and a /realms/<realm>/pat endpoint), the keycloakify theme, and siwe-keycloak. SHC adds two files and re-augments the server: its own SPI jar (keycloak/spi/, compiled in the build) and its admin theme (keycloak/themes/shc). Nothing else moves: the image is “the pinned base plus our jar plus our theme.”

The LDAP facade. The base image also bundles an LDAP face (MyVD) and a Kerberos face (vKDC). The shipped packaging hard-disables both through compose environment flags, so no estate serves LDAP today. The LDAP face is capable, and packaging it as a proper ldap socket is design work in flight; see the LDAP fallback proposal for what exists, what is missing, and why it is off. Treat LDAP-from-Keycloak as a direction, not a feature.

Rebuild cadence. CI builds the image on every pipeline (docker buildx bake, per-commit tags); consumers move only when the addon’s digest pin is bumped deliberately. A base-digest bump is a coupled change: the SPI compiles against a declared Keycloak version, and compiling against a different minor than the one it runs on is how a NoSuchMethodError reaches an estate, so the base digest and the SPI’s Keycloak version move together.

License. Keycloak upstream is Apache-2.0 (verified against the project’s LICENSE.txt). Apache-2.0 permits redistributing modified builds and does not require publishing extension source; it requires the license text and notices to travel with the distribution. The SHC SPI and theme are first-party code carrying no copyleft obligation.

apps/devops/frappe pins registry.gitlab.com/bitspur/selfhosted-cloud/shc/frappe (see apps/devops/frappe/vars.yaml), built from frappe/docker/Dockerfile in the SHC repo.

What it is. The digest-pinned upstream frappe/erpnext v15 bench, plus the frappe_keycloak app cloned at a pinned commit and installed into the bench virtualenv at build time. That one addition is the point: SHC’s Frappe OIDC plug depends on an app the upstream image does not carry, and installing a Python app into a live, preloaded gunicorn cannot be made reliable: the interpreter’s import path is fixed at boot, so a runtime install needs a restart and opens a window in which every request fails. Baking the app dissolves the window: the code is on disk and importable before the interpreter ever starts, so OIDC works at install with no manual step. The build asserts its own guarantee: it imports the app with the exact runtime interpreter and records a version manifest (/opt/shc/frappe-apps.json) tied to the pinned commit.

Source. frappe_keycloak is a private repo: git.corp.bitspur.com/multiplatform.one/keycloak. The Dockerfile pins its exact commit; bumps are deliberate, never a branch chase.

Rebuild cadence. The base digest in the Dockerfile and images.frappe in apps/devops/frappe/vars.yaml are two halves of one decision and move together. The image stays on the v15 line deliberately: Frappe v16 requires a newer Python than the base ships, so that hop is an interpreter migration, not a tag bump.

License. Frappe Framework is MIT and ERPNext is GPL-3.0 (both verified against the upstream license files); frappe_keycloak is Apache-2.0 (verified against its repo). Publishing this image distributes GPL-3.0 code, so the GPL’s source-availability condition applies: the ERPNext in the image is the unmodified upstream release at a digest-pinned base whose source upstream publishes, and everything SHC adds comes from the public Apache-2.0 repo above at a commit the image manifest records. Nothing in the image is source-unavailable.

SHC maintains a soft fork of Huly (hcengineering/platform): a numbered patch series applied to a pinned upstream release, adding integration capabilities the platform does not expose: environment-driven wiring for integration services and on-behalf mail identities, plus small model fixes. Built images are tagged <ref>-fork-<commit>, so a fork build is always distinguishable from the upstream release it derives from.

Shipping rule: the fork is a per-deployment override, never a catalog pin. apps/standalone/huly pins unmodified upstream hardcoreeng/* images and sets none of the environment variables the patches introduce, so a plain shc install huly / shc update huly runs stock Huly. Fork images live under registry.gitlab.com/bitspur/selfhosted-cloud/huly/<pod>:<ref>-fork-<commit> (amd64-only today) and estates that want them pass --var images.<pod>=… at install/update time. Putting those refs into the public catalog would make every non-amd64 estate uninstallable.

CI coverage for tag-only pins. The catalog’s deliberate tag-only refs (huly’s upstream train, greenbone channel tags) are probed by make apps/verify-pins (cmd/verify-image-pins): that gate extracts tag-only images: values alongside @sha256 digests and asks each registry whether the tag still resolves. A broken tag-only fork pin written into the catalog would fail the publish job, which is why the shipping rule and the probe are a pair, not alternatives. Digest-pinning the fork into the catalog is not the fix.

License. Huly is EPL-2.0 (verified against the platform repo’s LICENSE). EPL-2.0 is file-level copyleft: distributing modified builds in object form requires making the source of the modified files available and identifying the changes. A published patch series satisfies that by construction: each patch names its files and is the change. That is the copyleft-fork rule in licensing postures applied: when SHC soft-forks copyleft software, the fork source is public.

apps/integrated/fizzy pins registry.selfhostedcloud.org/shc/fizzy, built by the corp CI of selfhostedcloud.org/fizzy (public): upstream basecamp/fizzy plus a short commit series on top.

What changed. OIDC sign-in, taken from upstream’s open pull request #2370 and made to work against Keycloak (issuer discovery, the redirect on iOS, a rate-limit setting), and OIDC_REQUIRED, which removes every magic-link door so the estate’s Keycloak is the only way in. API access tokens keep working with OIDC_REQUIRED on, and the fork’s tests hold that.

Why. Upstream Fizzy signs people in by e-mailed magic link only. That is no SSO at all, and an estate’s apps sign in through its tenant realm.

License. O’Saasy (LicenseRef-OSaasy-1.0, read from upstream’s LICENSE.md): MIT terms plus one condition. Nobody may offer Fizzy to third parties as a hosted or SaaS product whose primary value is Fizzy itself. The fork changes nothing about that, so self-hosting Fizzy for your own organisation is fine and selling Fizzy hosting is not. The store shows the condition on the app page (license.no_saas).

affine-rs: a new server, not a patched one

Section titled “affine-rs: a new server, not a patched one”

apps/integrated/affine-rs runs AFFiNE’s MIT client against a server SHC wrote from scratch in Rust, built from selfhostedcloud.org/affine (public) and pinned as registry.selfhostedcloud.org/shc/affine-rs.

What changed. Everything on the server side. The Rust server speaks the wire protocol the MIT client already speaks (the fork’s docs/wire-contract-v1.md, frozen at v1.0.0). The client is AFFiNE v0.27.3’s MIT frontend with a small patch series on top.

Why. Upstream’s server tree (packages/backend/** and packages/common/native/**) is under the AFFiNE Enterprise Edition Licence. Its free self-host plan caps a workspace at 10 members, and past that the whole workspace goes read-only. affine-rs has no seat concept, so it has no cap to lift.

What it never touches. Neither EE directory has ever been fetched into the fork. Its clone is a sparse checkout that leaves both paths out, and scripts/check-provenance.sh asserts that on every build. Nothing in the stack reads, emulates or calls AFFiNE’s licence checks. This is the line licensing postures draws: writing the capability yourself is not fork-enabling someone else’s enterprise code.

Where it ships. House only, by Clay’s 2026-10-31 ruling: it’s hidden from the store, and it leaves the public install index once the house has a private one (FZ-8130). The upstream affine package stays the store’s AFFiNE.

License. MIT, server and client alike.

apps/flagship/activepieces pins registry.selfhostedcloud.org/shc/activepieces:0.88.3-fork, built from a patch series (0001-0005) on upstream’s 0.88.3 tag in selfhostedcloud.org/activepieces (public). The fork image is the package default.

Build. In that repository, make image fetches upstream at the tag in UPSTREAM, applies the series and builds. make push checks the image carries the fork and refuses a tag the registry already holds. Corp CI runs the same steps on every push to main and publishes one immutable tag per build, which the package pins with its digest.

What changed. Native OIDC sign-in, added to the MIT auth module (0001-0003). An OIDC sign-in provisions its user without an invite while open sign-up stays closed (0004), and the image build reads Debian bullseye’s apt sources from archive.debian.org (0005). Upstream’s own SSO (SAML, Google) lives in packages/ee/ and packages/server/api/src/app/ee/ under a commercial licence, and the fork neither reads nor enables any of it.

What did not change. Community Edition’s collaboration limits stay as upstream ships them: every CE project is personal, shared team projects cap at one, and project roles stay off. The fork adds a sign-in door and lifts no cap.

Why. Community Edition has no SSO of any kind, so without the fork every estate would land on e-mail and password.

License. MIT outside the ee trees. MIT asks for no source, but the patch series is public like every other fork’s here, so anyone can check what changed.

apps/flagship/openreplay pins two SHC images from selfhostedcloud.org/openreplay (public), a thin patch overlay on the AGPLv3 community build: shc/openreplay-chalice and shc/openreplay-spot. Every other OpenReplay service is upstream’s CE image.

What changed. chalice, the API, gets an OIDC login router for Keycloak, built only from helpers in the AGPL community tree. No ee/ file was read, copied or derived from, and the image still reports ENTERPRISE_BUILD=default-foss. spot gets a capped backoff on its job claim loop (FZ-8381).

Why. OpenReplay’s only SSO is SAML2 in the separately licensed ee/ tree, behind a licence key. OIDC is a different protocol written from the open tree.

License. AGPL-3.0, so the public fork repo is the source offer (section 13). The package’s tests fail if chalice is ever pointed back at upstream, because the OIDC wiring would render and then 404.

apps/standalone/pulp pins registry.selfhostedcloud.org/pulp/pulp and registry.selfhostedcloud.org/pulp/pulp-ui, both tagged -fork-<commit> and built from selfhostedcloud.org/pulp (public). Like Huly, upstream is never committed there: make stage clones each pinned upstream and applies its patch series.

What changed. Three things. pulp_sso turns the edge’s Keycloak verdict into a Pulp user, with roles from Keycloak groups, as a separate package beside pulpcore rather than a patch to it. pulp_mirror publishes chosen apt, file and container distributions as static trees to S3-compatible buckets, which is what makes registry.selfhostedcloud.org a bucket. And pulp-ui gets a session-auth mode plus a plugin browser that shows every plugin the server reports, not the four upstream wrote screens for. pulpcore itself carries no patch.

Why. Upstream’s dashboard signs in with HTTP Basic and keeps the admin password in browser storage, and upstream publishes no dashboard image at all. The mirror is how the house serves its apt repos and images from R2.

Where it ships. House only, by Clay’s 2026-11-01 ruling: the house runs it as its artifact mirror. It’s hidden from the store, and it leaves the public install index once the house has a private one (FZ-8130).

License. pulpcore is GPL-2.0-or-later and pulp-ui is Apache-2.0. The images are public, so the GPL’s source condition applies, and the public fork repo meets it.

For completeness, the remaining images SHC builds, system services rather than catalog apps, all built from Dockerfiles in the SHC repo by the same CI job:

ImageWhat it isWhy custom
shc/traefikUpstream Traefik plus SHC’s local Yaegi plugin, baked inA non-local Traefik plugin is fetched from GitHub at proxy startup: unacceptable on the boot path of the edge, and incompatible with airgapped installs. Baking the plugin source removes the fetch and the third party.
shc/collectorA minimal custom OpenTelemetry Collector distroShips only the components the telemetry fabric uses, from a declared component inventory.
shc/forward-auth, shc/license-brokerFirst-party Go servicesNot forks of anything: SHC’s own code, listed here only because they publish from the same pipeline.

These carry SHC’s own code, or package software upstream publishes no image for. All of them are pinned by digest on registry.selfhostedcloud.org.

ImageAppWhat it isSource
shc/medusamedusaMedusa v2 with the ERPNext sync subscribers compiled in. Upstream publishes no image, and subscribers can’t be added at runtime.selfhostedcloud.org/medusa
shc/s3managers3managerbitspur’s fork of cloudlena/s3manager, built for amd64 and arm64.bitspur/rock8s/s3manager
shc/credential-brokernextcloud, fleetSHC’s broker that trades a Keycloak sign-in for a service’s own credential (a Nextcloud app password, a Fleet enrol secret).credential-broker/ in this repo
shc/mailcow-apppassmailcowSHC’s app-password sidecar for mailcow.mailcow-apppass/ in this repo
shc/monica-nextcloudmonica-nextcloud, monicaSHC’s CalDAV/CardDAV bridge between Monica and Nextcloud.bridges/monica-nextcloud in this repo
shc/multiplatform-keycloakmultiplatform-keycloakmultiplatform.one’s Keycloak bundle (house only).multiplatform.one/mpo
shc/gitlab-fizzy-bridge, shc/gitlab-huly, shc/huly-matrix-notifier, shc/identity-brokergitlab-fizzy and the apps of the same namesBridges and estate glue SHC wrote for its own tools.selfhostedcloud.org/huly
shc/lookoutlookoutBased OS’s web wall (house app).basedlinux.com/lookout
shc/drover-relaydrover-relayCattle Drover’s sync server (house app).drover/drover
shc/fusionpbxfusionpbxFusionPBX, built by SHC on an Alpine base.apps/standalone/fusionpbx/docker/ in this repo
shc/matrix-authentication-servicematrixUpstream’s MAS image with mas-cli rebuilt from the same tag plus one patch: the socket peer is the last hop of X-Forwarded-For, so a client that dials MAS directly can’t forge its address. Upstream still puts the peer first.apps/flagship/matrix/docker/mas/ in this repo

Roadmap: builds and plugins the catalog does not ship yet

Section titled “Roadmap: builds and plugins the catalog does not ship yet”

Clearly marked as not-yet-shipped, so this page does not overpromise:

  • Medusa OIDC provider. Medusa v2 ships no admin OIDC. An SSO provider plugin is planned; until it exists, Medusa sits outside the SSO coverage ladder.
  • DefectDojo SSO re-add. The current DefectDojo line has no single sign-on of its own (see licensing postures for the split this caused). Restoring SSO to the current line, by an upstream change or an SHC-maintained patch, is roadmap; until then defectdojo-classic carries SSO and the current app installs behind the edge gate.