docker/docs/source-of-truth.md

Source-of-Truth Boundaries

This repository has multiple layers. Knowing the authority for each layer prevents accidental drift.

Boundary summary

Layer	Primary authority	Purpose
Application/runtime container composition	services-up.sh + Compose files under core/, apps/, monitoring/	What runs in the Docker environment and how services are wired.
Docker shared baseline inputs	default-network.yml, default-environment.env, secrets/stack-secrets.env	Shared network/env material applied during compose rendering.
Infrastructure inventory and reconciliation	Terraform under infrastructure/terraform/	Codified inventory of existing infrastructure and relationships, especially Proxmox VMs and selected Docker mirrors.
Secret policy and inventory	SECURITY_SECRETS_INVENTORY.md + local secret files in secrets/	What secrets exist and where they are expected.

Practical meaning

Docker runtime decisions

Change Compose files and services-up.sh when changing runtime behavior.

Do not assume Terraform Docker resources are the deployment source for day-to-day service runtime.

Infrastructure inventory decisions

Use Terraform when documenting/reconciling existing:

• Proxmox VM config and identifiers.
• Physical host metadata.
• Select Docker container details that are intentionally mirrored.

Do not treat Terraform as a full replacement for Compose operations in this repo.

Declared config vs observed/runtime state

• Declared config: files in this repository (Compose, Terraform, docs).
• Observed/runtime state: live Docker/Proxmox reality and Terraform state snapshots.

Brownfield workflows reconcile these two safely and incrementally.

Guardrails for contributors and Codex

• Do not mass-import or mass-reconcile everything at once.
• Keep imports/reconciliation scoped to one object (or small set) at a time.
• Keep ignore_changes surgical and justified.
• Prefer shaped outputs (inventory-ready) over raw provider object dumps.
• Do not commit .tfstate, real .tfvars, or real secret files.

See docs/terraform-workflows.md for step-by-step procedures.