Harp Nextcloud: Install
Disclaimer: This guide is for educational purposes. Always consult the official Nextcloud documentation for the latest security updates and configuration details.
For Nextcloud administrators, HaRP (High-performance AppAPI Reverse Proxy) is the next-generation solution for managing External Apps (ExApps). Introduced as the recommended deployment daemon for Nextcloud 32 and above, it replaces the legacy Docker Socket Proxy (DSP) by providing a more efficient way to route traffic directly to external containers while enabling advanced features like WebSockets. Core Installation Workflow
Setting up HaRP typically involves two main phases: deploying the container and registering it within Nextcloud's AppAPI. 1. Deploying the HaRP Container
The most common way to install HaRP is via Docker. You must configure several key environment variables to ensure secure communication:
HP_SHARED_KEY: A secure secret used for authentication between Nextcloud and the proxy.
NC_INSTANCE_URL: Your public Nextcloud instance URL (e.g., https://example.com).
HP_TRUSTED_PROXY_IPS: The IP range or CIDR of your network/reverse proxy to allow proper client IP identification.
Ports: You must publish Port 8780 (HTTP communication) and Port 8782 (FRP tunnel port for ExApps). 2. Registering the Daemon in Nextcloud
Once the container is running, you must register it as a Deploy Daemon in the AppAPI admin settings.
Template Selection: Use the HaRP Proxy (Host) template for standard bare-metal or single-host Docker setups, or HaRP All-in-One if using Nextcloud AIO.
HaRP Host: Enter the IP and port (e.g., 192.168.1.10:8780) where the HaRP container is reachable.
FRP Server Address: Point this to the same host on Port 8782.
Verification: Always use the "Test deploy" action from the three-dots menu to verify that the daemon is reachable and functioning correctly. Networking and Proxy Configurations
HaRP sits behind your main reverse proxy. To ensure ExApps are accessible, you must add specific redirection rules to your main proxy (e.g., NGINX or Apache).
Apache Example: Use ProxyPass to redirect /exapps/ traffic to the HaRP container on port 8780.
NGINX Example: Set up a location block for /exapps/ that proxies to the HaRP service, ensuring headers like X-Real-IP and Host are correctly passed. Why Move to HaRP? Docker Deploy Daemon (HaRP) - Nextcloud Documentation
Installing and Configuring HaRP for Nextcloud AppAPI HaRP (High-performance AppAPI Reverse Proxy) is the next-generation deployment daemon for Nextcloud Hub 32+, replacing the older DockerSocketProxy (DSP). It acts as a dedicated bridge and proxy for External Apps (ExApps), enabling them to communicate directly with clients via WebSockets and bypass the standard PHP stack for improved performance. 1. Prerequisites Before beginning the installation, ensure you have:
Nextcloud 32 or higher (HaRP is the recommended standard for these versions). Docker and Docker Compose installed on your host. Administrative access to your Nextcloud instance. The AppAPI app installed from the Nextcloud App Store. 2. Deploying the HaRP Container
HaRP is typically deployed as a standalone Docker container. Use the following docker-compose.yml snippet to launch it:
services: appapi-harp: image: ghcr.io/nextcloud/nextcloud-appapi-harp:release container_name: appapi-harp restart: always environment: - HP_SHARED_KEY=your_very_secure_password # Minimum 12 characters - NC_INSTANCE_URL=https://your-nextcloud-domain.com volumes: - /var/run/docker.sock:/var/run/docker.sock:ro # Access to Docker engine - ./harp_certs:/certs # Persistent storage for FRP certificates networks: - nextcloud_network networks: nextcloud_network: external: true Use code with caution. harp nextcloud install
HP_SHARED_KEY: A secret key used to authenticate communication between Nextcloud and HaRP.
NC_INSTANCE_URL: The full URL of your Nextcloud installation.
Persistent Volume: Mounting /certs is critical. If these certificates are lost, existing ExApp tunnels will fail due to TLS mismatches. 3. Registering the HaRP Daemon in Nextcloud
Once the container is running, you must link it to Nextcloud through the web interface: Installing Harp for ExApps: Can't Connect from Nextcloud
The Basics. Nextcloud Server version (e.g., 29. x.x): 31.0. 4. Operating system and version (e.g., Ubuntu 24.04): Ubuntu 24.04. 2. Nextcloud community
nextcloud/HaRP: Fast Proxy for AppAPI(Nextcloud 32+) - GitHub
HaRP (High Performance Reverse Proxy) is a specialized system introduced for Nextcloud 32+ to manage and scale External Apps (ExApps) through the
. It acts as a fast proxy that allows ExApps to communicate directly with clients, bypassing the core Nextcloud instance to reduce overhead and latency. Installation Overview HaRP is primarily designed for Docker-based deployments and is not currently supported for bare-metal installs. Nextcloud community Setup Method
: You typically run HaRP as a separate Docker container alongside your Nextcloud instance or on a dedicated host. Key Configuration Environment Variables : You must set HP_SHARED_KEY (a secret for authentication) and NC_INSTANCE_URL (the address of your Nextcloud server). : It often requires a Docker Socket Proxy
or direct access to the Docker socket to orchestrate ExApp containers. External Access
: If using a reverse proxy (like NGINX or HAproxy), you must forward traffic for specifically to the HaRP container. The "Long Review": Critical Insights Based on community feedback and Nextcloud documentation , here is a breakdown of the current state of HaRP: Pros: Performance & Scalability
AIO and HARP for ExApp running remotely - the Nextcloud forums 2 Mar 2026 —
Nextcloud HaRP: High-Performance AppAPI Reverse Proxy (High-performance AppAPI Reverse Proxy) is the modern deployment daemon for Nextcloud 32+ , designed specifically for managing External Apps (ExApps)
. It replaces the legacy Docker Socket Proxy (DSP) and is intended to simplify networking and boost performance by allowing clients to communicate directly with ExApps, bypassing the standard Nextcloud PHP process. Key Benefits of HaRP Performance
: Routes requests directly to ExApps, reducing latency and resource consumption. WebSocket Support
: Enables real-time features like chat or live notifications, which were difficult to implement under older systems. FRP Tunneling
: Uses Fast Reverse Proxy (FRP) to create secure tunnels, meaning ExApp containers do
need to expose ports or have open firewall rules to be reachable by Nextcloud. Multi-Docker Support
: A single HaRP instance can manage multiple Docker engines across different hosts. Step-by-Step Installation & Configuration Disclaimer: This guide is for educational purposes
Installing HaRP involves setting up a Docker container and then registering it within your Nextcloud instance. 1. Deploy the HaRP Docker Container
You must run the HaRP container on the same host as your Docker engine. Ensure you set a secure shared key.
docker run -d \ --name appapi-harp \ --network nextcloud_network \ -e HP_SHARED_KEY= "your_secure_password" \ -e NC_INSTANCE_URL= "https://yourdomain.com" \ ghcr.io/nextcloud/appapi-harp:latest Use code with caution. Copied to clipboard HP_SHARED_KEY : Used for authentication between Nextcloud and HaRP. NC_INSTANCE_URL : Your public Nextcloud URL. 2. Register the Daemon in Nextcloud Log in to your Nextcloud instance as an Navigate to Administration Settings Register Daemon Select a template based on your environment: HaRP Proxy (Host) : For most standard setups. HaRP Proxy (Docker) : If Nextcloud and HaRP share a custom Docker network. HaRP All-in-One : Specifically for Nextcloud AIO installations. appapi-harp:8780 Shared Key you created in Step 1. Check connection 3. Update Your Main Reverse Proxy
To enable direct communication, you must add a redirect in your main reverse proxy (e.g., NGINX or Apache) to point traffic to the HaRP container. Example Apache Configuration:
ProxyPass /exapps/ http://
Nextcloud plans to remove DSP support in version 35, making migration essential for long-term stability. Install HaRP on the Docker engine currently running DSP. Set HaRP as Default in the AppAPI settings. Reinstall ExApps : Remove existing ExApps (choose
to delete data volumes) and reinstall them. They will automatically deploy via HaRP. Remove DSP once all apps are successfully migrated. Docker Compose example for a production-ready HaRP and Nextcloud setup? Docker Deploy Daemon (HaRP) - Nextcloud Documentation
To create a feature for installing Nextcloud on a Harp server, we'll outline a step-by-step guide on how to achieve this. This guide assumes you have basic knowledge of using the command line and have Harp and a suitable database (like MySQL or MariaDB) installed and running.
Would you like a minimal proof-of-concept implementation plan for this using Harp + Nextcloud’s WebDAV or OCS API?
(High-performance AppAPI Reverse Proxy) is the modern, recommended deployment daemon for Nextcloud 32+
, designed to bridge the gap between your core Nextcloud instance and External Apps (ExApps)
. While traditional Nextcloud setups rely on a local PHP stack, HaRP uses FRP (Fast Reverse Proxy)
tunnels to allow ExApps—which can be written in any language—to communicate securely without exposing ports or requiring complex network rules. Core Architecture
HaRP functions as a specialized reverse proxy that sits behind your primary web server (like Nginx or Caddy). Its primary roles include: Direct Routing
: It routes traffic directly from the client to ExApps, bypassing the heavy Nextcloud PHP process to improve performance. WebSocket Support
: Unlike older methods, HaRP enables full end-to-end WebSocket support for real-time features in external apps.
: It uses FRP to create outbound connections from ExApps back to the daemon, solving issues with NAT traversal and internal firewall restrictions. Installation & Deployment Steps For a standard Docker-based setup , follow these streamlined steps: Deploy the HaRP Container
: Run the daemon where your main reverse proxy can reach it. docker run -d \ --name appapi-harp \ -e HP_SHARED_KEY= "your_secure_key" \ -e NC_INSTANCE_URL= "https://yourcloud.com" \ -v /var/run/docker.sock:/var/run/docker.sock \ -p \ ghcr.io/nextcloud/nextcloud-appapi-harp:release Use code with caution. Copied to clipboard Register the Daemon Navigate to your Nextcloud Admin Settings Register Daemon and select the HaRP Proxy (Host) HP_SHARED_KEY used in your Docker command to establish the link. Configure Main Reverse Proxy : Update your primary proxy (e.g., Nginx) to redirect requests to the HaRP container on port Best Practices for Stability Version Compatibility : Ensure you are running Nextcloud 32 or higher for full support, as older methods are being deprecated. Network Security
: Launch the HaRP container within the same Docker network as your Nextcloud instance to limit external exposure. Internal Heartbeats recommended deployment daemon for Nextcloud 32+
: If deploying in complex environments like Kubernetes, ensure internal routing is configured so the Nextcloud server can reach the /heartbeat endpoint through the proxy without throwing 404 errors. Docker Compose file to integrate HaRP with your existing Nextcloud setup? AppAPI and External Apps - Nextcloud Documentation
Setting Up HaRP for Nextcloud 32+ HaRP (High-performance AppAPI Reverse Proxy) is the new recommended bridge for running External Apps (ExApps) in Nextcloud 32 and beyond. It replaces the older DockerSocketProxy, offering better performance and native support for features like WebSockets. Why Use HaRP?
Direct Routing: Requests bypass the Nextcloud PHP stack, significantly reducing resource usage.
WebSocket Support: Essential for real-time AI assistants and interactive external apps.
Simplified Networking: Uses FRP (Fast Reverse Proxy) tunnels, so your ExApp containers don't need to expose ports to the host or be on the same network as Nextcloud. Step-by-Step Installation 1. Deploy the HaRP Container
The easiest way to start is using the official nextcloud/HaRP GitHub image. You'll need to define a shared key for secure communication. Example Docker Run Command:
docker run -d \ --name appapi-harp \ -e HP_SHARED_KEY="your_secure_password" \ -e NC_INSTANCE_URL="https://yourdomain.com" \ -p 8780:8780 -p 8782:8782 \ ghcr.io/nextcloud/nextcloud-appapi-harp:release Use code with caution. Copied to clipboard Port 8780: Handles HTTP/WebSocket traffic. Port 8782: The FRP server for ExApp tunnels. 2. Register the Daemon in Nextcloud Log in to your Nextcloud instance as an admin. Navigate to Administration settings > AppAPI. Click Register Daemon.
Choose the HaRP Proxy (Host) or HaRP Proxy (Docker) template. Fill in the details: HaRP host: HP_SHARED_KEY from Step 1. Click Check connection and then Register. 3. Update Your Reverse Proxy (Important)
To ensure everything works correctly, especially for external access, you must route requests for /exapps/ directly to the HaRP container. Apache Example Snippet:
Note: Ensure proxy, proxy_http, and headers modules are enabled. Troubleshooting Common Issues
Connection Failed: Double-check that your HP_SHARED_KEY matches exactly in both the Docker environment and the Nextcloud UI.
Docker Version: Some users have reported issues with older Docker versions; ensure you are running a recent version (v29+ is recommended) to avoid API client mismatches.
Certificate Persistence: If running in a Kubernetes or ephemeral environment, ensure the /certs directory is mounted to a persistent volume, or HaRP will regenerate CA certs on restart, orphaning existing ExApps.
For deeper configuration details, check out the official Docker Deploy Daemon (HaRP) Documentation. Docker Deploy Daemon (HaRP) - Nextcloud Documentation
objectStore: enabled: true type: s3 s3: bucket: nextcloud-data region: us-east-1 endpoint: https://minio.example.com accessKey: "minioadmin" secretKey: "minioadmin123"
mariadb: enabled: true auth: existingSecret: mariadb-secret database: nextcloud username: nextcloud primary: persistence: enabled: true size: 20Gi
ingress: enabled: true ingressClassName: traefik hostname: nextcloud.example.com tls: true annotations: cert-manager.io/cluster-issuer: letsencrypt-prod