99 lines
3.1 KiB
Markdown
99 lines
3.1 KiB
Markdown
# 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.
|
|
|
|
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.
|
|
|
|
## Prerequisites
|
|
|
|
- Docker Engine with the Docker Compose plugin
|
|
- PowerShell 7 or Windows PowerShell 5.1 for the local secret helper
|
|
|
|
The pinned images are `grafana/grafana:13.2.2` and
|
|
`postgres:18.6-alpine`. Do not replace them with `latest`.
|
|
|
|
## Prepare local secrets
|
|
|
|
Copy the non-secret environment template and create three random secret files:
|
|
|
|
```powershell
|
|
Copy-Item .env.example .env
|
|
./scripts/initialize-local-secrets.ps1
|
|
```
|
|
|
|
The helper creates these ignored files without printing their values:
|
|
|
|
```text
|
|
.local/secrets/grafana_admin_password
|
|
.local/secrets/grafana_database_password
|
|
.local/secrets/postgres_admin_password
|
|
```
|
|
|
|
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.
|
|
|
|
## Start and verify
|
|
|
|
Start the local stack:
|
|
|
|
```powershell
|
|
docker compose -f compose.yaml -f compose.sandbox.yaml up -d
|
|
docker compose -f compose.yaml -f compose.sandbox.yaml ps
|
|
```
|
|
|
|
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>.
|
|
|
|
Confirm that PostgreSQL is not published to the host:
|
|
|
|
```powershell
|
|
docker compose -f compose.yaml -f compose.sandbox.yaml port postgres 5432
|
|
```
|
|
|
|
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"`.
|
|
|
|
## Stop or reset
|
|
|
|
Stop containers while preserving their named volumes:
|
|
|
|
```powershell
|
|
docker compose -f compose.yaml -f compose.sandbox.yaml down
|
|
```
|
|
|
|
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:
|
|
|
|
```powershell
|
|
docker compose -f compose.yaml -f compose.sandbox.yaml down --volumes
|
|
```
|
|
|
|
## Supply test logs
|
|
|
|
Put 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.
|
|
|