Skip to content

Getting started

This section takes you from zero to a running PiHerder with a first admin account and a clear idea of what to do next.

Prefer a click-through first?

The public demo is a limited view-only sandbox (piherder-demo.hacknow.info) with a shared viewer login. Credentials and limits are on that page — password may rotate; the live wiki always has the current one.

What you are setting up

Piece Role
PiHerder stack Web UI + API, Postgres, Redis, Celery workers, Caddy TLS — on one Linux host
Fleet hosts Pis / Linux boxes you manage later over SSH
You (first admin) First registered account owns the instance; then you invite others

You do not need Catalog integrations, templates, or Web Push on day one. Those are optional after the fleet basics work.

Step Doc Why this step exists
1 Requirements Avoid install surprises (disk, ports, remote tools)
2 Install (Docker Compose) Supported way to run the stack and secrets
3 First login Create the only self-serve admin; lock registration
4 Trusted HTTPS & TLS Needed for reliable mobile PWA / Web Push
5 Appearance Light/dark, and (on this train) an instance name, one accent, and Catalog in the nav
6 Operator scenarios Map goals → docs for everything after install

Then: Add a server (guided wizard) → Dashboard → Reports once Jobs exist. Bootstrap missing tools is on that wizard and on SSH access. It installs rsync only when Backups are on, and Docker CE only when Docker is on.
HAOS appliance: HAOS hosts. Optional Host Files (PIHERDER_HOST_FILES). Templates / from-host: Service templates.

Supported install path

Docker Compose only

The supported topology is the compose stack in this repository (web, db, redis, celery-worker, caddy).

Kubernetes and bare-metal installs are under consideration only — not documented as supported paths.

Time estimate

Step Typical
Clone + generate secrets 5 min
First compose up --build 5–15 min (image build)
Register + open UI 2 min
Trusted certs (if not ready) depends on your CA / ACME
First server + key deploy 10–20 min

First successful week (end-to-end sketch)

A realistic production onboarding path:

  1. Install + first admin — this section.
  2. Add one non-critical Pi — Add a server wizard (Identity → Trust → Connect: install key → test → clear password → Features).
  3. Run one manual backup — Backups (confirm Celery + rsync path before schedules).
  4. Run one OS update check — Updates (check before any apply schedule; HAOS uses ha CLI).
  5. Open Jobs + Audit — Jobs, audit & notifications so you trust the trail.
  6. Optional: Kuma / templates / network / HAOS — only after the host path feels solid.

Detailed “I want to…” tables and longer journeys: Operator scenarios.

Doc Role
README Project overview
.env.example Full env catalog
docs/ADMIN.md Long-form admin reference (mirrored into this wiki)
v1.2.0 QA Freeze sign-off checklist (before Hub 1.2.0)