Merge pull request #67 from beatz174-bit/codex/update-github-actions-for-automated-docs-generation

docs: auto-commit generated docs on push and add browsable docs site structure

.github/workflows/generate-docs.yml

@@ -7,12 +7,14 @@ on:
       - "docs/generated/**"
       - "docs/diagrams/**"
       - "docs/public/**"
+      - "site/**"
   pull_request:
     branches: [main]
     paths-ignore:
       - "docs/generated/**"
       - "docs/diagrams/**"
       - "docs/public/**"
+      - "site/**"
   workflow_dispatch:
     inputs:
       commit_generated_docs:
@@ -30,6 +32,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - name: Install tooling
         run: |
           sudo apt-get update
@@ -55,7 +59,9 @@ jobs:
             docs/diagrams
             docs/public
       - name: Commit generated docs
-        if: github.event_name == 'workflow_dispatch' && inputs.commit_generated_docs == 'true'
+        if: >
+          github.event_name == 'push' ||
+          (github.event_name == 'workflow_dispatch' && inputs.commit_generated_docs == 'true')
         uses: stefanzweifel/git-auto-commit-action@v5
         with:
           commit_message: "docs: regenerate environment documentation"

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
+
+Source fingerprint: `d6aa78e3317a`
+
+## 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
+
+Source fingerprint: `d6aa78e3317a`
+
+## 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.

mkdocs.yml

@@ -0,0 +1,20 @@
+site_name: Infrastructure Documentation
+site_description: Generated and maintained infrastructure documentation
+repo_url: https://github.com/beatz174-bit/docker
+docs_dir: docs
+
+nav:
+  - Home: index.md
+  - Docker Environment: docker.md
+  - Networking: networking.md
+  - Monitoring: monitoring.md
+  - Automation: automation.md
+  - Operations: operations.md
+  - Public Showcase: showcase.md
+  - Generated:
+      - Compose Inventory: generated/compose-inventory.md
+      - Traefik Routes: generated/traefik-routes.md
+      - Prometheus Rules: generated/prometheus-rules.md
+
+theme:
+  name: mkdocs

scripts/docs/generate-all.sh

@@ -7,5 +7,6 @@ scripts/docs/render-compose-config.sh
 python3 scripts/docs/generate-compose-inventory.py docs/generated/docker-compose.resolved.yml docs/generated/compose-inventory.md
 python3 scripts/docs/generate-traefik-routes.py docs/generated/docker-compose.resolved.yml docs/generated/traefik-routes.md
 python3 scripts/docs/generate-prometheus-rules.py docs/generated/prometheus-rules.md
+python3 scripts/docs/generate-docs-index.py docs/generated/index.md
 python3 scripts/docs/generate-diagrams.py docs/generated/docker-compose.resolved.yml docs/diagrams/docker-compose.dot docs/diagrams/docker-compose.svg
 python3 scripts/docs/sanitize-public-docs.py docs/generated docs/diagrams docs/public

scripts/docs/generate-compose-inventory.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
+import hashlib
 import sys, yaml
-from datetime import datetime, timezone
 
 def md(v): return str(v).replace('|','\\|') if v is not None else ''
 
@@ -9,7 +9,9 @@ with open(inp) as f: c=yaml.safe_load(f) or {}
 svcs=c.get('services',{}) or {}
 nets=c.get('networks',{}) or {}
 vols=c.get('volumes',{}) or {}
-lines=["# Docker Compose Inventory","",f"Generated: {datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')}","","## Summary","","| Item | Count |","|---|---:|",f"| Services | {len(svcs)} |",f"| Networks | {len(nets)} |",f"| Volumes | {len(vols)} |","","## Services","","| Service | Container | Image | Build | Profiles | Networks | Ports | Restart |","|---|---|---|---|---|---|---|---|"]
+raw=open(inp,'rb').read()
+fingerprint=hashlib.sha256(raw).hexdigest()[:12]
+lines=["# Docker Compose Inventory","",f"Source fingerprint: `{fingerprint}`","","## Summary","","| Item | Count |","|---|---:|",f"| Services | {len(svcs)} |",f"| Networks | {len(nets)} |",f"| Volumes | {len(vols)} |","","## Services","","| Service | Container | Image | Build | Profiles | Networks | Ports | Restart |","|---|---|---|---|---|---|---|---|"]
 for n,s in sorted(svcs.items()):
     build=s.get('build','')
     if isinstance(build,dict): build=build.get('context','')

scripts/docs/generate-docs-index.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+from pathlib import Path
+import sys
+
+out = Path(sys.argv[1])
+out.parent.mkdir(parents=True, exist_ok=True)
+out.write_text(
+    """# 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)
+"""
+)

scripts/docs/sanitize-public-docs.py

@@ -1,18 +1,46 @@
 #!/usr/bin/env python3
-import sys,re,shutil
+import re
+import sys
 from pathlib import Path
-srcg,srcd,out=sys.argv[1],sys.argv[2],sys.argv[3]
-outp=Path(out)
-outp.mkdir(parents=True,exist_ok=True)
-for src in [Path(srcg),Path(srcd)]:
-    for f in src.rglob('*'):
-        if not f.is_file(): continue
-        rel=f.relative_to(src)
-        dest=outp/src.name/rel
-        dest.parent.mkdir(parents=True,exist_ok=True)
-        txt=f.read_text(errors='ignore')
-        txt=re.sub(r'\b[a-zA-Z0-9.-]+\.lan\.ddnsgeek\.com\b','<internal-domain>',txt)
-        txt=re.sub(r'\b(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3})\b','<private-ip>',txt)
-        txt=re.sub(r'(?i)\b(password|token|api_key|secret)\s*[:=]\s*[^\s\n]+',r'\1=<redacted>',txt)
-        txt=re.sub(r'(?m)^([A-Z0-9_]*(?:PASSWORD|TOKEN|API_KEY|SECRET)[A-Z0-9_]*)\s*[:=]\s*.*$',r'\1=<redacted>',txt)
-        dest.write_text(txt)
+
+src_generated = Path(sys.argv[1])
+src_diagrams = Path(sys.argv[2])
+out_dir = Path(sys.argv[3])
+out_dir.mkdir(parents=True, exist_ok=True)
+
+
+def sanitize_text(content: str) -> str:
+    content = re.sub(r'\b[a-zA-Z0-9.-]+\.lan\.ddnsgeek\.com\b', '<internal-domain>', content)
+    content = re.sub(
+        r'\b(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3})\b',
+        '<private-ip>',
+        content,
+    )
+    content = re.sub(r'(?i)\b(password|token|api[_-]?key|secret)\s*[:=]\s*[^\s\n]+', r'\1=<redacted>', content)
+    content = re.sub(r'(?m)^([A-Z0-9_]*(?:PASSWORD|TOKEN|API_KEY|SECRET)[A-Z0-9_]*)\s*[:=]\s*.*$', r'\1=<redacted>', content)
+    return content
+
+for name in ['compose-inventory.md', 'traefik-routes.md', 'prometheus-rules.md']:
+    src = src_generated / name
+    if src.exists():
+        (out_dir / name).write_text(sanitize_text(src.read_text(errors='ignore')))
+
+svg_src = src_diagrams / 'docker-compose.svg'
+if svg_src.exists():
+    (out_dir / 'docker-compose.svg').write_text(sanitize_text(svg_src.read_text(errors='ignore')))
+
+(out_dir / 'index.md').write_text(
+    """# 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)
+"""
+)