Set up

Configuration

Everything is set in config.yaml on the board, which you never commit. config.yaml.example in the repository lists every setting with a comment.

On this page

config.yaml
Secrets
Who can do what
Kiosk, browser and app
Built-in behaviour

config.yaml

The file holds only these blocks:

Setting	Meaning
`public_url`	The HTTPS address of the board from outside the device. Required.
`timezone`	The board's clock, an IANA name. Default `Europe/Amsterdam`.
`database`	MariaDB, made by compose. Keep the defaults.
`oidc`	Your OIDC provider and client, and `groups`: who may do what.
`connections`	One entry per system: `alertmanager` (one per environment), `prometheus`, `awx`, `kubernetes`, `findings`, `greenbone`, `wazuh`, `oneuptime`, `proxmox`, `harbor`, `gitlab`, `apns`. See Connections.
`ansible`	The AWX workflows whose approvals the board shows (`approvals`) and the job templates the app may launch (`runbooks`).
`scan`	Networks to scan besides Proxmox's (`networks`) and Proxmox networks to leave alone (`exclude`). See Networks.

An unknown key or a missing required setting stops start-up with a message saying what is wrong, so a typo never goes unnoticed. After changing the file, run docker compose restart alertboard.

Every connection may also set, where it applies:

token_file: a file with a bearer token;
basic_auth_file: a file with user:password (not both);
ca_file: the PEM file of the only CA to trust for its HTTPS URL. Default: the system roots. There is no “skip certificate checks”.

API keys and other secrets

Secret values never go in config.yaml. Every API key, token, password, private key and kubeconfig sits in its own file under secrets/, and config.yaml names it as /secrets/<file>, the path inside the container. For example, an AWX token:

printf '%s\n' '<the token>' > secrets/awx_token
chmod 600 secrets/awx_token

connections:
  awx:
    url: https://awx.example.com
    token_file: /secrets/awx_token

Each secret file holds one value. Surrounding whitespace is ignored; an empty file is an error.
A secret file must be readable by its owner only (mode 600 or 400). If any can be read by its group or by others, the board does not start: the log names the file and says to chmod 600 it.
CA certificates (ca_file) are not secret and may stay 644.
The settings that take a secret end in _file (token_file, password_file, basic_auth_file, …), plus kubeconfig.

Who can do what

Four groups in oidc.groups decide who may do what. Each is one group name or a list of names, matched exactly against the groups claim in the ID token.

oidc:
  groups:
    users: alertboard-users           # required
    operators: alertboard-operators   # default: users
    security: security                # default: operators
    admins: admins                    # default: none, so the terminal is off

Group	Default	May
`users`	required	Log in and look; ack, take an ack back, silence for up to a day; declare OneUptime incidents, add alerts to them, post internal notes; read pod logs; browse Kubernetes; see the networks.
`operators`	`users` (required once `ansible.runbooks` or a Kubernetes connection is set)	Decide approvals; launch runbooks; act on Kubernetes (as far as its RBAC allows); start or extend maintenance and silence for longer than a day; publish an incident, post public notes, change an incident's state.
`security`	`operators`	Decide findings: accepted risk, false positive, closed; declare an incident from one.
`admins`	none	Open a terminal and confirm a terminal host's key; add, delete and turn off networks in the app; see `/api/connections`. Without it the terminal is off.

Only members of users can log in at all; anyone else gets “Your account is not allowed” and no session. Your provider must put a groups claim in the ID token: Authentik's default profile scope mapping does; in Keycloak, add a Group Membership mapper (see OIDC).

Sessions keep the groups of the login and last 30 days, so after changing someone's groups they need to log in again.

Kiosk, browser and app

Where	Login	Can
The Pi's own screen, `http://127.0.0.1:8080`	None (actor `kiosk`)	Read; ack; declare a OneUptime incident from a firing alert and add alerts to one; mark a finding in progress. No notes, states, publishing or Kubernetes.
Any other browser, `public_url`	OIDC	As its groups allow. Risky actions need a login of at most 15 minutes.
The iPhone app, `public_url`	OIDC	As the browser, with Face ID before anything that changes something.
The app's Terminal and network edits	OIDC and Face ID	`admins` only, after a login of at most 5 minutes. Never from the kiosk or a browser.

Every action (acks, silences, approvals, runbooks, Kubernetes actions, terminal sessions, findings decisions) is logged in the board's database with who made it.

Built-in behaviour

What used to be a setting is fixed now, so there is less to get wrong:

Alertmanager is polled every 5 seconds; the history covers 24 hours.
An ack silences the alert until it resolves, at most 24 hours. Silences go up to 7 days.
Critical alerts are pushed as soon as they fire unacked.
Metrics refresh every 30 seconds, findings every 5 minutes, the calendar every 15, Proxmox and the network scans every 10.
Every connection is checked at start and every 5 minutes (/api/connections).
Terminal sessions close after 15 idle minutes or 2 hours, with at most 2 per user and 6 in all.
Resolved alerts are kept 90 days; a database backup is made every night (Backups).