nextcloud-appapi

Metadata

Field	Value
Service	nextcloud-appapi
Purpose	Kubernetes-native Nextcloud AppAPI deploy daemon and isolated ExApp runtime
Criticality	Tier 3
Owner	Application / platform owner
Clusters	local
Namespace	nextcloud-exapps
Exposure	existing cloud.mutana.fr/exapps/ path plus private ClusterIPs
Stateful	HaRP: no; AppAPI-created ExApps: yes
Backup class	ExApp-specific PVC snapshot plus Nextcloud application backup
RPO / RTO	Best effort for HaRP; inherit application policy for ExApp state
Last reviewed	2026-08-17

1. Service Overview

nextcloud-appapi runs the official HaRP proxy and deployment agent used by Nextcloud AppAPI. AppAPI calls HaRP through a private ClusterIP Service; HaRP uses a namespace-scoped Kubernetes identity to create and operate External App (ExApp) Deployments, ClusterIP Services, and PVCs in nextcloud-exapps.

Context Agent is installed through Nextcloud AppAPI rather than rendered in Git. AppAPI pins the selected app release and HaRP materializes its runtime resources. The initial supported release is Context Agent 2.8.0 for Nextcloud 34.

Summary

If HaRP fails, installed ExApps may be unreachable through AppAPI and lifecycle operations stop. Core Nextcloud files, Tasks, Notes, and Collectives remain independent of this component.

Dependencies

Dependency	Type	Why it matters
Nextcloud 34 and AppAPI 34	application	Owns ExApp registration, routing metadata, and lifecycle calls
nextcloud-appapi-harp Secret	credential	Authenticates AppAPI control requests to HaRP
Kubernetes API	platform	HaRP creates and observes ExApp resources in one namespace
local-path StorageClass	storage	Supplies the default 10Gi PVC requested for each ExApp
cloud.mutana.fr	application URL	HaRP and ExApps use the canonical Nextcloud instance URL

2. Architecture Diagram

[User / life-agent]
  -> [https://cloud.mutana.fr]
  -> [Nextcloud + AppAPI, namespace nextcloud]
  -> [HaRP ClusterIP :8780, namespace nextcloud-exapps]
  -> [Context Agent ClusterIP]
  -> [Context Agent pod + 10Gi local-path PVC]

[AppAPI lifecycle heartbeat]
  -> [cloud.mutana.fr/exapps/context_agent/*]
  -> [narrow Traefik route to HaRP]

[HaRP ServiceAccount]
  -> [namespace Role]
  -> [Deployments, Services, PVCs, Pod readiness in nextcloud-exapps only]

3. Deployment Specifications

Item	Value
Source path	nextcloud-appapi/base and nextcloud-appapi/overlays/local
Deployment model	Plain Kustomize plus Fleet bundle
Namespace	nextcloud-exapps
Workload kind	HaRP Deployment and ClusterIP Service; ExApps are AppAPI-generated
HaRP image	ghcr.io/nextcloud/nextcloud-appapi-harp@sha256:3b335650...2f310
Context Agent release	2.8.0 (ghcr.io/nextcloud/context_agent:2.8.0)
HaRP resources	requests 100m CPU / 128Mi; limits 500m CPU / 512Mi
ExApp storage default	10Gi, local-path, ReadWriteOnce
Fleet target	local, overlay overlays/local

RBAC boundary

HaRP has one Role and RoleBinding in nextcloud-exapps. It can:

• get, list, create, patch, and delete Deployments;
• get, list, create, and delete Services;
• create and delete PVCs;
• list Pods to wait for ExApp readiness.

It cannot read Secrets, ConfigMaps, logs, nodes, or resources in another namespace. ClusterIP mode deliberately avoids the node-list permission required by NodePort mode. AppAPI-created pods receive no ServiceAccount token because token automount is disabled on the namespace's default ServiceAccount.

The container has a read-only root filesystem, RuntimeDefault seccomp, and privilege escalation disabled. It drops all Linux capabilities except DAC_OVERRIDE: the pinned upstream image ships /etc/haproxy without directory execute bits, and HAProxy cannot read spoe-agent.conf without that capability.

4. Configuration Guide

Environment variables

Variable	Source	Purpose	Secret?
HP_SHARED_KEY	nextcloud-appapi-harp Secret	AppAPI-to-HaRP authentication	yes
NC_INSTANCE_URL	local overlay	Canonical Nextcloud URL	no
HP_K8S_ENABLED	base Deployment	Enables HaRP Kubernetes backend	no
HP_K8S_NAMESPACE	base Deployment	Restricts managed ExApps to nextcloud-exapps	no
HP_K8S_STORAGE_CLASS	local overlay	Selects local-path for generated PVCs	no
HP_K8S_DEFAULT_STORAGE_SIZE	local overlay	Requests 10Gi per generated ExApp PVC	no
HP_FRP_DISABLE_TLS	base Deployment	Avoids unused FRP certificate generation in ClusterIP mode	no

HaRP discovers the in-cluster API server and reads its rotating projected ServiceAccount token and CA. No static Kubernetes bearer token is configured.

Secrets management

• Secret name: nextcloud-appapi-harp in nextcloud-exapps.
• Required key: HP_SHARED_KEY.
• Git contract: referenced by name only; Fleet does not create or manage it.
• Credential reference: Vaultwarden -> Nextcloud -> AppAPI HaRP shared key.
• Rotation: replace the Secret and re-register the AppAPI daemon as one planned operation; mismatched values make lifecycle requests fail.

5. Access Protocols

Path	URL or endpoint	Audience	Auth	TLS terminates at
AppAPI control	http://nextcloud-appapi-harp.nextcloud-exapps.svc:8780	Nextcloud AppAPI	HaRP shared key	N/A, private ClusterIP
AppAPI lifecycle and routed ExApp calls	https://cloud.mutana.fr/exapps/<app-id>/...	AppAPI and authenticated Nextcloud clients	HaRP/AppAPI headers or Nextcloud session	Traefik
HaRP to Context Agent	generated ClusterIP in nextcloud-exapps	HaRP proxy	AppAPI ExApp token	N/A, private ClusterIP
Context Agent MCP	https://cloud.mutana.fr/index.php/apps/app_api/proxy/context_agent/mcp/	authenticated Nextcloud users	Nextcloud app password bearer token	Traefik

No HaRP or ExApp Service has a NodePort or LoadBalancer. The single IngressRoute adds only the upstream-required /exapps/ path on the existing Nextcloud host; HaRP enforces the ExApp route and authentication metadata.

6. Operations and Observability

• HaRP health: /healthcheck.sh validates HAProxy configuration, the internal agent heartbeat, SPOA, FRP, and the ExApp HTTP frontend.
• Primary resources: kubectl -n nextcloud-exapps get deploy,pod,svc,pvc.
• HaRP logs: kubectl -n nextcloud-exapps logs deploy/nextcloud-appapi-harp.
• AppAPI state: occ app_api:daemon:list and occ app_api:app:list from the Nextcloud pod.
• Expected replicas: one HaRP pod and one Context Agent pod.
• Known failure modes: missing/mismatched shared key, denied Role verb, failed ExApp image pull, unbound local-path PVC, removed DAC_OVERRIDE, or public Nextcloud URL failure.

7. Backup and Recovery Notes

HaRP is stateless and is recovered by reapplying Kustomize plus restoring the shared-key Secret and matching AppAPI daemon registration. Do not delete AppAPI-created PVCs during routine HaRP recovery. ExApp PVC snapshot and restore requirements are app-specific; Nextcloud application state and database remain covered by the Nextcloud backup policy.

Related runbook: ../runbooks/nextcloud-appapi.md

8. Release and Change Notes

• Initial deployment: 2026-08-17.
• HaRP image is pinned by OCI index digest and supports amd64 and arm64.
• Context Agent is installed at the explicit App Store release supported by Nextcloud 34; AppAPI owns its generated Kubernetes resources.
• Rollback: disable/remove Context Agent through AppAPI, unregister the daemon, and revert the nextcloud-appapi Fleet unit while preserving the Secret and dynamically-created PVC until data retention is decided.