Post-deploy notes templating (Helm NOTES.txt style) (2026-07-17)
Status: open design. Adapters read a
notesfield into app metadata, and nothing renders it after a deploy. Part of the platform-compat program, faithful capture ofdocs/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 synthesizesnotesfor adapted apps), 2026-07-17-manifest-adapters.md (the per-origin adapters doing the synthesis), 2026-07-17-app-metadata-schema.md (notesis a canonical field in that schema), 2026-07-17-origin-repos-and-migrations.md (catalog registration + migration).
Problem
Section titled “Problem”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”.
Design
Section titled “Design”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_specresult: 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.
Native surface
Section titled “Native surface”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.
What adapters synthesize it from
Section titled “What adapters synthesize it from”Per the canonical-field remap table (2026-07-17-app-metadata-schema.md):
| Origin | Source of the notes template |
|---|---|
| Cloudron | postInstallMessage |
| CapRover | instructions.end (CapRover is dropped from the adapter roadmap; the mapping is recorded for the schema) |
| Umbrel | defaultUsername/defaultPassword display |
| CasaOS | tips (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.
Decided
Section titled “Decided”notesis a native SHC feature (with a canonicalapp.yamlfield), 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
notessynthesized 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.