Files
grafana/README.md
T
2026-10-05 08:55:26 +01:00

124 lines
4.4 KiB
Markdown

# Kiosk observability proof of concept
This repository contains the version-controlled dashboards, documentation, and
test fixtures for the kiosk reporting platform. The first runnable milestone is
Grafana OSS backed by PostgreSQL on an Ubuntu 24.04 sandbox.
Grafana and PostgreSQL are installed natively through the central Salt and
Pillar repositories, following the same operational model as CMS and CMS Front.
Docker is not used. The Salt deployment templates are authoritative.
## Current milestone
The native deployment installs and holds:
- Grafana OSS 13.2.2
- PostgreSQL 18.6
Grafana stores its users, organizations, data-source configuration, and
dashboards in a dedicated PostgreSQL database. Both services listen only on the
sandbox loopback interface. Nginx, TLS, Loki, reporting aggregation, dashboards,
and production deployment are later milestones.
## Deployment sources
The native automation is split between the existing repositories:
```text
grafana/ documentation, future dashboards, tests, and log fixtures
salt/ package repositories, installation, configuration, and services
pillar/ non-secret versions, ports, paths, and database identifiers
```
The reusable Salt state is deliberately not assigned to any minion. A sandbox
minion must be named and authorized before it is added to either `top.sls`.
## Prepare an Ubuntu sandbox
The target must be Ubuntu 24.04 AMD64 with Salt Minion access and outbound HTTPS
access to the official Grafana and PostgreSQL package repositories.
After the sandbox minion is named and deployment is authorized, add that minion
to the `grafana` state in `salt/top.sls` and to the non-secret `grafana` Pillar
in `pillar/top.sls`. Refresh its Pillar data before applying the commands below.
Do not reuse an existing production target for this assignment.
First install the packages, secret directories, and root-only secret helper:
```bash
sudo salt-call state.apply grafana.bootstrap
```
Generate the two initial secrets on the sandbox:
```bash
sudo /usr/local/sbin/kiosk-observability-init-secrets
```
The helper creates, but never prints or overwrites:
```text
/etc/kiosk-observability/secrets/grafana_admin_password
/etc/kiosk-observability/secrets/grafana_database_password
```
Both files are owned by `root:grafana` and have mode `0640`. If the operator
supplies the files through another approved secret-management process, use the
same paths, ownership, and permissions. The administrator password must satisfy
Grafana's strong-password policy; the database password must be a strong
single-line Base64 value.
Preview the complete state before applying it:
```bash
sudo salt-call state.apply grafana test=True
sudo salt-call state.apply grafana
```
The complete state refuses to start Grafana when a required secret is missing.
Applying it a second time should produce no changes.
## Verify the services
Run these checks on the sandbox:
```bash
sudo systemctl status postgresql grafana-server
sudo ss -lntp | grep -E ':(3000|5432)\b'
curl --fail --silent http://127.0.0.1:3000/api/health
apt-mark showhold | grep -E '^(grafana|postgresql-18)$'
```
Grafana must listen only on `127.0.0.1:3000`, PostgreSQL only on
`127.0.0.1:5432`, and the health response must include `"database":"ok"`.
## Connect through SSH
Until Nginx and TLS are implemented, do not expose port 3000 on the sandbox.
Create a tunnel from the operator workstation:
```bash
ssh -L 3000:127.0.0.1:3000 <user>@<sandbox-host>
```
Open <http://127.0.0.1:3000> locally and sign in as `admin` with the initial
password from the sandbox secret file. The configured admin password is used
only when Grafana creates its first administrator. Later password rotations must
use Grafana's supported administrator workflow and update the external secret
record to match.
## Supply test logs
Place logs awaiting review in `testing/logs/incoming/`. The directory is present
in Git, but its contents are ignored. Read `testing/logs/README.md` before adding
files. Only fully sanitized, explicitly approved samples may later be placed in
`tests/fixtures/`.
## Safety boundaries
- Do not store passwords, tokens, certificates, private keys, database dumps,
or real guest logs in Git or Pillar.
- Do not assign the Grafana state to a production minion during this milestone.
- Do not expose Grafana or PostgreSQL directly to a network.
- Do not commit, push, or deploy changes without operator authorization.