beatzaplenty/docker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: fix Mermaid labels for GitHub parser compatibility

Browse Source
This commit is contained in:
beatz174-bit
2026-04-13 16:54:37 +10:00
parent 72cda2dc92
commit 4eed2fd710
7 changed files with 706 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+37
View File
@@ -113,3 +113,40 @@ Unknowns (left intentionally as placeholders):
- **Inter-host VLAN/subnet layout beyond Docker bridges:** _unknown from repo contents._
If you want, this section can be replaced with a concrete Proxmox topology once you add an inventory source (e.g., Terraform, Ansible inventory, or a diagram export).
## Runtime visibility from Prometheus
<!-- BEGIN GENERATED PROMETHEUS SECTION -->
Prometheus inventory provides **observed runtime coverage** of scrape targets. It complements (but does not replace) declared architecture in Compose files and static docs.
- Inventory timestamp: `2026-04-13T06:36:45Z`
- Observed jobs: `8`
- Observed instances: `19`
- Observed services (label-derived): `1`
### Observed monitoring view
| job | targets | unhealthy |
| --- | --- | --- |
| container-updates | 2 | 0 |
| kuma | 2 | 0 |
| node | 7 | 0 |
| pihole | 1 | 0 |
| prometheus | 1 | 0 |
| proxmox-storage | 2 | 0 |
| telegraf | 2 | 0 |
| traefik | 2 | 0 |
### Data sources
- `docs/runtime/prometheus-inventory.json` (normalized runtime export)
- Prometheus scrape metadata (`targets` + label sets)
- Existing repository architecture docs for declared topology
### Notes from inventory
- The `up` query indicates scrape success from Prometheus perspective only.
- Use static repository architecture docs and deployment configs with this runtime export for complete diagrams.
<!-- END GENERATED PROMETHEUS SECTION -->
docs/diagrams/architecture.mmd
+17
View File
@@ -0,0 +1,17 @@
flowchart TB
Declared[Declared architecture<br/>(Compose + docs)]
Runtime[Observed runtime<br/>(Prometheus inventory)]
Declared --> Runtime
subgraph Monitoring["Prometheus observed jobs"]
job_container_updates["container-updates"]
job_kuma["kuma"]
job_node["node"]
job_pihole["pihole"]
job_prometheus["prometheus"]
job_proxmox_storage["proxmox-storage"]
job_telegraf["telegraf"]
job_traefik["traefik"]
end
Runtime --> Monitoring
docs/diagrams/monitoring-coverage.mmd
+90
View File
@@ -0,0 +1,90 @@
flowchart LR
Prom[Prometheus]
classDef scrape stroke-dasharray: 5 5;
subgraph host_docker_update_exporter["Host: docker-update-exporter"]
container_updates_docker_update_exporter_9105["container-updates<br/>docker-update-exporter:9105"]
end
subgraph host_kuma_lan_ddnsgeek_com["Host: kuma.lan.ddnsgeek.com"]
kuma_kuma_lan_ddnsgeek_com["kuma<br/>kuma.lan.ddnsgeek.com"]
end
subgraph host_monitor_kuma["Host: monitor-kuma"]
kuma_monitor_kuma_3001["kuma<br/>monitor-kuma:3001"]
end
subgraph host_nix_cache["Host: nix-cache"]
node_nix_cache_9100["node<br/>nix-cache:9100"]
end
subgraph host_node_exporter["Host: node-exporter"]
node_node_exporter_9100["node<br/>node-exporter:9100"]
end
subgraph host_pbs_sweet_home["Host: pbs.sweet.home"]
node_pbs_sweet_home_9100["node<br/>pbs.sweet.home:9100"]
proxmox_storage_pbs_sweet_home_9102["proxmox-storage<br/>pbs.sweet.home:9102"]
end
subgraph host_pihole["Host: pihole"]
node_pihole_9100["node<br/>pihole:9100"]
end
subgraph host_pihole_exporter["Host: pihole-exporter"]
pihole_pihole_exporter_9617["pihole<br/>pihole-exporter:9617"]
end
subgraph host_prometheus["Host: prometheus"]
prometheus_prometheus_9090["prometheus<br/>prometheus:9090"]
end
subgraph host_pve_sweet_home["Host: pve.sweet.home"]
node_pve_sweet_home_9100["node<br/>pve.sweet.home:9100"]
proxmox_storage_pve_sweet_home_9101["proxmox-storage<br/>pve.sweet.home:9101"]
end
subgraph host_raspberrypi_tail13f623_ts_net["Host: raspberrypi.tail13f623.ts.net"]
container_updates_raspberrypi_tail13f623_ts_net_9105["container-updates<br/>raspberrypi.tail13f623.ts.net:9105"]
node_raspberrypi_tail13f623_ts_net_9100["node<br/>raspberrypi.tail13f623.ts.net:9100"]
telegraf_raspberrypi_tail13f623_ts_net_9273["telegraf<br/>raspberrypi.tail13f623.ts.net:9273"]
traefik_raspberrypi_tail13f623_ts_net_8080["traefik<br/>raspberrypi.tail13f623.ts.net:8080"]
end
subgraph host_server["Host: server"]
node_server_9100["node<br/>server:9100"]
end
subgraph host_telegraf["Host: telegraf"]
telegraf_telegraf_9273["telegraf<br/>telegraf:9273"]
end
subgraph host_traefik_lan_ddnsgeek_com["Host: traefik.lan.ddnsgeek.com"]
traefik_traefik_lan_ddnsgeek_com_8080["traefik<br/>traefik.lan.ddnsgeek.com:8080"]
end
Prom -. scrape .-> container_updates_docker_update_exporter_9105
class container_updates_docker_update_exporter_9105 scrape;
Prom -. scrape .-> container_updates_raspberrypi_tail13f623_ts_net_9105
class container_updates_raspberrypi_tail13f623_ts_net_9105 scrape;
Prom -. scrape .-> kuma_kuma_lan_ddnsgeek_com
class kuma_kuma_lan_ddnsgeek_com scrape;
Prom -. scrape .-> kuma_monitor_kuma_3001
class kuma_monitor_kuma_3001 scrape;
Prom -. scrape .-> node_nix_cache_9100
class node_nix_cache_9100 scrape;
Prom -. scrape .-> node_node_exporter_9100
class node_node_exporter_9100 scrape;
Prom -. scrape .-> node_pbs_sweet_home_9100
class node_pbs_sweet_home_9100 scrape;
Prom -. scrape .-> node_pihole_9100
class node_pihole_9100 scrape;
Prom -. scrape .-> node_pve_sweet_home_9100
class node_pve_sweet_home_9100 scrape;
Prom -. scrape .-> node_raspberrypi_tail13f623_ts_net_9100
class node_raspberrypi_tail13f623_ts_net_9100 scrape;
Prom -. scrape .-> node_server_9100
class node_server_9100 scrape;
Prom -. scrape .-> pihole_pihole_exporter_9617
class pihole_pihole_exporter_9617 scrape;
Prom -. scrape .-> prometheus_prometheus_9090
class prometheus_prometheus_9090 scrape;
Prom -. scrape .-> proxmox_storage_pbs_sweet_home_9102
class proxmox_storage_pbs_sweet_home_9102 scrape;
Prom -. scrape .-> proxmox_storage_pve_sweet_home_9101
class proxmox_storage_pve_sweet_home_9101 scrape;
Prom -. scrape .-> telegraf_raspberrypi_tail13f623_ts_net_9273
class telegraf_raspberrypi_tail13f623_ts_net_9273 scrape;
Prom -. scrape .-> telegraf_telegraf_9273
class telegraf_telegraf_9273 scrape;
Prom -. scrape .-> traefik_raspberrypi_tail13f623_ts_net_8080
class traefik_raspberrypi_tail13f623_ts_net_8080 scrape;
Prom -. scrape .-> traefik_traefik_lan_ddnsgeek_com_8080
class traefik_traefik_lan_ddnsgeek_com_8080 scrape;
docs/monitoring-coverage.md
+77
View File
@@ -0,0 +1,77 @@
# Monitoring Coverage
## Overview
This page is generated from Prometheus-observed runtime inventory. It supplements declared architecture docs and does not replace static source-of-truth configuration.
- Inventory timestamp: `2026-04-13T06:36:45Z`
- Prometheus URL: `http://prometheus:9090`
- Active scrape targets observed: `19`
- Unhealthy scrape targets observed: `0`
## Coverage by job
| job | active targets | unhealthy targets |
| --- | --- | --- |
| container-updates | 2 | 0 |
| kuma | 2 | 0 |
| node | 7 | 0 |
| pihole | 1 | 0 |
| prometheus | 1 | 0 |
| proxmox-storage | 2 | 0 |
| telegraf | 2 | 0 |
| traefik | 2 | 0 |
## Coverage by instance
| instance | jobs | health |
| --- | --- | --- |
| docker-update-exporter:9105 | container-updates | 1/1 up |
| kuma.lan.ddnsgeek.com | kuma | 1/1 up |
| monitor-kuma:3001 | kuma | 1/1 up |
| nix-cache:9100 | node | 1/1 up |
| node-exporter:9100 | node | 1/1 up |
| pbs.sweet.home:9100 | node | 1/1 up |
| pbs.sweet.home:9102 | proxmox-storage | 1/1 up |
| pihole-exporter:9617 | pihole | 1/1 up |
| pihole:9100 | node | 1/1 up |
| prometheus:9090 | prometheus | 1/1 up |
| pve.sweet.home:9100 | node | 1/1 up |
| pve.sweet.home:9101 | proxmox-storage | 1/1 up |
| raspberrypi.tail13f623.ts.net:8080 | traefik | 1/1 up |
| raspberrypi.tail13f623.ts.net:9100 | node | 1/1 up |
| raspberrypi.tail13f623.ts.net:9105 | container-updates | 1/1 up |
| raspberrypi.tail13f623.ts.net:9273 | telegraf | 1/1 up |
| server:9100 | node | 1/1 up |
| telegraf:9273 | telegraf | 1/1 up |
| traefik.lan.ddnsgeek.com:8080 | traefik | 1/1 up |
## Coverage by service
| service | instances | health |
| --- | --- | --- |
| unknown | docker-update-exporter:9105, kuma.lan.ddnsgeek.com, monitor-kuma:3001, nix-cache:9100, node-exporter:9100, pbs.sweet.home:9100, pbs.sweet.home:9102, pihole-exporter:9617, pihole:9100, prometheus:9090, pve.sweet.home:9100, pve.sweet.home:9101, raspberrypi.tail13f623.ts.net:8080, raspberrypi.tail13f623.ts.net:9100, raspberrypi.tail13f623.ts.net:9105, raspberrypi.tail13f623.ts.net:9273, server:9100, telegraf:9273, traefik.lan.ddnsgeek.com:8080 | 19/19 up |
## Unhealthy targets
| job | instance | scrape URL | health | last error |
| --- | --- | --- | --- | --- |
| none | | | | |
## Unknowns / missing metadata
| label | targets missing |
| --- | --- |
| exposure | 19 |
| hostname | 19 |
| hypervisor | 19 |
| network | 19 |
| service | 19 |
Unknown or missing metadata is treated as `unknown` in generated summaries to avoid over-claiming topology.
## Regeneration instructions
```bash
python3 scripts/render_prometheus_docs.py --inventory-file docs/runtime/prometheus-inventory.json
```
docs/network.md
+52
View File
@@ -0,0 +1,52 @@
# Network and Exposure View (Prometheus Observed)
## Overview
This document is generated from Prometheus scrape metadata and endpoint URLs. It is an observed monitoring view and not a physical network map.
- Inventory timestamp: `2026-04-13T06:36:45Z`
- Physical topology, VLAN mapping, and bridge membership remain unknown unless explicitly documented elsewhere.
## Observed scrape endpoints
| job | instance | scrape URL | network label | exposure label |
| --- | --- | --- | --- | --- |
| container-updates | docker-update-exporter:9105 | http://docker-update-exporter:9105/metrics | unknown | unknown |
| container-updates | raspberrypi.tail13f623.ts.net:9105 | http://raspberrypi.tail13f623.ts.net:9105/metrics | unknown | unknown |
| kuma | kuma.lan.ddnsgeek.com | http://kuma.lan.ddnsgeek.com/metrics | unknown | unknown |
| kuma | monitor-kuma:3001 | http://monitor-kuma:3001/metrics | unknown | unknown |
| node | nix-cache:9100 | http://nix-cache:9100/metrics | unknown | unknown |
| node | node-exporter:9100 | http://node-exporter:9100/metrics | unknown | unknown |
| node | pbs.sweet.home:9100 | http://pbs.sweet.home:9100/metrics | unknown | unknown |
| node | pihole:9100 | http://pihole:9100/metrics | unknown | unknown |
| node | pve.sweet.home:9100 | http://pve.sweet.home:9100/metrics | unknown | unknown |
| node | raspberrypi.tail13f623.ts.net:9100 | http://raspberrypi.tail13f623.ts.net:9100/metrics | unknown | unknown |
| node | server:9100 | http://server:9100/metrics | unknown | unknown |
| pihole | pihole-exporter:9617 | http://pihole-exporter:9617/metrics | unknown | unknown |
| prometheus | prometheus:9090 | http://prometheus:9090/metrics | unknown | unknown |
| proxmox-storage | pbs.sweet.home:9102 | http://pbs.sweet.home:9102/metrics | unknown | unknown |
| proxmox-storage | pve.sweet.home:9101 | http://pve.sweet.home:9101/metrics | unknown | unknown |
| telegraf | raspberrypi.tail13f623.ts.net:9273 | http://raspberrypi.tail13f623.ts.net:9273/metrics | unknown | unknown |
| telegraf | telegraf:9273 | http://telegraf:9273/metrics | unknown | unknown |
| traefik | raspberrypi.tail13f623.ts.net:8080 | http://raspberrypi.tail13f623.ts.net:8080/metrics | unknown | unknown |
| traefik | traefik.lan.ddnsgeek.com:8080 | http://traefik.lan.ddnsgeek.com:8080/metrics | unknown | unknown |
## Internal vs public indicators
| exposure label | targets |
| --- | --- |
| unknown | 19 |
All indicators above are label-derived. Missing labels are rendered as `unknown`.
## Monitoring paths
| metrics path | observed targets |
| --- | --- |
| /metrics | 19 |
## Unknowns and limits
- Prometheus can confirm scrape reachability but not ownership or placement boundaries.
- No VLAN, switch, or hypervisor placement is inferred unless present in inventory labels.
- Treat this as runtime evidence to pair with declared architecture docs.