Nextcloud LLM lokal betreiben: Nextcloud KI mit HaRP (AppAPI) auf einem System

Wer Nextcloud produktiv betreibt, will bei „KI-Funktionen“ oft zwei Dinge gleichzeitig: einen echten Mehrwert für Anwender und möglichst wenig Abhängigkeit von externen Cloud-Diensten. Genau an der Stelle wird es interessant, wenn Sie Nextcloud KI mit einem lokal installierten LLM kombinieren – also ein Nextcloud LLM-Setup, bei dem das Modell (oder zumindest der Inference-Server) in Ihrem eigenen Netz läuft.

Technisch hängt das in aktuellen Nextcloud-Versionen stark an AppAPI und den sogenannten ExApps. Nextcloud empfiehlt dafür inzwischen HaRP als Proxy- und Transport-Schicht, weil sich damit ExApps typischerweise sauberer betreiben lassen als mit klassischen Docker-Socket-Proxy-Konstrukten. In diesem Beitrag zeige ich eine praxisnahe Lösung:

HaRP + ExApps (llm2) direkt auf dem Nextcloud-Host (ein System)

Dazu bekommen Sie konkrete Compose-Beispiele, Hinweise für Reverse Proxies und eine Checkliste, wie Sie die üblichen Stolpersteine (Ports, Trusted Proxies, Shared Key) schnell eingrenzen.

Was HaRP in der AppAPI-Kette tatsächlich macht

HaRP ist ein „Fast Proxy“ für AppAPI und ExApps. Er stellt zwei zentrale Funktionen bereit:

HTTP-Frontend für ExApps unter /exapps/ (Standard-Port 8780) – Ihr Reverse Proxy leitet diese Route an HaRP weiter. In der HaRP-Doku ist das als HP_EXAPPS_ADDRESS beschrieben; Default ist 0.0.0.0:8780.
FRP-basierter Transport (Default-Port 8782) für die Verbindung zu ExApp-Containern. Das ist HP_FRP_ADDRESS mit Default 0.0.0.0:8782.

Der Knackpunkt: Bei HaRP müssen ExApps häufig keine Ports nach außen öffnen. Der ExApp-Container baut eine ausgehende FRP-Client-Verbindung zum HaRP-Server auf, und HaRP proxyt dann die Requests vom Client zur ExApp. Genau dieses Modell beschreibt Nextcloud auch im Developer Manual.

Wenn Sie in diesem Kontext über „Nextcloud KI“ mit lokalem LLM sprechen, ist das Setup meist so: Nextcloud/ AppAPI steuert Deployment und Routing, und Ihr LLM-Server (oder eine ExApp, die mit dem LLM spricht) läuft in Ihrer Infrastruktur.

Voraussetzungen

Für HaRP

Docker Engine + Docker Compose auf dem Host
Nextcloud mit AppAPI / ExApps
Reverse Proxy, der /exapps auf HaRP weiterleitet (NGINX / Caddy / Traefik) – HaRP liefert Beispiele

Für die LLM2 App

NVIDIA GPU oder x86_64 CPU
NVIDIA GPU mit mindestens 8GB VRAM
CPU mindestens 10 Kerne & 12GB RAM

HaRP direkt auf dem Nextcloud-Host

Diese Lösung ist für viele „Start“-Szenarien gut: ein Host, weniger Netzwerkvariablen, weniger Moving Parts. Der Preis: Ihre ExApps teilen sich Ressourcen mit Nextcloud.

Docker Compose für HaRP (Host-Netzwerk)

Die HaRP-Doku zeigt sowohl Port-Publishing als auch Host-Networking. Host-Networking ist oft angenehm, weil Sie dann nicht zwischen Container-IPs und Host-Ports „übersetzen“ müssen.

Beispiel:

services:
  appapi-harp:
    image: ghcr.io/nextcloud/nextcloud-appapi-harp:latest
    container_name: appapi-harp
    hostname: appapi-harp
    restart: unless-stopped
    environment:
      # Muss identisch in Nextcloud AppAPI- /Daemon-Registrierung sein
      HP_SHARED_KEY: "SECRET_KEY_EINFÜGEN"

      # Basis-URL Ihrer Nextcloud, erreichbar aus dem HaRP-Container
      NC_INSTANCE_URL: "https://cloud.example.com"

      # Logging
      HP_LOG_LEVEL: "debug"
      HP_VERBOSE_START: "1"

      # FRP-Frontend (Default laut Doku 0.0.0.0:8782)
      HP_FRP_ADDRESS: "0.0.0.0:8782"

      # Wichtig bei hinter einem Reverse Proxy
      HP_TRUSTED_PROXY_IPS: "127.0.0.1,::1"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./certs:/certs
    network_mode: host

Hinweise:

Das Image-Tag :latest wird empfohlen
HP_TRUSTED_PROXY_IPS: auf Proxy-Server IPs anpassen
HP_SHARED_KEY: in Nextcloud gleichsetzen

Starten Sie:

docker compose up -d

Reverse Proxy: `/exapps` auf HaRP

Diese Route leitet den Zugriff auf HaRP. Beispiel für NGINX:

location /exapps/ {
    proxy_pass http://localhost:8780/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

In Apache analog:

ProxyPass /exapps/ http://127.0.0.1:8780/
ProxyPassReverse /exapps/ http://127.0.0.1:8780/

Daemon-Registrierung in Nextcloud

Nutzen Sie die UI oder occ app_api:daemon:register, um HaRP in Nextcloud zu integrieren.

Nachinstallation der App llm2

Nach Einrichtung von HaRP und AppAPI können Sie die App ‚llm2‘ installieren:

sudo -u www-data php /var/www/nextcloud/occ app_api:app:register llm2

Damit wird die App gespeichert und steht für die Nutzung bereit.

Wo bringt das lokale LLM jetzt Mehrwert?

Mit HaRP und AppAPI steuern Sie die Anbindung an Ihren lokalen Inference-Server. Ihre ExApp kann z. B. ein Modell wie Llama oder GPT-4-Like per API ansprechen. Das Ergebnis: eine Nextcloud mit integrierter KI, die in Ihrem eigenen Netz arbeitet, wodurch ihre Daten das System nicht verlassen.

Vorteile:

Datenschutz (keine Cloud-Externe Ablage)
Kontrolle über Hardware (GPU, RAM)
Flexibilität bei Modellen und Anwendungen

Deployment-Checkliste für die Inbetriebnahme

/exapps im Reverse Proxy erreichbar?
HaRP läuft stabil (Container-Logs tailen)
Shared Key in Konfiguration und Nextcloud exakt
Proxy-Konfiguration ohne Breaks (Timeout, Header)
Trust- und Security-Settings geprüft

Wenn Sie bei der Umsetzung dieses Projekts oder der Einrichtung des LLMs auf einem separaten Server Unterstützung brauchen, stehen wir gern beratend zur Seite: ADMIN INTELLIGENCE. Wir helfen bei Architektur, Security und Troubleshooting für Ihre Nextcloud & LLM-Systeme.

Der Blog enthält viele weitere interessante Beiträge rund ums Thema Nextcloud. Lesen Sie hier weiter!

Tim Perelli

IT-Fachinformatiker bei ADMIN INTELLIGENCE GmbH