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 OS as a fleet host

Managing HAOS (SSH, System info, Core/OS/Supervisor updates) is day-to-day fleet work, not a Catalog adapter — HAOS hosts. HA can still call PiHerder with API tokens.

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 (read-only) + certificate pull 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