diff --git a/README.md b/README.md index 0e99a22..64abbef 100644 --- a/README.md +++ b/README.md @@ -4,57 +4,81 @@ A real, multi-host homelab run as a production-grade platform — not a pile of This repo is a sanitized showcase of the systems behind that platform — the actual engineering decisions and tradeoffs, not just a list of installed apps. Every real IP, hostname, and internal domain has been stripped or genericized throughout. + + + + + + + + +
11
fleet hosts
55
compose stacks
16
documented systems
4
trust boundaries
13
automated maintenance flows
+ ## Architecture at a glance ```mermaid -flowchart TD - Internet(["Internet"]) - Edge["Edge Firewall
NAT · public reverse proxy · NTP · DHCP"] - LAN["LAN"] - DNS["Internal DNS
two zones: browser-facing / service-to-service"] - Vault["Vault
PKI + secret store"] +flowchart LR + Internet(["Internet"]) --> Edge["Edge Firewall"] + Edge --> LAN["LAN"] - Apps["App Host (LXC)
~40 Docker Compose stacks"] - InternalProxy["Internal reverse-proxy zone
app-to-app HTTPS"] - SSO["SSO / forward-auth"] - - FileServer["File Server
NFS · SMB"] - Automation["Automation VM
Git hosting · orchestration"] - EdgeProxy["User-facing reverse proxy
mTLS enforced"] - Monitoring["Monitoring
metrics · logs"] - SecMonitoring["Security Monitoring
SOC stack"] - - Internet --> Edge --> LAN - LAN --> DNS - LAN --> Vault + LAN --> DNS["Internal DNS
two zones"] + LAN --> Vault["Vault
PKI + secrets"] DNS --> Vault - Vault --> Apps - LAN --> FileServer + Vault --> Apps["App Host
41 stacks"] + Vault --> Automation["Automation VM
Git + orchestration"] + LAN --> FileServer["File Server"] DNS --> FileServer - Vault --> Automation LAN --> Automation - Apps --> InternalProxy - Apps --> SSO + Apps --> InternalProxy["Internal Proxy Zone"] + Apps --> SSO["SSO"] - Vault --> EdgeProxy + Vault --> EdgeProxy["User-Facing Proxy
mTLS"] DNS --> EdgeProxy - Apps -. proxied by .-> EdgeProxy - SSO -. auth gate via .-> EdgeProxy + Apps -.proxied.-> EdgeProxy + SSO -.auth.-> EdgeProxy - Apps -. reports to .-> Monitoring - Automation -. reports to .-> Monitoring - FileServer -. reports to .-> Monitoring - EdgeProxy -. reports to .-> Monitoring + Apps -.-> Monitoring["Monitoring"] + Automation -.-> Monitoring + FileServer -.-> Monitoring + EdgeProxy -.-> Monitoring - Apps -. reports to .-> SecMonitoring - Automation -. reports to .-> SecMonitoring - FileServer -. reports to .-> SecMonitoring - EdgeProxy -. reports to .-> SecMonitoring + Apps -.-> SecMon["Security Monitoring"] + Automation -.-> SecMon + FileServer -.-> SecMon + EdgeProxy -.-> SecMon + + classDef edge fill:#f8cecc,stroke:#b85450,color:#333 + classDef core fill:#dae8fc,stroke:#6c8ebf,color:#333 + classDef obs fill:#fff2cc,stroke:#d6b656,color:#333 + class Internet,Edge edge + class LAN,DNS,Vault,Apps,Automation,FileServer,InternalProxy,SSO,EdgeProxy core + class Monitoring,SecMon obs ``` -Full traffic-law breakdown (ingress, east-west, secrets, DNS, observability, notifications, CI/CD, and management planes, each with its own failure behavior): [docs/architecture-overview.md](docs/architecture-overview.md). +Solid arrows are real dependencies; dotted arrows are asynchronous telemetry reporting, not a blocking dependency. Full breakdown of all 8 traffic laws (ingress, east-west, secrets, DNS, observability, notifications, CI/CD, management) with the actual trust-boundary reasoning: [docs/architecture-overview.md](docs/architecture-overview.md). + +## Every system, at a glance + +| System | The core decision | Doc | +|---|---|---| +| 🔐 Secrets & PKI | One Vault cluster as CA + secret store, zero plaintext secrets in git | [→](docs/secrets-and-pki.md) | +| 🔑 Secret Distribution | Four distinct flows, each with its own failure contract | [→](docs/secret-distribution.md) | +| 🪪 SSO & Identity | Dual-zone SSO registration, header-based fallback for a real LDAP limitation | [→](docs/sso-and-identity.md) | +| 🧱 Firewall & Network | Zero blanket-allow rules — every flow explicit, everything else dropped | [→](docs/firewall-and-network.md) | +| 🌐 DNS | Two zones decide which trust boundary a request enters | [→](docs/dns-naming.md) | +| 📈 Observability | Push-based metrics, chosen specifically to fit the firewall model | [→](docs/observability.md) | +| 🛡️ Security Monitoring | Curated alert runbook + justified compliance exceptions | [→](docs/security-monitoring.md) | +| 🔁 Orchestration | 13 flows, check → pause → human approval → apply | [→](docs/orchestration.md) | +| 🔔 Notifications | Two fan-in branches, one shared formatter, zero runtime coupling | [→](docs/notifications.md) | +| 📦 Registry & Build | Self-hosted registry, digest-checked before any rebuild | [→](docs/registry-and-build.md) | +| 🖥️ Dashy SOC Board | 14 data sources aggregated into one glanceable board | [→](docs/dashy-soc-board.md) | +| ⏱️ Cron Scheduler | Fleet-wide job inventory, weighted load heatmap | [→](docs/cron-scheduler.md) | +| 📝 Content Pipeline | In-progress, shown honestly rather than hidden | [→](docs/content-pipeline.md) | +| 🏗️ Infrastructure as Code | Packer → Terraform → Ansible, one tag threading all three | [→](docs/iac-pipeline.md) | +| 🧯 Disaster Recovery | 3 independent recovery layers, one real documented gap | [→](docs/disaster-recovery.md) | +| 📐 Architecture Overview | 4 trust boundaries, 3 routing authorities, calibrated not maxed | [→](docs/architecture-overview.md) | ## Systems