project-charlie/docs/strategy.md

Strategy

flowchart LR
  Dev[Operator push] --> Gitea
  Gitea --> Runner[Any runner]
  Runner -->|SSH cert| Host[Target host]
  Host --> Stack["/mnt/nas/stacks"]
  Host --> Data["/mnt/nas/data"]

Area	Current state
Deployment model	GitOps through Gitea Actions and shared reusable workflows.
Runner model	Stateless runners; target work happens over SSH on the host.
Deployment identity	sys-gitea-runner with short-lived step-ca SSH certs.
Stack sync	Target working tree is fetched, reset, cleaned, decrypted, composed.
Drift stance	Host edits are overwritten by repo state.
Data stance	Persistent state lives outside Git.

Stack types

Type	Shape
Singleton stack	One owner host named in workflow host.
Shared stack	Same repo deployed to multiple hosts.
Source/image repo	Builds images through build-image.yml; stack repo pins the result.
Operator tool	Runs on the operator workstation; not deployed as a stack.

Shared-stack resolution

File	Meaning
docker-compose.yml	Default stack definition.
docker-compose.<host>.yml	Full host-specific replacement.
overrides/<host>.yml	Host-specific additive overlay.
envs/<host>.env	Host-specific environment file.

Shared stacks are serialized when they touch the same NFS working tree or plaintext secret path.