README: fix diagram rendering, add stat strip and systems table
Diagram: switched to LR layout, color-coded by role (edge/core/ observability), dropped the repeated 'reports to' labels that were clipping in the browser - same fix already applied to architecture-overview.md. Added a stat strip (11 hosts, 55 stacks, 16 systems, 4 boundaries, 13 flows) and a scannable systems-at-a- glance table above the detailed sections, so a reader gets the full picture in a 10-second skim before the deeper 2-minute read.
This commit is contained in:
1 file changed
+60
-36
@@ -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.
|
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.
|
||||||
|
|
||||||
|
<table>
|
||||||
|
<tr>
|
||||||
|
<td align="center"><strong>11</strong><br/>fleet hosts</td>
|
||||||
|
<td align="center"><strong>55</strong><br/>compose stacks</td>
|
||||||
|
<td align="center"><strong>16</strong><br/>documented systems</td>
|
||||||
|
<td align="center"><strong>4</strong><br/>trust boundaries</td>
|
||||||
|
<td align="center"><strong>13</strong><br/>automated maintenance flows</td>
|
||||||
|
</tr>
|
||||||
|
</table>
|
||||||
|
|
||||||
## Architecture at a glance
|
## Architecture at a glance
|
||||||
|
|
||||||
```mermaid
|
```mermaid
|
||||||
flowchart TD
|
flowchart LR
|
||||||
Internet(["Internet"])
|
Internet(["Internet"]) --> Edge["Edge Firewall"]
|
||||||
Edge["Edge Firewall<br/>NAT · public reverse proxy · NTP · DHCP"]
|
Edge --> LAN["LAN"]
|
||||||
LAN["LAN"]
|
|
||||||
DNS["Internal DNS<br/>two zones: browser-facing / service-to-service"]
|
|
||||||
Vault["Vault<br/>PKI + secret store"]
|
|
||||||
|
|
||||||
Apps["App Host (LXC)<br/>~40 Docker Compose stacks"]
|
LAN --> DNS["Internal DNS<br/>two zones"]
|
||||||
InternalProxy["Internal reverse-proxy zone<br/>app-to-app HTTPS"]
|
LAN --> Vault["Vault<br/>PKI + secrets"]
|
||||||
SSO["SSO / forward-auth"]
|
|
||||||
|
|
||||||
FileServer["File Server<br/>NFS · SMB"]
|
|
||||||
Automation["Automation VM<br/>Git hosting · orchestration"]
|
|
||||||
EdgeProxy["User-facing reverse proxy<br/>mTLS enforced"]
|
|
||||||
Monitoring["Monitoring<br/>metrics · logs"]
|
|
||||||
SecMonitoring["Security Monitoring<br/>SOC stack"]
|
|
||||||
|
|
||||||
Internet --> Edge --> LAN
|
|
||||||
LAN --> DNS
|
|
||||||
LAN --> Vault
|
|
||||||
DNS --> Vault
|
DNS --> Vault
|
||||||
|
|
||||||
Vault --> Apps
|
Vault --> Apps["App Host<br/>41 stacks"]
|
||||||
LAN --> FileServer
|
Vault --> Automation["Automation VM<br/>Git + orchestration"]
|
||||||
|
LAN --> FileServer["File Server"]
|
||||||
DNS --> FileServer
|
DNS --> FileServer
|
||||||
Vault --> Automation
|
|
||||||
LAN --> Automation
|
LAN --> Automation
|
||||||
|
|
||||||
Apps --> InternalProxy
|
Apps --> InternalProxy["Internal Proxy Zone"]
|
||||||
Apps --> SSO
|
Apps --> SSO["SSO"]
|
||||||
|
|
||||||
Vault --> EdgeProxy
|
Vault --> EdgeProxy["User-Facing Proxy<br/>mTLS"]
|
||||||
DNS --> EdgeProxy
|
DNS --> EdgeProxy
|
||||||
Apps -. proxied by .-> EdgeProxy
|
Apps -.proxied.-> EdgeProxy
|
||||||
SSO -. auth gate via .-> EdgeProxy
|
SSO -.auth.-> EdgeProxy
|
||||||
|
|
||||||
Apps -. reports to .-> Monitoring
|
Apps -.-> Monitoring["Monitoring"]
|
||||||
Automation -. reports to .-> Monitoring
|
Automation -.-> Monitoring
|
||||||
FileServer -. reports to .-> Monitoring
|
FileServer -.-> Monitoring
|
||||||
EdgeProxy -. reports to .-> Monitoring
|
EdgeProxy -.-> Monitoring
|
||||||
|
|
||||||
Apps -. reports to .-> SecMonitoring
|
Apps -.-> SecMon["Security Monitoring"]
|
||||||
Automation -. reports to .-> SecMonitoring
|
Automation -.-> SecMon
|
||||||
FileServer -. reports to .-> SecMonitoring
|
FileServer -.-> SecMon
|
||||||
EdgeProxy -. reports to .-> SecMonitoring
|
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
|
## Systems
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user