Skip to content
SHC Docs

Post-deploy notes templating (Helm NOTES.txt style) (2026-07-17)

Status: open design. Adapters read a notes field into app metadata, and nothing renders it after a deploy. Part of the platform-compat program, faithful capture of docs/handoff/2026-07-16-hel1-reprovision-and-platform-compat.md (§C, §C5 Table B, §D), no new design. A native SHC feature first, a compat target second. Siblings: 2026-07-17-origin-ingest-gate.md (the adapt stage that synthesizes notes for adapted apps), 2026-07-17-manifest-adapters.md (the per-origin adapters doing the synthesis), 2026-07-17-app-metadata-schema.md (notes is a canonical field in that schema), 2026-07-17-origin-repos-and-migrations.md (catalog registration + migration).

Every origin has some way to tell the user how to log in for the first time, and almost all of them are static text: Umbrel ships literal defaultUsername/defaultPassword fields, Cloudron a postInstallMessage, CapRover instructions.end, CasaOS “tips”. Static default creds are exactly what SHC’s secret handling replaces: SHC mints the credential into the vault (see the secret contract in 2026-07-17-origin-ingest-gate.md), so a static message cannot tell the user what their actual credential is.

SHC natively has no post-deploy message surface at all; after shc install the user gets no “here is your URL, here is how you log in”.

Replace static default-creds fields with a Helm-style templated post-deploy notes (NOTES.txt model): a template shipped in the package that is rendered after deploy, interpolating

  • the resolved host (the actual host_spec result: traefik host + LE, post DNS self-registration), and
  • the minted vault secret (the deployment-scoped credential SHC minted at install).

Literal fallback: if the image hardcodes a credential (nothing was minted because nothing is consumed), the notes fall back to displaying the literal.

Sensitive rendering (load-bearing): minted secrets render SENSITIVELY, never through TF outputs / CI logs unmarked. The render path must treat interpolated secrets as sensitive material end to end.

notes is a canonical app.yaml field (2026-07-17-app-metadata-schema.md), available to first-party packages, not a compat-only shim. It also powers the future catalog UI alongside the rest of the metadata schema.

Per the canonical-field remap table (2026-07-17-app-metadata-schema.md):

OriginSource of the notes template
CloudronpostInstallMessage
CapRoverinstructions.end (CapRover is dropped from the adapter roadmap; the mapping is recorded for the schema)
UmbreldefaultUsername/defaultPassword display
CasaOStips (field name to be verified in the census)

The notes-vs-literal fork: Umbrel’s deterministicPassword field tells the adapter whether APP_PASSWORD is actually consumed by the app; it drives whether the notes interpolate the minted secret or display a literal.

Cloudron’s checklist is a second post-install surface (tickable todos), distinct from the message, deferred; it rides the compat: passthrough bag.

  • notes is a native SHC feature (with a canonical app.yaml field), not compat-only.
  • Helm NOTES.txt-style templating: interpolates the resolved host + the minted vault secret.
  • Literal fallback when the image hardcodes a credential.
  • Sensitive-safe render: minted secrets never pass through TF outputs or CI logs unmarked.
  • Adapted apps get their notes synthesized at the ingest adapt stage from the origin’s post-install/default-creds fields.
  • Template syntax / interpolation grammar: not specified in the source design.
  • Render surfaces (install output, shc app info, HUD): not specified.
  • The mechanism that keeps rendered secrets marked sensitive across the terraform provider boundary: requirement stated, mechanism unscoped.
  • CasaOS post-install field name needs census verification.
  • Cloudron checklist (tickable post-install todos): deferred.