121 lines
4.3 KiB
Markdown
121 lines
4.3 KiB
Markdown
# Demo Runtime Source Of Truth
|
|
|
|
## Purpose
|
|
|
|
This document defines which system is authoritative for demo runtime behavior, how repo docs relate to deployed state, and how to validate or change that state safely.
|
|
|
|
The goal is to remove ambiguity between:
|
|
|
|
- Portainer stack definitions
|
|
- VPS Caddy site files
|
|
- Vault runtime and bootstrap material
|
|
- repo-owned runbooks and planning documents
|
|
|
|
## Ownership Model
|
|
|
|
The source-of-truth model is split by concern.
|
|
|
|
| Concern | Canonical Source | Live Materialization | Validation Path |
|
|
|---|---|---|---|
|
|
| Wave intent and execution order | `plan/2026-03-27-s39-master-spa-depth-and-ops-hardening.md` | N/A | Confirm task graph and plan links |
|
|
| Demo routing contract | `docs/consumption/demo-auth-routing-runbook.md` | Caddy site files on VPS | Validate hosts, path routing, and auth flow behavior |
|
|
| Demo container composition | Portainer stack definitions for demo stacks | Running Docker containers on VPS | Validate stack config against docs and deployed services |
|
|
| Secret operations and recovery | `general_information/Vault.md` | Vault host paths and `core-vault` container | Validate unseal, health, and expected secret paths |
|
|
| Registry endpoints and publication targets | `general_information/Gitea.md` | Gitea package and registry services | Validate package/image endpoints and login/pull paths |
|
|
| Cross-repo dependency safety | `docs/architecture/workspace-cross-repo-reference-guard.md` | `.csproj` graph in workspace | Run `tools/validate-no-cross-repo-projectrefs.sh` |
|
|
|
|
## Canonical Interpretation Rules
|
|
|
|
Use the following rules when repo docs and runtime state disagree:
|
|
|
|
1. Planning files define intended execution order and scope.
|
|
2. Repo runbooks define the expected runtime contract for routing, validation, and operational ownership.
|
|
3. Portainer and Caddy define the actual deployed runtime and must be reconciled back to the repo runbooks.
|
|
4. Vault operational recovery steps remain owned by `general_information/Vault.md` until a repo-owned ops runbook replaces them.
|
|
5. Gitea publication endpoints remain owned by `general_information/Gitea.md` until a repo-owned publication runbook replaces them.
|
|
|
|
This means:
|
|
|
|
- repo docs are canonical for expected behavior
|
|
- deployed systems are authoritative for current runtime
|
|
- any mismatch must be documented and reconciled, not silently accepted
|
|
|
|
## Required Change Order
|
|
|
|
When changing demo runtime behavior, use this order:
|
|
|
|
1. Update the relevant repo docs first.
|
|
2. Apply runtime changes in the owning platform:
|
|
- Portainer for demo stacks
|
|
- Caddy for ingress and host routing
|
|
- Vault for runtime secret operations
|
|
3. Validate deployed behavior against the updated docs.
|
|
4. Record any recovery or rollback notes in the same repo-owned runbook.
|
|
|
|
## Current Runtime Boundaries
|
|
|
|
### Portainer
|
|
|
|
Portainer owns:
|
|
|
|
- demo stack definitions
|
|
- container image references
|
|
- environment variable and mount bindings at stack level
|
|
|
|
Portainer does not own:
|
|
|
|
- public hostnames
|
|
- Caddy route logic
|
|
- application behavior contracts
|
|
|
|
### Caddy
|
|
|
|
Caddy owns:
|
|
|
|
- public hostnames
|
|
- reverse proxy path routing
|
|
- auth host and demo host ingress behavior
|
|
|
|
Caddy does not own:
|
|
|
|
- app container composition
|
|
- secret values
|
|
- application workflow semantics
|
|
|
|
### Vault
|
|
|
|
Vault owns:
|
|
|
|
- secret storage
|
|
- seal and unseal lifecycle
|
|
- bootstrap and recovery material
|
|
|
|
Vault does not own:
|
|
|
|
- auth UX behavior
|
|
- route ownership
|
|
- application feature flags outside secret-backed configuration
|
|
|
|
## Validation Checklist
|
|
|
|
Before closing any runtime or auth-alignment task:
|
|
|
|
- Confirm the active plan and mini plan still match the intended work.
|
|
- Confirm Portainer stacks match the documented demo service layout.
|
|
- Confirm Caddy host and path routing match the documented auth and demo routing contract.
|
|
- Confirm Vault paths and operations notes still match the expected runtime secret behavior.
|
|
- Confirm no cross-repo `ProjectReference` violations were introduced while adjusting repo docs or validation scripts.
|
|
|
|
## Rollback Principle
|
|
|
|
Rollback is not automatic.
|
|
|
|
If runtime validation fails:
|
|
|
|
1. stop at the system that drifted
|
|
2. restore the last known-good runtime configuration in that system
|
|
3. update the repo runbook if the rollback exposed undocumented behavior
|
|
|
|
Do not treat repo docs and deployed systems as independent sources of truth.
|
|
They must converge after every runtime-facing change.
|