Branding is S3-only, served by shcd: 2026-08-18
Owner ruling, 2026-08-18. Retires builtin/branding as an app package and
moves the brand store to the estate’s S3 connection, served read-through by
the daemon.
The ruling, verbatim
Section titled “The ruling, verbatim”“i would rather require s3 provider than have another module i have to maintain”
“can’t shcd serve the branding files from s3 proxied through traefik … the branding assets resolved from the shc dns route that goes through traefik and that’s what traefik injects in. so we simply just require a connection that has an s3 provider”
“also branding is the same story NO support outsdie of s3.”
And the architecture statement that fixes the shape of the answer:
“SHCD is supposed to handle branding … branding is handled by traefik [routing] … The modules are only for traefik, Keycloak, and OpenObserve, and … Postgres.”
An interim “ok ok fine fine then do support local for branding” amendment was REVERSED by the third quote above and is not the ruling. There is no local backend.
Why local could not stay
Section titled “Why local could not stay”The retired store was a host bind under the branding deployment
(<stateHome>/deployments/master/branding/default/mounts/brands/), written
directly by the daemon. That is node-pinned state: it lives on whichever
node the daemon wrote it on, and a container rescheduled to any other node
serves an empty store. It worked only because the estates run single-node.
The owner’s own words on the local shape: “it’s stupid to use beyond a
single node”, and he ruled out node-local .bak backups in the same
breath (scheduled backups are restic-over-S3 only,
backups-restic-only). The parallel is the point: the object store is
what makes both branding and backups cluster-real. A capability whose
state cannot leave one node is not a platform capability.
The second half of the ruling is about maintenance surface, not clustering:
an nginx container over a bind is a module to patch, pin, licence-audit and
back up forever, in exchange for alias /brands/. Requiring a connection the
estate already needs is cheaper than owning that.
What was built
Section titled “What was built”| before | after | |
|---|---|---|
| store | host bind, mounts/brands/<name>/ | S3 bucket, brands/<name>/ through the estate s3 connection |
| provider | builtin/branding: nginx, x-shc-scale: max 1, network public | none; the daemon is the provider |
| serving | nginx alias /brands/ on the overlay network | shcd route /branding/brands/{name}/{file}, read-through from S3 |
| routing | provider DNS alias <env>.branding.<stack>:80 | the estate host, which traefik already carries to shcd (the console catch-all) |
| socket | branding.socket.yaml in the package | the same contract, embedded in modules/branding |
| per-edge values | resolve-brand job, ::shc-connection-value:: channel | Go minter on the resolve path |
shc branding set | direct filesystem write | S3 PutObject through the connection |
The daemon-socket seam this rides on is ce’s app.RegisterDaemonSocket
(modules/app/integration_daemon_socket.go), built alongside the existing
OTEL/DNS system sockets and generic over any module-registered token.
The socket contract is unchanged; consumers were not edited
Section titled “The socket contract is unchanged; consumers were not edited”Zero consumer plugs changed. A socket stem is forever: every published
archive and every persisted integration row carries branding, so the stem,
the plug field (brand), the three socket fields (internalUrl,
resolvedBrand, hash), the fallback ladder (requested → default →
unbranded), the hash formula and the <internalUrl>/brands/<brand>/<file>
fetch shape are all preserved verbatim. Both shipped consumers
(apps/flagship/gitlab, apps/integrated/gitea) bind through untouched
plug files.
Two consequences worth stating:
internalUrl’s value moved (overlay origin → estate route). The field and its use did not, and the consumers only ever concatenated onto it.- The
hashformula is now implemented once, in Go, but its SPELLING is still the retired sh job’s, byte for byte, and a test still pins it against that shell one-liner. Markers written by the old provider stay valid.
A pre-existing defect closed on the way. Job-minted socket values are
re-minted only on explicit deploys and are never persisted, so the
post-restore reconcile (ReconcileDeploymentIntegrations) re-ran the
consumers’ apply jobs with an EMPTY resolvedBrand; every restored gitea
or gitlab silently reverted to stock assets. Minting on the resolve path
means install, update and restore all see the same values.
Day zero: unbranded, declared, never a failure
Section titled “Day zero: unbranded, declared, never a failure”A fresh estate has no S3 connection. The plug is required: false and an
unbranded install is the default, not a failure; that is preserved exactly.
Every reason a brand cannot be resolved mints an empty resolvedBrand and
logs X200880BRDUNB naming the reason: no s3 connection, credentials
rejected, store unreachable, no bundle for the brand or for default, or a
headless estate with no public route. The consumers already read an empty
resolvedBrand as “keep the current look”.
The management verbs are the opposite: they refuse loudly, because an
operator running shc branding set has asked for something specific.
| code | when |
|---|---|
X404882BRDCON | no estate s3 connection is visible to master (or the pin names none); carries the shc connection connect s3 --scope system … remedy |
X409881BRDAMB | several usable s3 connections; pin one with SHC_BRANDING_CONNECTION rather than let branding guess |
X403882BRDDEN | the connection’s held key was rejected |
X404883BRDBKT | the branding bucket does not exist |
X502880BRDOBJ | dial/DNS/TLS/5xx against the object store |
X200880BRDUNB | the declared-unbranded notice (warning, never fatal) |
Retired with the host bind: X404880BRDDIR (“install the branding app”) and
X409880BRDNDR. Neither number is reused.
Migration
Section titled “Migration”None is owed. Measured 2026-08-18: builtin/branding is deployed on
NEITHER estate: no branding container or deployment directory under
/var/lib/shc/deployments/master on bitspur or promanager. There is no
brand bundle anywhere to move.
Had there been, the path would have been: read the bind, shc branding set
each brand back through the new store, then uninstall the stack. The
master-tenant guards fire on install/deploy only, never on uninstall, so a
leftover stack stays removable after the package is gone.
Backups
Section titled “Backups”builtin/branding/backup.yaml dies with the package, and nothing replaces
it. Per the standing ruling, “backups never cross integration
boundaries; a stack backs up what it OWNS”, the brand bundles now belong
to the S3 provider’s stack: a bundled minio backs up its own buckets, and an
external bucket is the operator’s to protect. Branding owns no durable state
of its own any more, which is the correct end state for a capability whose
store is somebody else’s.
Consequences
Section titled “Consequences”BUILTIN_APPSlosesbranding(Makefile), with its lockstep ledger:.gitignore,.goreleaser.yaml(×2), the deb + darwin payload checks, and the arch-fitness corpus floors.licenseleft the same day (the app-licence socket amputation,2026-08-18-builtin-vs-deploy-placement.md), so the floors land at 4 and the builtins are now EXACTLY the owner’s list: traefik, keycloak, openobserve, postgres. This repo’sbuiltin/is empty; the local-first staging seam stays for the next proprietary package.modules/brandingno longer callsRegisterSystemApporRegisterMagicProvider; BRANDING is a daemon-socket token instead. The token match is case-insensitive, so sidecar rows written under the magic provider (canonical stack spellingbranding) still resolve.- The plug/socket agreement guard learned a
daemonServedSocketsset: a stem may only be listed there with a real daemon-side registration behind it. - The store is estate-wide and lives in one bucket
(
SHC_BRANDING_BUCKET, defaultshc-branding); assets are served unauthenticated, which is sound because brand assets render on public login pages by definition.