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	docs/security-secrets.md + secrets/inventory.json + local secret files in secrets/	What secrets exist, where they are expected, and what automation should parse.
Host/device configuration bootstrap (emerging)	Ansible under infrastructure/ansible/	Gradual inventory/configuration layer for hosts/devices; validation-first at current stage.

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.

Ansible bootstrap decisions

Use Ansible under infrastructure/ansible/ to build inventory and configuration structure incrementally.

At the current stage:

• Do not treat Ansible as replacement authority for Docker runtime operations.
• Do not treat Ansible as replacement authority for Terraform inventory/reconciliation.
• NixOS remains outside Ansible authority unless explicitly adopted in a later phase.

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.