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:

Copy-Item .env.example .env
./scripts/initialize-local-secrets.ps1

The helper creates these ignored files without printing their values:

.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:

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:

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:

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:

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:

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.

3.1 KiB Raw Blame History