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