Run it

Troubleshooting

Start with /api/connections: it says, per system, what works and what is missing.

Check every connection

The board checks every connection at start and every 5 minutes. On the Pi itself:

curl -s http://127.0.0.1:8080/api/connections

On the public URL it answers for oidc.groups.admins, or operators when no admins group is set. Each row looks like this:

{"type": "awx", "name": "awx", "reachable": true, "logged_in": true,
 "missing": ["workflow Security - Expedited patch"],
 "last_worked": "2026-10-31T09:00:00Z", "error": ""}

Field	What it tells you
`reachable`	The system answered at all. `false` with `unreachable`, `TLS` or `timeout` is a network, DNS or certificate problem. For `TLS`, set the connection's `ca_file`.
`logged_in`	`false` with `401` or `403` is a wrong or expired secret.
`missing`	Rights the login lacks, where the system can say. The Connections page lists what each one needs.
`null`	Not known yet: nothing tried so far.

The board's log has the full error:

docker compose logs alertboard | grep "connection check"

Common problems

The board doesn't start

Run docker compose logs alertboard. A mistake in config.yaml (an unknown key, a missing setting) or a secret file with the wrong mode stops start-up with a message naming the setting or the file. Fix it (chmod 600 secrets/* for the latter) and run docker compose up -d. An old-format file needs converting.

The app can't sign in to my board

The board must be reachable at its public_url over HTTPS, and be a version with the /auth/app endpoints. Check that your OIDC client's redirect URI is <public_url>/auth/callback and that your account is in the oidc.groups.users group.

“Your account is not allowed”

Your account is not in oidc.groups.users, or the ID token has no groups claim. Group names must match exactly. In Keycloak, add a Group Membership mapper with Full group path off (see OIDC). After changing someone's groups, they log in again.

Logging in on http://<pi>:8081 doesn't work

The session cookie is Secure, so the board only logs in over HTTPS. Use public_url through your reverse proxy, from the LAN too.

I don't get push notifications

Push needs connections.apns in the board's config.yaml: relay: https://push.pidash.io (see Push notifications). In the app, open More › Settings, turn on “Critical alerts” and tap “Send test notification”:

“update PiDash on your phone”: the phone runs PiDash older than 1.0.12, from before encrypted push. Update it in TestFlight and open it once.
“no phone of yours is registered for push”: allow notifications for PiDash in iOS Settings, then open the app again.
“push is off on this board”: connections.apns is missing, or the board wasn't restarted.
“push relay: …”: the board can't reach push.pidash.io over HTTPS, or the relay refused the push; the push relay row in /api/connections says which.

Only alerts with severity critical are pushed. During your quiet hours they arrive without sound, in Notification Centre.

A screen I expect is missing

Each screen appears once the board has the connection behind it: Incidents need OneUptime, Kubernetes needs a kubeconfig, Terminal needs Proxmox with terminal_tag and you in admins. See which screens you see, and check the connection in /api/connections.

Kubernetes shows no namespaces, or no actions

A namespace shows where the service account may list Deployments, StatefulSets, DaemonSets, CronJobs and pods; the actions follow from its Role's verbs, and only for operators. Without list on namespaces only the kubeconfig context's namespace is used. /api/connections names what is missing. A server on 127.0.0.1 in the kubeconfig points at the container: use the LAN address.

Terminal says the host key is not confirmed

The first time, or after a host's key changed, an admin confirms its SHA256 fingerprint in the app. Compare it with ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub on the host's console. See Confirm the host's key.

A terminal host says “no address in a scanned network”

The guest reported an address outside every network the board knows. Add that network under scan.networks in config.yaml, or in the app under More › Networks.

The kiosk shows nothing at http://localhost:8080

Use http://127.0.0.1:8080: localhost may resolve to ::1, which the port is not published on.

A calendar time is an hour or two off

Every time is shown on the board's timezone. Kubernetes, Longhorn and Harbor run their schedules on UTC, so a CronJob at 02:00 shows at 03:00 in winter in Amsterdam. Proxmox schedules are taken to be on the board's clock.

Still stuck?

Email support@koper.cloud with the board's version, the /api/connections row of the system involved and the relevant lines of docker compose logs alertboard. Remove host names and addresses you'd rather not share.