# Docker + Traefik Homelab Stack

This repository defines a multi-compose Docker environment with Traefik as ingress, app workloads, and a monitoring/alerting plane.

## High-Level Architecture

```mermaid
flowchart TB
  Internet((Internet Clients)) -->|HTTPS 443 / HTTP 80| Traefik[Traefik Ingress\nACME TLS + Security Middlewares]

  subgraph DockerHost[Primary Docker Host]
    Traefik
    Authelia[Authelia SSO / ForwardAuth]
    CrowdSec[CrowdSec + Traefik Bouncer]
    ErrPages[Error Pages Fallback]

    subgraph Apps[Business / User Applications]
      Nextcloud[Nextcloud]
      Passbolt[Passbolt]
      Gitea[Gitea]
      FamilyTree[Gramps Web]
      Searxng[SearXNG]
    end

    subgraph Ops[Operations & Monitoring]
      Grafana[Grafana]
      Prometheus[Prometheus]
      InfluxDB[InfluxDB]
      NodeRED[Node-RED]
      Portainer[Portainer]
      UptimeKuma[Uptime Kuma]
      Gotify[Gotify Notifications]
    end
  end

  Traefik --> Apps
  Traefik --> Ops
  Traefik -->|ForwardAuth for selected routes| Authelia
  Traefik -->|Threat decisions| CrowdSec
  Traefik -->|4xx/5xx fallback| ErrPages

  Prometheus --> Grafana
  Prometheus --> Gotify
```

For a request-flow/network view and architecture notes, see [docs/architecture.md](docs/architecture.md).

## Prometheus Runtime Inventory Export
Regenerate derived docs/diagrams from inventory:

```bash
python3 scripts/render_prometheus_docs.py --inventory-file docs/runtime/prometheus-inventory.json
```


Use `scripts/export_prometheus_inventory.py` to snapshot Prometheus-observed runtime inventory into versionable artifacts for docs/diagram workflows.

```bash
export PROMETHEUS_URL="https://prometheus.example.com"
python3 scripts/export_prometheus_inventory.py --output-dir docs/runtime
```

This writes raw API snapshots and a normalized inventory JSON under `docs/runtime/`, and updates `docs/prometheus-inventory.md`.