124 lines
4.4 KiB
Markdown
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.
|