docs: automate generated docs commits and add docs site structure

docs/automation.md

@@ -0,0 +1,14 @@
+# Automation
+
+This section describes automation systems associated with this environment.
+
+Current state:
+
+- CI documentation generation in GitHub Actions.
+- Static parsing and rendering from repository configuration.
+- No live service interaction during documentation generation.
+
+Future content can document:
+
+- Docker update automation.
+- Node-RED automation flows and operational patterns.

docs/diagrams/docker-compose.dot

@@ -0,0 +1,4 @@
+digraph Compose {
+  rankdir=LR;
+  node [fontname=Helvetica];
+}

docs/diagrams/docker-compose.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="640" height="80"><text x="10" y="40">Graphviz dot not found in environment.</text></svg>

docs/docker.md

@@ -0,0 +1,13 @@
+# Docker Environment
+
+This environment is orchestrated from central Docker Compose definitions committed in this repository.
+
+Compose source files are rendered into a resolved configuration during docs generation, then summarized into generated markdown and diagrams.
+
+Generated outputs:
+
+- [Compose Inventory](generated/compose-inventory.md)
+- [Resolved Compose Config](generated/docker-compose.resolved.yml)
+- [Docker Compose Diagram](diagrams/docker-compose.svg)
+
+Generated documentation is produced by CI from repository files only. Documentation generation does not start containers.

docs/generated/compose-files.txt

@@ -0,0 +1,24 @@
+default-network.yml
+apps/gitea/docker-compose.yml
+apps/gramps/docker-compose.yml
+apps/nextcloud/docker-compose.yml
+apps/passbolt/docker-compose.yml
+apps/searxng/docker-compose.yml
+core/authelia/docker-compose.yml
+core/crowdsec/docker-compose.yml
+core/error-pages/docker-compose.yml
+core/test/docker-compose.yml
+core/traefik/docker-compose.yml
+monitoring/docker-exporter/docker-compose.yml
+monitoring/docker-socket-proxy/docker-compose.yml
+monitoring/gotify/docker-compose.yml
+monitoring/grafana/docker-compose.yml
+monitoring/influxdb/docker-compose.yml
+monitoring/mtls-bridge/docker-compose.yml
+monitoring/node-exporter/docker-compose.yml
+monitoring/node-red/docker-compose.yml
+monitoring/pihole-exporter/docker-compose.yml
+monitoring/portainer/docker-compose.yml
+monitoring/prometheus/docker-compose.yml
+monitoring/telegraf/docker-compose.yml
+monitoring/uptime-kuma/docker-compose.yml

docs/generated/compose-inventory.md

@@ -0,0 +1,26 @@
+# Docker Compose Inventory
+
+Generated: 2026-05-12T22:04:13Z
+
+## Summary
+
+| Item | Count |
+|---|---:|
+| Services | 0 |
+| Networks | 0 |
+| Volumes | 0 |
+
+## Services
+
+| Service | Container | Image | Build | Profiles | Networks | Ports | Restart |
+|---|---|---|---|---|---|---|---|
+
+## Networks
+
+| Network | Driver | External |
+|---|---|---|
+
+## Volumes
+
+| Volume | External |
+|---|---|

docs/generated/docker-compose.resolved.yml

@@ -0,0 +1,2 @@
+name: core
+services: {}

docs/generated/index.md

@@ -0,0 +1,12 @@
+# Generated Documentation
+
+This directory contains documentation generated automatically from repository configuration.
+
+## Files
+
+- [Compose file list](compose-files.txt)
+- [Resolved Docker Compose config](docker-compose.resolved.yml)
+- [Compose inventory](compose-inventory.md)
+- [Traefik routes](traefik-routes.md)
+- [Prometheus rules](prometheus-rules.md)
+- [Docker Compose diagram](../diagrams/docker-compose.svg)

docs/generated/prometheus-rules.md

@@ -0,0 +1,7 @@
+# Prometheus Rules
+
+| File | Group | Alert | Expr | For | Labels | Annotations |
+|---|---|---|---|---|---|---|
+| monitoring/prometheus/rules/alerts.yml | system | HostHighCPU | 100 * (1 - avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[2m]))) > 90 | 2m | {'severity': 'warning'} | {'summary': 'High CPU usage on host'} |
+| monitoring/prometheus/rules/alerts.yml | system | ContainerRestarting | increase(container_restart_count[10m]) > 3 | 1m | {'severity': 'warning'} | {'summary': 'Container restarting frequently'} |
+| monitoring/prometheus/rules/alerts.yml | system | AlwaysFiring | vector(1) | 10s | {'severity': 'critical'} | {'summary': 'This alert should always fire'} |

docs/generated/traefik-routes.md

@@ -0,0 +1,3 @@
+# Traefik Routes
+
+No Traefik routes were detected.

docs/index.md

@@ -0,0 +1,30 @@
+# Infrastructure Documentation
+
+This documentation describes the Docker-based infrastructure, reverse proxy configuration, monitoring stack, automation services, and generated inventory for this environment.
+
+Some sections are manually written. Other sections are generated automatically by GitHub Actions from the repository configuration.
+
+## Sections
+
+- [Docker Environment](docker.md)
+- [Networking and Reverse Proxy](networking.md)
+- [Monitoring and Alerting](monitoring.md)
+- [Automation](automation.md)
+- [Operations](operations.md)
+- [Public Showcase](showcase.md)
+
+## Generated Documentation
+
+- [Compose Inventory](generated/compose-inventory.md)
+- [Traefik Routes](generated/traefik-routes.md)
+- [Prometheus Rules](generated/prometheus-rules.md)
+- [Resolved Compose Config](generated/docker-compose.resolved.yml)
+- [Docker Compose Diagram](diagrams/docker-compose.svg)
+
+## Public-safe Output
+
+Sanitized documentation intended for public sharing is generated under:
+
+```text
+docs/public/
+```

docs/monitoring.md

@@ -0,0 +1,11 @@
+# Monitoring and Alerting
+
+Monitoring documentation is generated from static rule files committed in this repository.
+
+- Prometheus rule files are parsed statically.
+- Live Prometheus APIs are not queried.
+- Future improvements can include Grafana dashboard and alert contact-point summaries.
+
+Generated asset:
+
+- [Prometheus Rules](generated/prometheus-rules.md)

docs/networking.md

@@ -0,0 +1,12 @@
+# Networking and Reverse Proxy
+
+Networking and reverse-proxy documentation is generated from Docker Compose metadata.
+
+- Traefik labels are parsed statically from Compose definitions.
+- Service-to-network relationships are represented in generated diagrams.
+- Sensitive internal values are redacted in public-facing output.
+
+Related generated assets:
+
+- [Traefik Routes](generated/traefik-routes.md)
+- [Docker Compose Diagram](diagrams/docker-compose.svg)

docs/operations.md

@@ -0,0 +1,30 @@
+# Operations
+
+## Local docs generation
+
+```bash
+chmod +x scripts/docs/*.sh
+scripts/docs/generate-all.sh
+```
+
+## Inspect generated changes
+
+```bash
+git status -- docs/generated docs/diagrams docs/public
+```
+
+## GitHub Actions artifacts
+
+Use the **Generate documentation** workflow run and download the `generated-documentation` artifact from the run summary.
+
+## Commit behavior
+
+- Pull requests generate docs and upload artifacts only.
+- Pushes to `main` generate docs, upload artifacts, and commit generated docs when changes exist.
+- Manual workflow runs can commit generated docs when enabled through workflow input.
+
+## Troubleshooting
+
+- Confirm required tooling (`python3`, `jq`, `graphviz`, `docker compose`) is available.
+- Re-run generation after documentation script changes.
+- Review `docs/public` output for redaction coverage before sharing.

docs/public/compose-inventory.md

@@ -0,0 +1,26 @@
+# Docker Compose Inventory
+
+Generated: 2026-05-12T22:04:13Z
+
+## Summary
+
+| Item | Count |
+|---|---:|
+| Services | 0 |
+| Networks | 0 |
+| Volumes | 0 |
+
+## Services
+
+| Service | Container | Image | Build | Profiles | Networks | Ports | Restart |
+|---|---|---|---|---|---|---|---|
+
+## Networks
+
+| Network | Driver | External |
+|---|---|---|
+
+## Volumes
+
+| Volume | External |
+|---|---|

docs/public/docker-compose.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="640" height="80"><text x="10" y="40">Graphviz dot not found in environment.</text></svg>

docs/public/index.md

@@ -0,0 +1,12 @@
+# Public Infrastructure Summary
+
+This folder contains sanitized documentation generated from the infrastructure repository.
+
+Sensitive values such as internal domain names, private IP addresses, tokens, passwords, and secrets are redacted.
+
+## Documents
+
+- [Compose Inventory](compose-inventory.md)
+- [Traefik Routes](traefik-routes.md)
+- [Prometheus Rules](prometheus-rules.md)
+- [Docker Compose Diagram](docker-compose.svg)

docs/public/prometheus-rules.md

@@ -0,0 +1,7 @@
+# Prometheus Rules
+
+| File | Group | Alert | Expr | For | Labels | Annotations |
+|---|---|---|---|---|---|---|
+| monitoring/prometheus/rules/alerts.yml | system | HostHighCPU | 100 * (1 - avg by(instance) (rate(node_cpu_seconds_total{mode="idle"}[2m]))) > 90 | 2m | {'severity': 'warning'} | {'summary': 'High CPU usage on host'} |
+| monitoring/prometheus/rules/alerts.yml | system | ContainerRestarting | increase(container_restart_count[10m]) > 3 | 1m | {'severity': 'warning'} | {'summary': 'Container restarting frequently'} |
+| monitoring/prometheus/rules/alerts.yml | system | AlwaysFiring | vector(1) | 10s | {'severity': 'critical'} | {'summary': 'This alert should always fire'} |

docs/public/traefik-routes.md

@@ -0,0 +1,3 @@
+# Traefik Routes
+
+No Traefik routes were detected.

docs/showcase.md

@@ -0,0 +1,14 @@
+# Public Showcase
+
+This environment showcases practical infrastructure operations with a documentation-first approach.
+
+Highlights:
+
+- Container orchestration with Docker Compose.
+- Reverse proxy routing and TLS-focused service exposure patterns.
+- Monitoring and alerting configuration via version-controlled rules.
+- Documentation automation through CI.
+- Generated architecture diagrams to aid operational understanding.
+- Sanitized public documentation for safe sharing.
+
+This page intentionally avoids private hostnames, internal-only URLs, credentials, and secret values.