Skip to content
SHC Docs

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.

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

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.

beforeafter
storehost bind, mounts/brands/<name>/S3 bucket, brands/<name>/ through the estate s3 connection
providerbuiltin/branding: nginx, x-shc-scale: max 1, network publicnone; the daemon is the provider
servingnginx alias /brands/ on the overlay networkshcd route /branding/brands/{name}/{file}, read-through from S3
routingprovider DNS alias <env>.branding.<stack>:80the estate host, which traefik already carries to shcd (the console catch-all)
socketbranding.socket.yaml in the packagethe same contract, embedded in modules/branding
per-edge valuesresolve-brand job, ::shc-connection-value:: channelGo minter on the resolve path
shc branding setdirect filesystem writeS3 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 hash formula 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.

codewhen
X404882BRDCONno estate s3 connection is visible to master (or the pin names none); carries the shc connection connect s3 --scope system … remedy
X409881BRDAMBseveral usable s3 connections; pin one with SHC_BRANDING_CONNECTION rather than let branding guess
X403882BRDDENthe connection’s held key was rejected
X404883BRDBKTthe branding bucket does not exist
X502880BRDOBJdial/DNS/TLS/5xx against the object store
X200880BRDUNBthe declared-unbranded notice (warning, never fatal)

Retired with the host bind: X404880BRDDIR (“install the branding app”) and X409880BRDNDR. Neither number is reused.

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.

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.

  • BUILTIN_APPS loses branding (Makefile), with its lockstep ledger: .gitignore, .goreleaser.yaml (×2), the deb + darwin payload checks, and the arch-fitness corpus floors. license left 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’s builtin/ is empty; the local-first staging seam stays for the next proprietary package.
  • modules/branding no longer calls RegisterSystemApp or RegisterMagicProvider; BRANDING is a daemon-socket token instead. The token match is case-insensitive, so sidecar rows written under the magic provider (canonical stack spelling branding) still resolve.
  • The plug/socket agreement guard learned a daemonServedSockets set: 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, default shc-branding); assets are served unauthenticated, which is sound because brand assets render on public login pages by definition.