HaRP operations
HaRP is the service AppAPI drives to deploy and reach External Apps. It is three things in one container: the
HTTP frontend that carries all ExApp traffic, the FRP tunnel server that ExApp containers dial back into, and
the control path AppAPI uses to manage Docker or Kubernetes. Most "my ExApp is broken" reports are really one
of those three planes failing, and each fails with a different signature.
This skill is HaRP itself. Registering daemons, installing ExApps and the occ surface are
exapp-operations.
How to work
- Read references/harp-operations.md: the planes, the probes, the
configuration that matters, log decoding, upgrades, certificates and symptom-first troubleshooting.
- Collect the state before theorising: assets/harp-triage.sh prints container
health, the reported version, ports, the probe results and recent errors, with secrets redacted.
- Fix the daemon registration or the ExApp instead if the fault is on that side:
exapp-operations.
Facts that save hours
- Read the status code first, it names the plane:
401 shared key, 403 route access level, 404 unknown
route or an app not on this daemon, 502 an infrastructure route or a proxy rule pointing nowhere, 503
the agent under load.
GET / on the HTTP frontend answers 404 by design. Never use it as a health probe; use
/exapps/app_api/info with the harp-shared-key header.- One HaRP serves one Nextcloud.
NC_INSTANCE_URL is a single value and every request is authorised against
that instance.
- HaRP must be reachable at
<nextcloud_url>/exapps/: AppAPI talks to ExApps through the public URL, so a
missing reverse-proxy rule blocks installs, not just browsers.
- Regenerating the FRP certificates invalidates every deployed ExApp: they embed them at install time and
must be reinstalled, not restarted.
:release is the newest release, :latest and :main are built from main. Pin :vX.Y.Z if you need a
known version.
Files
- references/harp-operations.md: the runbook.
- assets/harp-triage.sh: read-only diagnostics collector.
- Daemon registration, ExApp lifecycle and the occ surface:
exapp-operations. ExApps on a separate host or in Kubernetes:
remote-daemon.md,
kubernetes.md.
1---2name: harp-operations3description: Runs and debugs HaRP itself, the reverse proxy that serves as AppAPI's deploy daemon: deploying the container, the environment variables worth setting, health probes and what their answers mean, reading HAProxy and agent logs, client IP handling behind another reverse proxy, certificates and the FRP tunnel, upgrades and version floors, and load-related failures. Use when HaRP returns 401, 403, 404, 502 or 503, when ExApps are unreachable although their containers run, or when installing, tuning or upgrading HaRP.4license: AGPL-3.0-or-later5---67# HaRP operations89HaRP is the service AppAPI drives to deploy and reach External Apps. It is three things in one container: the10HTTP frontend that carries all ExApp traffic, the FRP tunnel server that ExApp containers dial back into, and11the control path AppAPI uses to manage Docker or Kubernetes. Most "my ExApp is broken" reports are really one12of those three planes failing, and each fails with a different signature.1314This skill is HaRP itself. Registering daemons, installing ExApps and the occ surface are15[exapp-operations](../exapp-operations/SKILL.md).1617## How to work18191. Read [references/harp-operations.md](references/harp-operations.md): the planes, the probes, the20 configuration that matters, log decoding, upgrades, certificates and symptom-first troubleshooting.212. Collect the state before theorising: [assets/harp-triage.sh](assets/harp-triage.sh) prints container22 health, the reported version, ports, the probe results and recent errors, with secrets redacted.233. Fix the daemon registration or the ExApp instead if the fault is on that side:24 [exapp-operations](../exapp-operations/SKILL.md).2526## Facts that save hours2728- Read the status code first, it names the plane: `401` shared key, `403` route access level, `404` unknown29 route or an app not on this daemon, `502` an infrastructure route or a proxy rule pointing nowhere, `503`30 the agent under load.31- `GET /` on the HTTP frontend answers `404` by design. Never use it as a health probe; use32 `/exapps/app_api/info` with the `harp-shared-key` header.33- One HaRP serves one Nextcloud. `NC_INSTANCE_URL` is a single value and every request is authorised against34 that instance.35- HaRP must be reachable at `<nextcloud_url>/exapps/`: AppAPI talks to ExApps through the public URL, so a36 missing reverse-proxy rule blocks installs, not just browsers.37- Regenerating the FRP certificates invalidates every deployed ExApp: they embed them at install time and38 must be reinstalled, not restarted.39- `:release` is the newest release, `:latest` and `:main` are built from `main`. Pin `:vX.Y.Z` if you need a40 known version.4142## Files4344- [references/harp-operations.md](references/harp-operations.md): the runbook.45- [assets/harp-triage.sh](assets/harp-triage.sh): read-only diagnostics collector.46- Daemon registration, ExApp lifecycle and the occ surface:47 [exapp-operations](../exapp-operations/SKILL.md). ExApps on a separate host or in Kubernetes:48 [remote-daemon.md](../exapp-operations/references/remote-daemon.md),49 [kubernetes.md](../exapp-operations/references/kubernetes.md).
nextcloud