Repository Structure

This page explains where to find authoritative files quickly.

Top-level directories

core/ — core platform/security services (Traefik, Authelia, CrowdSec, error pages).
apps/ — user/business applications (Nextcloud, Passbolt, Gitea, Gramps, SearXNG).
monitoring/ — observability and operational tooling (Prometheus, Grafana, InfluxDB, Node-RED, etc.).
infrastructure/terraform/ — brownfield Terraform inventory/reconciliation layers.
infrastructure/ansible/ — phase-1 Ansible inventory/configuration scaffold and validation playbooks.
docs/ — repository-level architecture and workflow documentation.
archive/ — historical compose/config artifacts not part of active runtime composition.
secrets/ — local secret material and templates; never commit real values.

services-up.sh — runtime composition entrypoint for multi-compose environment.
default-network.yml — shared docker network definitions used across compose files.
default-environment.env — non-secret default env values for compose rendering.
scripts/codex-setup.sh — Codex/bootstrap helper to install validation tooling and prepare dummy secret material.
scripts/codex-maintenance.sh — Codex maintenance helper to refresh tooling, reconcile dummy secret material, and run safe Ansible validation checks.
docs/deployment-prerequisites.md — prerequisite setup before runtime operations.
docs/security-secrets.md — secrets documentation and inventory model.

infrastructure/terraform/README.md — Terraform purpose and boundaries in this repo.
infrastructure/terraform/proxmox/ — imported/reconciled Proxmox VM resources and host metadata.
infrastructure/terraform/docker/ — selective Docker container documentation mirrors.
infrastructure/terraform/bootstrap/ — backend/provider bootstrap scaffolding.
infrastructure/terraform/scripts/reconcile_from_plan.sh — helper for terraform plan -generate-config-out reconciliation workflow.

Read README.md.
Read docs/source-of-truth.md.
Read docs/docker-environment.md.
Read docs/terraform-workflows.md.
Only then edit Compose/Terraform files.
For Ansible bootstrap changes, validate inventory and playbook syntax checks only.