Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,8 +193,9 @@ $ make help
```

<!-- Dashboard screenshots go here once the stack has real data worth showing.
docs/images/README.md lists the filenames to use, how to capture them,
and what to check for before publishing them publicly. -->
`make screenshots` captures them; docs/images/README.md lists the
filenames, and says why the Logs dashboard is deliberately not among
them. -->

## What runs it

Expand Down
29 changes: 20 additions & 9 deletions docs/images/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,9 @@ make screenshots
```

`scripts/capture-screenshots.sh` starts the `capture` profile's renderer, shoots
all five dashboards over a 24-hour window, and stops the renderer again. Nothing
is left running and `docker compose ps` shows the same six services afterwards.
four of the five dashboards over a 24-hour window, and stops the renderer again.
Nothing is left running and `docker compose ps` shows the same six services
afterwards.

Filenames and dashboards are paired in the script, not here, so they cannot
drift:
Expand All @@ -26,7 +27,6 @@ drift:
| `docker-containers.png` | Docker Containers |
| `network-snmp.png` | Network & Firewall |
| `ups-power.png` | UPS & Power |
| `logs-explorer.png` | Logs |

Height is derived per dashboard from its own JSON, so adding a panel makes the
screenshot taller instead of pushing the new panel out of frame.
Expand All @@ -44,19 +44,30 @@ what the screenshot is for.
`make screenshots` is cheap and repeatable. Re-running it tomorrow is the
correct fix for a bad window, not cropping.

## The Logs dashboard is not captured

There are five dashboards and four screenshots. `homelab-logs` is excluded on
purpose.

Its Authentication log panel renders `auth.log` verbatim — real usernames, real
source addresses, real session IDs — and so do the other two stream panels. That
is not a bad time range or an unlucky window; showing log lines is the entire
point of the dashboard, so there is no capture of it that does not publish them.

Excluding it in the script beats capturing it and relying on someone noticing.
The check that catches this is the one that runs every time, not the one that
depends on reading carefully at the end of a long afternoon.

If it is ever wanted, the thing to build first is redaction — not a reminder.

## Before publishing

These are going into a public repository. Check each image for:

- Full MAC addresses in table panels
- The WAN IP address in any interface panel
- Hostnames or usernames in log lines
- Hostnames or usernames anywhere in a table or legend
- Anything in a Grafana annotation or query bar you did not mean to publish

The **Logs** dashboard is the one that reliably fails this check. Its
Authentication log panel renders `auth.log` verbatim, which means real
usernames, real source addresses and real session IDs. Read that image properly
before it goes anywhere.

Crop or blur rather than re-shooting — it is easier to be thorough. There is no
image editor on the monitoring host; do it wherever you are reading this.
7 changes: 6 additions & 1 deletion scripts/capture-screenshots.sh
Original file line number Diff line number Diff line change
Expand Up @@ -47,12 +47,17 @@ TIMEOUT="${CAPTURE_TIMEOUT:-180}"

# uid:filename. The uid is the contract — the filename is only what
# docs/images/README.md and the README's image block expect to find.
#
# homelab-logs is deliberately absent. Its Authentication log panel renders
# auth.log verbatim, so a capture contains real usernames, real source addresses
# and real session IDs — and there is no way to shoot it that does not, because
# showing log lines is what the dashboard is for. Adding it back means solving
# redaction first, not remembering to check afterwards.
DASHBOARDS=(
"homelab-host-overview:host-overview.png"
"homelab-docker:docker-containers.png"
"homelab-network:network-snmp.png"
"homelab-ups:ups-power.png"
"homelab-logs:logs-explorer.png"
)

# shellcheck source=secrets-env.sh
Expand Down
Loading