Update Nextcloud 31 zu 32

Update Nextcloud 31 zu 32, inklusive AppAPI Einrichtung.

Posted Mar 4, 2026 Updated Mar 5, 2026

By Mattek

views 6 min read

Ausgangslage

Nextcloud ist mein zentraler Speicher für Fotos und Office Dokumente. Ein stabiler und sicherer Betrieb ist mir daher sehr wichtig.

Leider hat die Version Nextcloud Hub 10 den Status “End-of-life” erreicht und ein Update ist unausweichlich.
Die “Maintenance und Release Planung” unter https://github.com/nextcloud/server/wiki/Maintenance-and-Release-Schedule möchte ich hier als gute und übersichtliche Quelle verlinken.

Dieser Artikel beschreibt mein Vorgehen und die Fehlerbehebung beim Update von NC31 auf NC32.

Meine Nextcloud Umgebung

Ich setze die Version Nextcloud Hub 10 (31.0.14) mit einer MariaDB 11.8.6 (mariadb:lts) ein. Die MariaDB hatte ich in Vorbereitung auf das NC32 Update bereits schrittweise von 11.6 auf 11.8 upgedated. Der Stack läuft auf einem Raspberry Pi4, der Docker wird “rootfull” (also nicht “rootless”) betrieben.

Update Pfad

Im Prizip Standard-Vorgehen:

Herunterfahren des Nextcloud-Stacks
Sichern aller Bind-Volumes in ein TAR Archiv
Container Images aktualisieren
Starten des aktualisierten Stacks

        
      
docker compose down;
tar cvzf nc31.tgz /data/docker/nextcloud;
docker compose pull;
docker compose up -d

Da das Update von NC31 auf NC32 im Testsystem auf die Bretter ging, bin ich etwas defensiver an das Update meiner Prod Umgebung herangegangen.

Erfahrungen im Testsystem

Ich nutze eine weitere Nextcloud-Instanz als Testsytem für Updates oder Apps. Die Konfiguration entspricht fast der meiner produktiven Nextcloud Instanz. Einziger Unterschied: Das Testsystem läuft auf einem rootless Docker.

Beim Update trat der Fehler auf, das der Stack in eine bootloop lief, weil das Update-Script scheiterte.

Troubleshooting

Da der nextcloud-app container für eine gewisse Zeit lief, konnte ich zunächt im Container schauen was Sache ist.

docker exec -it nextcloud-app /bin/bash

Beim Update wird innerhalb des containers nextcloud-appder Befehl

        
      
rsync -rlDog --chown www-data:www-data --delete --exclude-from=/upgrade.exclude /usr/src/nextcloud/ /var/www/html/

ausgeführt. Der rsync lief bei mir mit einem “permission denied” vor die Wand - und konnte nicht die Dateien kopieren.

Ich überprüfte also die Berechtigungen. Dabei fiel mir auf, das einige Verzeichnisse mit 100032:100032, andere mit root:root berechtigt waren. Ich habe dann im laufenden Container geschaut, welche Files vom Update excluded sind.

        
      
root@e6502e4924df:/var/www/html# cat /upgrade.exclude
/config/
/data/
/custom_apps/
/themes/
/version.php
/nextcloud-init-sync.lock

Weitere Erkenntnis war, das die Bereiche mit der Berechtigung root:root nicht kopiert werden konnten.

Mit einem beherzten

        
      
chown 100032:100032 `find -group root`

habe ich das dann korrigiert. Das Update lief dann durch. Die Nacharbeiten waren dann identisch zum Prod-System.

Erfahrung im Prod-System

Nach der Anpassung der docker-compose.yaml ( image: nextcloud:31 -> image: nextcloud:32) habe ich den Stack mit

docker compose up

hochgefahren. Nach ca. 2min konnte ich mich einloggen, alles lief. Ein Traum. Offensichtlich waren die Probleme im Testsystem dem rootless Mode geschuldet.

Folgende Fehler wurden nach dem Start in den Sicherheits- & Einrichtungswarnungen moniert.

AppAPI-Bereitstellungs-Daemon Der standardmäßige Bereitstellungs-Daemon von AppAPI verwendet kein HaRP.
Für eine bessere Leistung sollte ein Upgrade darauf in Erwägung gezogen werden. Beschreibung siehe im folgenden Abschnitt.
MIME-Type-Migrationen verfügbar
Lösung: Verwende den Befehl occ maintenance:repair --include-expensive, um die Migrationen durchzuführen.
In der Datenbank fehlen Indizes
Lösung: Bitte den Befehl occ db:add-missing-indices verwenden, um sie hinzuzufügen.

AppAPI

Mit der NC32 wird ein neues Feature verpflichtend - AppAPI.
Den ersten Berührpunkt hat man, wenn man in den Sicherheits- & Einrichtungswarnungen schaut, ob das Update gut gelaufen ist…. und die genannten Fehler aufleuchten. Eingeführt wurde das bereits mit den letzten NC31 Versionen - allerdings musste man das nicht konfigurieren, wenn man es nicht brauchte.

Was ist AppAPI ?

Braucht man das ? Keine Ahnung, “it depends”.
Ich habe erstmal ein wenig recherchiert, was AppAPI genau macht.
Eine gute Erklärung zu dem Thema AppAPI liefert Thomas Joos auf der Seite https://www.computerweekly.com/de/tipp/Nextcloud-externe-Apps-mit-Docker-und-AppAPI-einrichten. Sehr empfehlenswert.

Einrichtungs-Alternativen

Folgende Alternativen zum Umgang mit der AppAPI habe ich recherchiert:

AppAPI disablen
Docker Socket Proxy 1.0 installieren
Docker Socket Proxy 2.0 / HaRP Proxy installieren

Variante AppAPI disablen

Man kann die AppAPI einfach deaktivieren.

Im Nextcloud-Interface rechts-oben auf das Profil klicken → Apps → links via "Deine Apps" eine Liste der aktiven Apps anzeigen → AppAPI deaktivieren → fertig

Variante Docker Socket Proxy

Eine wirklich gute und ausführliche Erklärung zum Thema AppAPI im Detail: Grundlagen, Einrichtung und Konfiguration ist auf https://decatec.de/home-server/nextcloud-mit-externen-apps-erweitern-die-appapi-im-detail-grundlagen-einrichtung-und-konfiguration/ zu finden.

Für die Einrichtung des Docker Socket Proxy reicht folgender Einzeiler:

        
      
docker run -e NC_HAPROXY_PASSWORD="MeinPassw0rt" \
--network=bridge \
-p 127.0.0.1:2375:2375 \
-v /var/run/docker.sock:/var/run/docker.sock \
--name nextcloud-appapi-dsp \
-h nextcloud-appapi-dsp \
--restart always \
--privileged \
-d ghcr.io/nextcloud/nextcloud-appapi-dsp:release

Variante HaRP Proxy

DECATEC hat auch zum Thema AppAPI mit HaRP einen sehr guten Artikel auf https://decatec.de/home-server/nextcloud-mit-externen-apps-erweitern-appapi-mit-harp/ bereitgestellt. Wie beim Docker Socket Proxy reduziert sich die Installation des HaRP Proxy auf eine Zeile.

        
      
docker run \
  -e HP_SHARED_KEY="MeinSicheresPasswort!123" \
  -e NC_INSTANCE_URL="https://nextcloud.meinedomain.de" \
  -e HP_EXAPPS_ADDRESS="127.0.0.1:8780" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v `pwd`/certs:/certs \
  --name appapi-harp -h appapi-harp \
  --restart unless-stopped \
  --network host \
  -d ghcr.io/nextcloud/nextcloud-appapi-harp:release

Auf jeden Fall vielen Dank an Jan Rehr für die sehr verständlichen und ausführlichen Artikel.

Meine Anpassungen / HaRP im Docker-Mode

Im Beispiel oben wird der HaRP im Host Modus betrieben. Ich stecke den HaRP-Container in das Nextcloud Netzwerk und habe dafür ein docker-compose.yaml erzeugt:

        
      
  services:
  nextcloud-appapi-harp:
    image: ghcr.io/nextcloud/nextcloud-appapi-harp:release
    container_name: nextcloud-appapi-harp
    restart: unless-stopped
    networks:
      - ${NC_NETWORK}
    environment:
      - HP_SHARED_KEY=${HP_SHARED_KEY}
      - NC_INSTANCE_URL=${NC_URL}
#      - HP_EXAPPS_ADDRESS="127.0.0.1:8780"
      - LOG_LEVEL=info
      - DOCKER_NETWORK=${NC_NETWORK}
    ports:
      - "8780:8780"  # Optional: Port für den HaRP-Daemon, falls extern zugreifbar
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro  # Zugriff auf Docker-Daemon
      - ${HP_ROOT}/certs:/certs

networks:
  ${NC_NETWORK}:
    external: true

  

Die Variablen ziehe ich aus einer .env:

HP_ROOT=Pfad zum Bind-Volume
HP_SHARED_KEY=SuperSichererSchlüssel
NC_NETWORK=Netzwerk des Nextcloud Stacks
NC_URL=Nextcloud URL

Registrieren des HaRP-Proxy

Wie im Beispiel beschrieben, muß man diesen HaRP-Proxy dann über Administration -> AppAPI in der Nextcloud registrieren.

Achtung: Beim Registrieren des Daemons achtet auf die richtige Daemon-Konfigurationsvorlage: Ich habe HaRP Proxy (Docker) gewählt !

Die Maske mit der Registrierung des HaRP-Proxy sieht dann so aus:

Die Verbindung steht nun, man kann eine Bereitstellung testen.

Reverse Proxy anpassen

Ich nutze aktuell einen NPMPlus Reverse Proxy.

Hier musste ich beim Nextcloud-Proxy-Host eine “Custom Location” /exapps/ einrichten, die auf den Port 8780 des Docker-Hosts mit dem HaRP-Container zeigt.
Die Verwendung Container-Names (wie im Screenie) hat bei mir nicht funktioniert.

ALs Options habe ich dann noch

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;
proxy_read_timeout 1800s;

gesetzt.

Ergänzende Quelle und Trobleshooting-Hilfe dazu: https://github.com/nextcloud/HaRP

Fazit

Das war nun nicht mein erstes Nextcloud Update, aber dennoch eines der zeitaufwändigeren.
Minor Updates gehen in der Regel problemlos von der Hand.
Major Updates erfordern grundsätzlich etwas mehr Vorbereitung - ein restorefähiges Backup beruhigt. Daher war die gründliche Vorbereitung (Backup, Recherche zu AppAPI) gut investierte Zeit. Das Update von NC31 auf NC32 funktionierte grundsätzlich im Prod-System gut. Allerdings ging das Update im ersten Test auf die Bretter - nicht so gut und zeitintensiv.
Die meiste Zeit ging bei der AppAPI bzw. dem HaRP-Proxy drauf, der in meiner Prod-Umgebung nicht auf Anhieb funktionierte. Insgesamt eine Version, die Nextcloud merklich einen Schritt nach vorn bringt, gerade was das Angebot an App-Paketen angeht.

homelab, docker, nextcloud

homelab docker nextcloud

This post is licensed under CC BY 4.0 by the author.