grafan update
This commit is contained in:
@@ -1,98 +1,123 @@
|
||||
# Kiosk observability proof of concept
|
||||
|
||||
This repository contains the first local milestone for the kiosk reporting
|
||||
platform: Grafana OSS backed by a dedicated PostgreSQL metadata database. Loki,
|
||||
reporting aggregation, Nginx/TLS, tenant bootstrap, and production deployment
|
||||
will be added in later milestones.
|
||||
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 is available only through a loopback sandbox port. PostgreSQL has no
|
||||
published host port. Nginx will replace the direct Grafana port when HTTPS is
|
||||
introduced.
|
||||
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.
|
||||
|
||||
## Prerequisites
|
||||
## Current milestone
|
||||
|
||||
- Docker Engine with the Docker Compose plugin
|
||||
- PowerShell 7 or Windows PowerShell 5.1 for the local secret helper
|
||||
The native deployment installs and holds:
|
||||
|
||||
The pinned images are `grafana/grafana:13.2.2` and
|
||||
`postgres:18.6-alpine`. Do not replace them with `latest`.
|
||||
- Grafana OSS 13.2.2
|
||||
- PostgreSQL 18.6
|
||||
|
||||
## Prepare local secrets
|
||||
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.
|
||||
|
||||
Copy the non-secret environment template and create three random secret files:
|
||||
## Deployment sources
|
||||
|
||||
```powershell
|
||||
Copy-Item .env.example .env
|
||||
./scripts/initialize-local-secrets.ps1
|
||||
```
|
||||
|
||||
The helper creates these ignored files without printing their values:
|
||||
The native automation is split between the existing repositories:
|
||||
|
||||
```text
|
||||
.local/secrets/grafana_admin_password
|
||||
.local/secrets/grafana_database_password
|
||||
.local/secrets/postgres_admin_password
|
||||
grafana/ documentation, future dashboards, tests, and log fixtures
|
||||
salt/ package repositories, installation, configuration, and services
|
||||
pillar/ non-secret versions, ports, paths, and database identifiers
|
||||
```
|
||||
|
||||
It does not overwrite an existing secret. For a deployed Linux environment,
|
||||
create equivalent restricted files below `/etc/kiosk-observability/secrets` and
|
||||
set `SECRETS_DIR` in the host's untracked `.env` file to that directory.
|
||||
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`.
|
||||
|
||||
## Start and verify
|
||||
## Prepare an Ubuntu sandbox
|
||||
|
||||
Start the local stack:
|
||||
The target must be Ubuntu 24.04 AMD64 with Salt Minion access and outbound HTTPS
|
||||
access to the official Grafana and PostgreSQL package repositories.
|
||||
|
||||
```powershell
|
||||
docker compose -f compose.yaml -f compose.sandbox.yaml up -d
|
||||
docker compose -f compose.yaml -f compose.sandbox.yaml ps
|
||||
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
|
||||
```
|
||||
|
||||
Open <http://127.0.0.1:3000> and sign in as `admin` with the value stored in
|
||||
`.local/secrets/grafana_admin_password`. The health endpoint is
|
||||
<http://127.0.0.1:3000/api/health>.
|
||||
Generate the two initial secrets on the sandbox:
|
||||
|
||||
Confirm that PostgreSQL is not published to the host:
|
||||
|
||||
```powershell
|
||||
docker compose -f compose.yaml -f compose.sandbox.yaml port postgres 5432
|
||||
```bash
|
||||
sudo /usr/local/sbin/kiosk-observability-init-secrets
|
||||
```
|
||||
|
||||
The command should report that no public port exists. To confirm Grafana is
|
||||
using PostgreSQL, inspect the health response and container logs; the health
|
||||
response should report `"database": "ok"`.
|
||||
The helper creates, but never prints or overwrites:
|
||||
|
||||
## Stop or reset
|
||||
|
||||
Stop containers while preserving their named volumes:
|
||||
|
||||
```powershell
|
||||
docker compose -f compose.yaml -f compose.sandbox.yaml down
|
||||
```text
|
||||
/etc/kiosk-observability/secrets/grafana_admin_password
|
||||
/etc/kiosk-observability/secrets/grafana_database_password
|
||||
```
|
||||
|
||||
Starting the stack again should retain Grafana metadata. Removing volumes
|
||||
permanently deletes the local databases and must only be done when an intentional
|
||||
clean reset is required:
|
||||
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.
|
||||
|
||||
```powershell
|
||||
docker compose -f compose.yaml -f compose.sandbox.yaml down --volumes
|
||||
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
|
||||
|
||||
Put logs awaiting review in `testing/logs/incoming/`. The directory is present
|
||||
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/`.
|
||||
|
||||
## Validate configuration
|
||||
|
||||
After preparing `.env` and the local secrets, render the merged configuration:
|
||||
|
||||
```powershell
|
||||
docker compose -f compose.yaml -f compose.sandbox.yaml config
|
||||
```
|
||||
|
||||
The output must show secret file paths only. It must not contain the contents of
|
||||
any password file. Do not commit `.env`, `.local/`, raw logs, certificates,
|
||||
private keys, database dumps, or runtime data.
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user