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:
- 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, andimages: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. - 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).
The Keycloak image
Section titled “The Keycloak image”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.
The Frappe image
Section titled “The Frappe image”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.
The Huly soft fork
Section titled “The Huly soft fork”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.
The Fizzy soft fork
Section titled “The Fizzy soft fork”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.
The Activepieces soft fork
Section titled “The Activepieces soft fork”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.
The OpenReplay soft fork
Section titled “The OpenReplay soft fork”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.
The Pulp soft fork
Section titled “The Pulp soft fork”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.
Other first-party system images
Section titled “Other first-party system images”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:
| Image | What it is | Why custom |
|---|---|---|
shc/traefik | Upstream Traefik plus SHC’s local Yaegi plugin, baked in | A 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/collector | A minimal custom OpenTelemetry Collector distro | Ships only the components the telemetry fabric uses, from a declared component inventory. |
shc/forward-auth, shc/license-broker | First-party Go services | Not forks of anything: SHC’s own code, listed here only because they publish from the same pipeline. |
Catalogue images SHC builds
Section titled “Catalogue images SHC builds”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.
| Image | App | What it is | Source |
|---|---|---|---|
shc/medusa | medusa | Medusa v2 with the ERPNext sync subscribers compiled in. Upstream publishes no image, and subscribers can’t be added at runtime. | selfhostedcloud.org/medusa |
shc/s3manager | s3manager | bitspur’s fork of cloudlena/s3manager, built for amd64 and arm64. | bitspur/rock8s/s3manager |
shc/credential-broker | nextcloud, fleet | SHC’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-apppass | mailcow | SHC’s app-password sidecar for mailcow. | mailcow-apppass/ in this repo |
shc/monica-nextcloud | monica-nextcloud, monica | SHC’s CalDAV/CardDAV bridge between Monica and Nextcloud. | bridges/monica-nextcloud in this repo |
shc/multiplatform-keycloak | multiplatform-keycloak | multiplatform.one’s Keycloak bundle (house only). | multiplatform.one/mpo |
shc/gitlab-fizzy-bridge, shc/gitlab-huly, shc/huly-matrix-notifier, shc/identity-broker | gitlab-fizzy and the apps of the same names | Bridges and estate glue SHC wrote for its own tools. | selfhostedcloud.org/huly |
shc/lookout | lookout | Based OS’s web wall (house app). | basedlinux.com/lookout |
shc/drover-relay | drover-relay | Cattle Drover’s sync server (house app). | drover/drover |
shc/fusionpbx | fusionpbx | FusionPBX, built by SHC on an Alpine base. | apps/standalone/fusionpbx/docker/ in this repo |
shc/matrix-authentication-service | matrix | Upstream’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-classiccarries SSO and the current app installs behind the edge gate.
See also
Section titled “See also”- Licensing postures: the patterns behind catalog splits and refusals
- SSO coverage policy: why zero-touch SSO drives these builds
- Gated apps: the edge gate custom builds sometimes exist to avoid needing
- Plugs & sockets: the integration model the baked-in connectors serve