Get started

Set up the app

Sign in, turn on push and make the app yours. The board must be running and reachable at its public_url first: see Install the board.

Install the app

PiDash is in TestFlight, Apple's beta programme, and we're looking for testers. The app is free while it's in TestFlight.

1. Install TestFlight from the App Store.
2. Open the PiDash beta link on your iPhone, tap Accept and install PiDash from TestFlight.
3. In TestFlight, open PiDash and turn on Automatic Updates. A TestFlight build expires after 90 days; with automatic updates you always have a current one.

Found a bug or have an idea? Take a screenshot in the app and TestFlight offers to send it as feedback, or use Send Beta Feedback in TestFlight, or mail us.

Sign in

1. Open PiDash.
2. Enter your board's public_url, for example https://board.example.com.
3. Log in with your OIDC provider in the system login sheet.
4. The board asks “Sign in to the PiDash app?”. Confirm, and the app keeps a session token in the iPhone's keychain.

Your account must be in the board's oidc.groups.users group. The app needs a board version with the /auth/app endpoints, so a board from before the app can't be used with it: update the board first.

Which screens you see

The app shows a screen once the board has the connection behind it, and the actions on it once your groups allow them.

Push notifications

With push on, the board sends:

• Critical alerts as soon as Alertmanager fires them, unacked, to the phones that turned on “Critical alerts”. The notification has Ack and Open, and a “Resolved” push clears it again.
• New approvals to the phones of those who may decide them, with Approve and Deny (each asks for Face ID).

Your board encrypts each notification for your phone and sends it through the PiDash push relay to Apple. The relay can't read it; the app decrypts it on the phone. See Push notifications for how.

1. On the board, add to config.yaml:

   connections:
     apns:
       relay: https://push.pidash.io

2. Restart the board: docker compose restart alertboard.
3. In the app, open More › Settings, allow notifications and turn on Critical alerts.
4. Tap Send test notification to check it.

Quiet hours, also in Settings, hold notifications without sound in Notification Centre during the hours you pick. They are set per phone.

Ack from any notification

Already get alerts through Pushover, ntfy, e-mail or chat? Point each notification's link at the board's action page, <public_url>/a?env=…&fp=…, and every notification gets an Ack button (and, with OneUptime, Declare incident). For a Pushover receiver in Alertmanager:

pushover_configs:
  - url: '{{ with index .Alerts 0 }}https://board.example.com/a?env=production&fp={{ .Fingerprint }}{{ end }}'
    url_title: Open in PiDash

env must be the Alertmanager connection's name in config.yaml.

Tabs and dashboard

• Dashboard is your own first screen: tap Edit to remove or reorder widgets, and Add widget to pick from what your board has (alert counts, unacked critical alerts, open incidents, waiting approvals, today's failed jobs, overdue findings, any metrics tile, …). The layout is kept on the phone, one per board.
• More › Settings › Tab bar: drag the tabs into the order you like, hide Dashboard, Alerts, Incidents or Findings, and pin More's screens (Approvals, Calendar, Maintenance, Runbooks, Metrics, Kubernetes, Networks, Terminal) as tabs of their own. At most four tabs fit beside More. The choice survives signing out.

Face ID and fresh logins

The app asks for Face ID (or the passcode) before anything that changes something: a long silence, maintenance, an approval, a runbook, a Kubernetes action, an incident's state or a terminal session.

On top of that, the board asks for a fresh login for its riskier actions: approvals, runbooks, Kubernetes actions, maintenance, silences over a day and publishing incidents need a login of at most 15 minutes; the terminal and editing networks need one of at most 5 minutes. The app sends you through your provider's login again when yours is older.

Sessions last 30 days. Removing someone from a group takes effect at their next login; changing secrets/session_key logs everyone out at once.