Skip to content

Catalog & integrations

What this is

Top-nav Catalog (/catalog → 303 to Integrations) is the hub for optional products and topology that sit around the fleet — not the fleet itself.

Each section shares:

  • An ops-hero (title + dual-line pulse for the section)
  • A full-width tab bar under the hero: Integrations · Certificates · Templates · Network
Tab Path Purpose Why it is separate
Integrations /integrations (default) Connect Kuma, Grafana, Pi-hole, NPM, generic links, LAN Discovery Vendor adapters + bookmarks + optional nmap
Certificates /certificates TLS vault + service maps + SSH deploy (obtain PEMs with ACME if needed) PEMs are sensitive and multi-consumer
Templates /templates Service template catalog & deploy (OOTB / Yours badges) Stack recipes, not product logins
Network /dns Host DNS, service paths (By path type stats), Hosts/Path maps Topology view of names and edges

Why Catalog exists

Core fleet ops (SSH, backups, patch, Docker) work without any Catalog entry. Catalog is for operators who also run the usual homelab edge stack and want:

  • Status and deep links (Kuma, Grafana)
  • DNS fan-out and maps (Pi-hole + Network)
  • Proxy inventory and cert pull (NPM + Certificates)
  • Repeatable stack deploy (Templates)

PiHerder stays the fleet truth; external tools enrich via adapters and deep links rather than embedding every vendor feature.

Home Assistant

Path 1: managing HAOS (SSH, System info, Core/OS/Supervisor) is day-to-day fleet work — HAOS hosts.
Path 2: HA observes the PiHerder fleet via HACS. Home Assistant → PiHerder. Poll reads snapshots only. Plugin 0.5.4 is one card (Fleet, Host, Updates) with a host strip. Click a stat for Home Assistant history. Containers starts, stops, restarts, or updates one service, and can stop a whole project (docker compose stop). The card can Move and can browse the fleet jail. Poll only. A read token shows sensors only. jobs shows Backup, the Actions menu, those container buttons, stop project, and Move. files shows the jail. edit shows the feature toggles. Visit on the host device is unchanged. The console stays in PiHerder.

Agents (v1.7): Cursor, Grok, Claude, and Codex call the same token API from a process on your computer — Agents (MCP). That program is not a Catalog entry and not part of this image.

End-to-end: first useful Catalog week

  1. Deploy or already run Kuma / Pi-hole / NPM (templates or existing).
  2. Connect each product under Integrations (test / poll).
  3. Bind Kuma monitors → Fleet Services.
  4. Set host FQDNs + Network map LAN settings → Network maps.
  5. Pull, obtain via ACME, or upload certs → map deploy targets → Certificates.

Journey: Operator scenarios — Journey E.

Integrations (products)

Product Role Start here when you…
Uptime Kuma Status, TLS days, deep links, fleet Services Want up/down and TLS in PiHerder
Grafana Dashboard inventory, deep links, preferred names Want one-click metrics from server/Docker
Pi-hole v6 multi-instance stats, local DNS/CNAME fan-out Manage LAN DNS from the herder
LAN Discovery (nmap) Opt-in CIDR scans, devices, map names/kinds, Hosts map overlay, schedules Want an end-to-end LAN view without linking every host
Nginx Proxy Manager Proxy hosts, certificate pull, admin create/edit/delete Inventory edge hosts and cert material
Generic links HA / Frigate / n8n / custom URL + reachability + Services chips Want a deep link without a full adapter
Certificates Encrypted store, PEM upload, deploy maps, NPM renew Push TLS files to many consumers
Network maps Host A + service paths; Hosts/Path maps; runtime stack expand + order Visualise name → host → app → containers

LAN Discovery is opt-in

The default compose stack does not start the nmap worker. Enable profile nmap, build Dockerfile.nmap, and configure CIDRs before scanning. Compose fences web with PIHERDER_NMAP_WORKER=0 (nmap worker =1) — LAN Discovery · env reference.

Credentials and cert PEMs are Fernet-encrypted and included in self-backup.

Design principle

  • PiHerder owns fleet truth
  • External tools enrich via adapters and deep links
  • Prefer n8n + token REST over embedding every vendor API