Documentation

Set up PiDash

Everything you need to run the board and connect the app, from the first install to the last connection.

How it fits together

PiDash has two parts:

The board (PiDashboard): one Docker Compose project, made for a Raspberry Pi, that runs on your own network. It holds the API keys, the SSH key and the kubeconfig, talks to your homelab's systems, logs who did what, and doubles as a wall board on a Pi touchscreen. It is free, and installs from Docker Hub.
The app (PiDash): the iPhone app. It talks only to your board, over HTTPS, and asks for Face ID before anything that changes something. It is in TestFlight and free while the beta runs: see Install the app.

 iPhone app  ──HTTPS──▶  PiDashboard on the Pi  ──▶  Alertmanager, Prometheus,
 (Face ID,               (config.yaml, secrets/,      Kubernetes, SSH hosts,
  push)                   MariaDB)                     your networks, AWX, …

Your phone never holds a secret for your systems. There is no PiDash cloud and no account with us.

What you need

For the board

A Raspberry Pi 4 or 5 (arm64), or any Linux machine
Docker with the Compose plugin
At least one Alertmanager
An OIDC provider (Authentik, Keycloak, …) whose ID token carries a groups claim
A TLS reverse proxy for the board's public address
Network access from the board to every system it connects to

Everything else is optional, one connection per feature: Prometheus (history and metrics), OneUptime, AWX, Kubernetes, Proxmox (terminal and networks), Greenbone, Wazuh, Harbor and GitLab.

For the app

An iPhone with TestFlight, to join the beta (how)
The board, reachable over HTTPS at its public address

The way through

Follow these in order. Each step says how to check that it worked before you move on.

1. Install the board

Clone it, make the secrets, fill in config.yaml and start it.

2. Set up the app

3. Add connections

Per system: the login to make, the rights it needs and how to check it.

4. Decide who can do what

Four OIDC groups decide who may look, act, decide findings or open a terminal.

What each connection lights up

Every connection beyond Alertmanager is optional: a feature without its connection stays off, and its screen does not show in the app.

Connection	Lights up
Alertmanager	Alerts, acks, silences, maintenance, alert push. Required.
Prometheus	24-hour alert history, the Metrics view and its charts
OneUptime	Incidents and the status page
AWX	Approvals, runbooks, AWX schedules on the calendar
Kubernetes	Workloads, pods, logs and actions in the app; CronJobs on the calendar
Proxmox	Backup jobs on the calendar, Networks, the SSH terminal
Greenbone, Wazuh	Security findings; Wazuh agents in Metrics; scan schedules on the calendar
Harbor, GitLab	Their schedules on the calendar
APNs	Push notifications for critical alerts and approvals

Stuck? See Troubleshooting or contact support.