Install !!better!! | Harp Nextcloud

Unlocking High-Performance Microservices: A Guide to Nextcloud HaRP

Nextcloud has evolved from a simple file-sharing tool into a comprehensive productivity suite. With the release of Nextcloud 32, a new architectural component called HaRP (High-performance AppAPI Reverse Proxy)

has become the recommended way to manage "ExApps"—external applications that run as microservices outside the main PHP stack.

This guide explores what HaRP is, why it’s essential for modern Nextcloud deployments, and how to install it. What is HaRP? Historically, Nextcloud used a Docker Socket Proxy (DSP)

to manage external apps. However, DSP had limitations, particularly with real-time features like WebSockets.

replaces the old system by acting as a fast reverse proxy that: Enables WebSockets : Allows real-time communication for apps like Nextcloud Talk without passing through the heavy PHP stack. Simplifies Networking

: ExApps no longer need to expose ports to the host; they connect outbound to HaRP using an internal FRP (Fast Reverse Proxy) client. Improves Performance

: Reduces resource overhead by routing traffic directly to the containerized microservices. Prerequisites Before you begin, ensure you have: Nextcloud 32 or higher installed. Docker and Docker Compose set up on your server. app enabled within your Nextcloud instance. Step 1: Deploy the HaRP Container

HaRP is distributed as a Docker image. You can deploy it using a simple docker run command or a Compose file. Essential Environment Variables: HP_SHARED_KEY : A secure password shared between Nextcloud and HaRP. NC_INSTANCE_URL : The URL of your Nextcloud instance (e.g.,

The introduction of (High-availability Reverse Proxy) marks a paradigm shift in how Nextcloud handles external applications (ExApps). As Nextcloud evolves into a "Hub" rather than just a file-sync service, the need for a robust, decoupled execution environment for resource-heavy apps—like those requiring GPUs or high-performance compute—has become critical. 🏛️ The Architecture of HaRP

HaRP serves as the bridge between the Nextcloud AppAPI and Docker-based ExApps. It replaces the older Docker Socket Proxy (DSP) to provide a more secure and flexible communication layer. : HaRP leverages Fast Reverse Proxy (FRP)

to create secure tunnels between the Nextcloud server and the Docker engine where ExApps reside. Decoupling

: Unlike traditional apps that run within the PHP process, HaRP allows apps to run in separate containers, potentially on different physical hardware. harp nextcloud install

: By moving away from direct Docker socket access, HaRP minimizes the risk of container escape or unauthorized host access. 🛠️ Installation and Configuration

Installing HaRP is primarily a Docker-based workflow. It is designed to work either on the same host as Nextcloud or a remote machine for distributed setups. 1. Deploying the HaRP Container The standard method involves pulling the nextcloud-appapi-harp Environment Setup

: You must define a shared key and set up the FRP server/client within the container. AIO Integration Nextcloud AIO

users, HaRP can be toggled as an additional container to simplify the networking stack. 2. Registering the Daemon

Once the container is live, you must register it as a "Deploy Daemon" via the Nextcloud occ app_api:daemon:register harp_proxy_docker "Harp Proxy" "docker-install" "appapi-harp:8780" --harp --harp_frp_address "appapi-harp:8782" --harp_shared_key "your_secure_password" Use code with caution. Copied to clipboard : Used for the HTTP proxy. : Used for the FRP server communication. 🚀 Advanced Use Cases: Remote ExApps

One of HaRP's greatest strengths is enabling "Manual Install" deploy daemons. This allows a user to run an ExApp on a secondary server—for instance, one with a powerful NVIDIA GPU

for AI-driven OCR or Face Recognition—while keeping the main Nextcloud instance on lightweight hardware. Nextcloud community GPU Offloading : Register the daemon with --compute_device=cuda

to let Nextcloud know the remote host can handle heavy AI workloads. Cross-Network Support

: Because it uses FRP tunnels, the remote app does not need a public IP; it only needs to reach the HaRP container. ⚠️ Common Troubleshooting

Transitioning to HaRP is not without hurdles. Common issues found in community forums Heartbeat Errors : Often caused by misconfigured files, resulting in a 404 during the "Test Deploy" phase. Certificate Issues

: If HTTPS frontends are disabled in the HaRP container, the may fail to establish a handshake. Docker Network Isolation

: The HaRP container and the ExApp containers must share a network or have correctly mapped bridge ports to communicate. 📈 Future Outlook Step 3: Search for Harp In the left

With Nextcloud 32 and beyond, HaRP is becoming the standard. The Nextcloud GitHub

suggests that manual Docker Socket Proxying will eventually be deprecated in favor of this tunnel-based approach. This shift ensures that the Nextcloud ecosystem remains scalable and "cloud-native," allowing developers to build apps in any language that can be containerized, rather than being restricted to PHP. docker-compose.yml example for a HaRP setup, or should we troubleshoot a specific error message you've encountered? Adapting ExApps to HaRP - Nextcloud Documentation

In the quiet hum of a basement server room, sat bathed in the blue glow of his monitor. He wasn’t just building a cloud; he was building a "Harp"—a high-availability, resilient platform designed to keep his family’s memories safe from the whims of corporate giants.

He began the Nextcloud installation, choosing the All-in-One Docker route to ensure every piece of the puzzle—from the database to the office suite—fit together perfectly. Command by command, he laid the foundation. When the first login screen finally appeared, it felt like striking a clear, resonant chord on a well-tuned instrument.

Elias spent the night fine-tuning his "Harp." He added Nextcloud Office so his kids could finish homework without tracking, and Memories to organize decades of photos. By dawn, the server wasn't just a machine anymore; it was a private sanctuary, humming a steady, secure tune of digital independence.

Setting Up Nextcloud HaRP for External Apps HaRP (Homeland App Runtime Platform) is the high-performance proxy bridge introduced in Nextcloud 32+ to facilitate External Apps (ExApps) like AI assistants and advanced office integrations. It replaces the older Docker Socket Proxy (DSP) by providing dedicated support for WebSockets and direct routing, which improves performance by bypassing the PHP stack. 1. Deploy the HaRP Container

The HaRP container acts as the intermediary between your Nextcloud instance and the external app containers.

Docker Pull: Ensure you have the latest image from the Nextcloud HaRP GitHub.

Networking: Launch the HaRP container on the same Docker network as your Nextcloud instance to ensure they can communicate.

Shared Key: Set a secure HP_SHARED_KEY environment variable in your Docker compose or run command. This key must match what you later enter in the Nextcloud UI. Example Command:

docker run -d --name nextcloud-appapi-harp \ --network nextcloud-net \ -e HP_SHARED_KEY="your_secure_key" \ -p 8780:8780 -p 8782:8782 \ nextcloud/nextcloud-appapi-harp:latest Use code with caution. Copied to clipboard 2. Configure Your Reverse Proxy

Because HaRP handles specific traffic for ExApps (often at /exapps/), you must update your main reverse proxy (e.g., Nginx Proxy Manager, Caddy) to redirect these requests. DSP had limitations

Endpoint: Requests to https://your-domain.com should be forwarded to the HaRP container's internal IP at port 8780.

WebSocket Support: Ensure your proxy configuration allows WebSocket upgrades for this path to enable real-time features. 3. Register the Daemon in Nextcloud

Once the container is running, you must link it to your Nextcloud instance via the AppAPI settings. Navigate to Administration settings > AppAPI. Click Register Daemon. Choose the appropriate preset:

HaRP Proxy (Host): For standard setups where ports are exposed to the host.

HaRP Proxy (Docker): If using a custom Docker network without exposed ports. HaRP All-in-One: Specifically for Nextcloud AIO users. Enter the Shared Key you defined in Step 1. Click Check connection and then Register. 4. Transitioning from DSP (Optional)

If you are upgrading an existing installation that uses the old Docker Socket Proxy: Install HaRP on the same engine.

Set HaRP as the default deployment daemon in the AppAPI settings.

Remove your existing ExApps (do not delete their data volumes) and reinstall them; they will now deploy via HaRP. Safely remove the old DSP container. Troubleshooting Common Issues AppAPI and External Apps - Nextcloud Documentation

Step 3: Search for Harp

In the left sidebar, you can either browse the "Multimedia" category or simply use the search bar. Type "Harp".

You will see an entry with a harp icon (a golden stringed instrument). Click the "Download and enable" button.

Problem 3: "Internal Server Error" on Scan

Solution: This is almost always a memory limit issue. Increase the PHP memory limit from 128M to 512M as shown above. Also, check Nextcloud’s data/nextcloud.log for the exact error.

Step 1: Download Harp from GitHub

SSH into your Nextcloud server:

cd /var/www/nextcloud/custom_apps
sudo git clone https://github.com/gabrielbruin/harp.git

Note: Your Nextcloud path might be /var/www/html/nextcloud or /apps/www/nextcloud. Adjust accordingly.