Deep Dive: Nextcloud op K3s – PHP-pods, databases op de host en Office in de browser

Nextcloud is een grote PHP-applicatie met achtergrondtaken, pushmeldingen, previews, een officepakket en tientallen apps. Hoe de onderdelen hier op twee servers samenwerken, wat ze snel houdt, welke waarschuwingen verwacht zijn – en de fouten die het meest leerden.

Illustratie voor de Deep Dive-serie

🌐 Ook in: English · Deutsch · Français · Español · Italiano · Português · Polski

Deep Dive in de serie rond de Ansible Tour. De tour legt de rollen uit, de deep dives de techniek eronder: hoe het werkt, waarom het hier zo wordt gebruikt en wat er onderweg misging.

Op deze setup draaien twee Nextcloud-servers, één voor een organisatie met ongeveer 150 accounts en bijna 400 GB aan bestanden, één voor een kleine groep. Beide worden gebouwd uit dezelfde rollen (deel 4 van de tour). Deze post legt uit hoe Nextcloud in elkaar zit, hoe de onderdelen over host en cluster verdeeld zijn en wat het beheer tot nu toe heeft geleerd.

Inhoud

🧭 Hoe Nextcloud werkt

Eén PHP-applicatie, veel ingangen

Nextcloud is PHP. Elke browserpagina, elk WebDAV-request van een synchronisatieclient en elke API-call van de mobiele apps is een PHP-request via nginx naar PHP-FPM. De bestanden zelf staan in een datamap; de database kent elk bestand via de tabel file cache – naam, grootte, ETag, rechten – zodat overzichten nooit de schijf hoeven aan te raken.

Locking en caching

Als twee clients hetzelfde bestand wijzigen, beslist transactional file locking wie wint. De locks moeten voor alle PHP-processen tegelijk zichtbaar zijn, daarom staan ze in Redis. Daarnaast cachet APCu per proces en Redis over processen heen.

Achtergrondtaken

Opruimen, prullenbak en versies laten verlopen, meldingen, controles op app-updates, previews vooraf genereren – Nextcloud houdt een takenwachtrij bij in de database. Iets moet regelmatig cron.php draaien om die af te werken; Nextcloud raadt elke vijf minuten aan.

Push, previews, office

  • notify_push is een kleine Rust-daemon die in een app wordt meegeleverd. Clients houden er een WebSocket mee open en horen meteen over wijzigingen, in plaats van elke 30 seconden te vragen.
  • Previews zijn miniaturen, gegenereerd bij de eerste weergave of vooraf door de app Preview Generator, en opgeslagen in de app-datamap.
  • Nextcloud Office is de app richdocuments plus een Collabora Online-server. De browser laadt de editor van Collabora; Collabora haalt het document op uit Nextcloud en slaat het daar op via het WOPI-protocol, met een token per sessie.

Apps en occ

Bijna alles naast bestanden is een app – agenda, contacten, Talk, group folders. occ is de commandlinetool voor al het beheer: status, upgrades, onderhoudsmodus, configuratie, bestandsscans, databasereparaties.

🛡️ Waarom het hier draait

  • Bestanden, agenda’s, contacten en office op één plek, voor mensen die niet hoeven te weten wat WebDAV is.
  • De data blijft op de eigen servers van de organisatie. Geen leverancier beslist over toegang, prijzen of functies.
  • Een ecosysteem. Apps voor bijna elke behoefte, clients voor elk platform, een grote community.

🔧 Wat deze repository doet

Wat draait waar

ComponentWaarRol
nginx + PHP-FPM + exporterPod nextcloudnext_k3s_deploy
notify_pushEigen Deployment, zelfde imagenext_k3s_deploy
Collabora OnlineEigen Deploymentnext_k3s_deploy
AchtergrondtakenCronJob elke 5 minnext_k3s_deploy
MariaDBHost, mysqld_tnext_mariadb
RedisHost, redis_tnext_redis
Instellingen, apps, WOPI, wachtwoordbeleidvia occnext_config

De zware, kostbare onderdelen – database en data – leven op de host, met de volledige systemd-sandbox en eigen SELinux-domeinen. De vervangbare – PHP, Collabora, de push-daemon – draaien in het cluster. Kubernetes-Services zonder selectors, die naar het node-IP wijzen, maken MariaDB en Redis voor de pods bereikbaar onder de namen mariadb en redis; nftables staat die poort alleen vanuit het podnetwerk toe. De PHP-code (/srv/nextcloud-www) en de data (/data) zijn hostPath-volumes met eigen SELinux-labels.

Configuratie in lagen

Nextcloud leest config.php en daarna elk *.config.php in de configmap in alfabetische volgorde, waarbij latere bestanden winnen. De repository maakt daar gebruik van: custom.config.php uit een ConfigMap bevat de instellingen (caches, previews, proxies, logging), redis.config.php uit een Secret bevat het Redis-wachtwoord. Beide worden met subPath gemount, wat in een draaiende pod nooit wordt bijgewerkt; een checksum van alles wat gemount is staat als annotation op de pod, dus een wijziging laat de pod opnieuw uitrollen. Die checksum dekte oorspronkelijk alleen de ConfigMaps – een nieuwe preview-instelling stond ooit een dag in de ConfigMap terwijl de pod nog het oude bestand draaide. Sinds deze serie dekt hij ook het Secret, nadat de deep dive over Redis ontdekte dat een geroteerd wachtwoord de pod niet zou hebben bereikt.

Collabora

TLS eindigt bij de ingress, dus Collabora draait daarachter plain HTTP en krijgt dat ook te horen. num_prealloc_children houdt zoveel documentprocessen vooraf gestart; een document openen kost er één, en als er geen klaarstaat wacht de gebruiker tot een nieuwe is opgestart. Het af en toe voorkomende “laden mislukt, opnieuw proberen werkt” vlak na een herstart van Collabora is precies dat. De grotere server houdt er tien klaar, de kleinere zes. next_config zet de WOPI-allowlist op het podnetwerk – alleen Collabora mag de WOPI-endpoints aanroepen – en laat Nextcloud het discovery-document van Collabora na elke Collabora-wijziging opnieuw inlezen.

Eén installatiedetail kostte een middag: occ app:install richdocuments kapte bij het uitpakken reproduceerbaar één bestand van de app af, en de integriteitscontrole faalde daarna. De rol downloadt de tarball daarom zelf uit de app store, pakt hem uit met tar en controleert de handtekeningen van de app met occ integrity:check-app.

De les: Een integriteitswaarschuwing na een installatie is echt. Hier was de oorzaak de tool die bij het uitpakken een bestand afkapte, niet de app.

Updates in twee soorten

Een versiewissel is een nieuwe image-tag in versions.yml en een run van het hoofdplaybook; het entrypoint van de container draait bij de start occ upgrade. Nextcloud zelf weigert een major-versie over te slaan, dus een sprong van 32 naar 34 gaat in twee stappen. Herbouwde images – Docker Hub herbouwt ongewijzigde tags voor fixes in het base image, en K3s pullt nooit uit zichzelf opnieuw – zijn de taak van nextcloud-update.yml. Dat weigert te draaien zonder --limit (één server tegelijk), weigert te starten op een instantie die in onderhoudsmodus staat of een openstaande database-upgrade heeft, herstart alleen Deployments waarvan het image echt veranderd is, draait occ upgrade als vangnet, werkt de apps bij, herstart een tweede keer (OPcache controleert geen timestamps, zie de deep dive over PHP-FPM) en controleert de status. Als er iets misgaat, verzamelt een rescue-blok de toestand voor een beslissing met de hand. Beide servers draaien Nextcloud 34.

Sinds 26 oktober 2026 rolt de Nextcloud-pod zonder downtime zolang het image hetzelfde blijft – bij configuratiewijzigingen en rebuilds van dezelfde tag: de nieuwe pod wordt ready, daarna stopt de oude. Als het image verandert, blijft het bij Recreate. Het entrypoint kopieert dan nieuwe code naar /var/www/html en draait occ upgrade, en in de tussentijd mag geen oude pod pagina’s uit dezelfde map serveren.

De les: Een rolling update is alleen veilig als twee versies tegelijk mogen draaien. Tijdens een versiewissel van Nextcloud mogen ze dat niet.

Isolatie

  • Een NetworkPolicy laat Collabora alleen met Nextcloud en DNS praten, en alleen verbindingen van Nextcloud en de node accepteren. De Nextcloud-pod en de push-daemon hebben er nog geen – anders dan bij de blog, waar elke pod geïsoleerd is. In een cluster waarin verder niets draait is dat geen open deur, maar wel een ontbrekende laag; gevonden tijdens het schrijven van dit artikel en voorgesteld.
  • Een admission policy laat alleen images toe uit een allowlist van registries – inclusief het image van de ACME-solver van cert-manager, die in deze namespace draait; bij de blog liet het ontbreken daarvan ooit een certificaataanvraag zonder enige fout in de wachtstand hangen.
  • Geen service-account-tokens in de pods – niets daarin praat met de Kubernetes-API.
  • ClamAV scant de bestanden om 04:30 op de achtergrond, met previews en mediaformaten uitgesloten – vóór die wijziging was de scan de oorzaak van een server die zonder zichtbare reden als “bezet” verscheen.

📊 Gemeten

Nextcloud ANextcloud B
Versie34.0.534.0.5
Accounts / actief in de laatste 7 dagen152 / 2726 / 1
Data388 GB16 GB
Items in de file cache73.0617.415
Apps ingeschakeld / uitgeschakeld43 / 2261 / 8
Run van de achtergrondtaken (cron.php)8–16 s elke 5 min6–8 s elke 5 min
Langste afzonderlijke taak133 s (updatecontrole)59 s (updatecontrole)
Beheeroverzichtalle controles groenéén logfout, verwacht (zie hieronder)

De file cache van de grotere server had na de migratie van de oude server meer dan tien keer zoveel items: de teruggezette database bevatte nog de hele bestandsindex van de oude server, en occ files:cleanup deed niets zolang de storage-rij van het oude pad bestond. Een kwart van wat overbleef hoorde bij restanten van een eerder gebruikte office-app. Beide zijn verwijderd – na een back-up en na het tellen van de live rijen, want data van uitgeschakelde apps blijft uit principe bewaard, voor het geval iemand ze terug wil.

De les: Een teruggezette database neemt de bestandsindex van de oude server mee. occ files:cleanup verwijdert die pas als het item van de oude storage gewist is.

🧰 Dagelijks beheer

occ() { k3s kubectl -n nextcloud exec deploy/nextcloud -c nextcloud-fpm -- \
  runuser -u www-data -- php /var/www/html/occ "$@"; }

occ status
occ setupchecks                       # the admin overview, on the command line
occ maintenance:mode --on             # before anything that touches data
occ files:scan --path="/alice/files"  # after files were changed outside Nextcloud
occ db:add-missing-indices
occ background-job:list --limit=20
occ app:list --disabled

Verwachte waarschuwingen

  • “Fouten in het log” op de kleinere server: één databasefout om 03:30 – de nachtelijke reboot, waarbij een pod voor achtergrondtaken mariadb niet kon resolven. Onschuldig, maar hij blijft in het overzicht staan tot het log roteert.
  • “Office laden mislukt, opnieuw proberen werkt” vlak na een herstart: Collabora had nog geen vooraf gestart proces.
  • Integriteitswaarschuwingen na een handmatige wijziging in de app-map zijn echt: Nextcloud ondertekent zijn code, en elk bewerkt bestand valt op. Bewerk nooit app-code ter plekke.

Back-ups en herstel

Elke nacht haalt een back-upmachine de databasedump, config.php en de datamap via SSH op en bewaart er 365 dagen versies van. Een herstel is het omgekeerde plus occ maintenance:data-fingerprint, dat de synchronisatieclients vertelt dat de serverstatus veranderd is, zodat ze niet verwijderen wat ze voor nieuw houden.

🆘 Spiekbriefje: symptoom → commando

De korte versie van dit artikel voor het moment dat er iets mis is. Uitvoeren op de host als root; <…> zijn placeholders. occ en wp zijn de shellfuncties uit de deep dives over Nextcloud en WordPress.

SymptoomCommando
Eerste blikocc status
occ setupchecks
Vast in onderhoudsmodusocc maintenance:mode --off
Buiten Nextcloud gewijzigde bestanden ontbrekenocc files:scan --path="/<user>/files"
Oude code na een app-updatek3s kubectl -n nextcloud rollout restart deployment/nextcloud
Achtergrondtaken lopen achterocc background-job:list --limit=20
k3s kubectl -n nextcloud get cronjob nextcloud-cron
Office-documenten openen nietk3s kubectl -n nextcloud logs deploy/collabora --tail=50
occ richdocuments:activate-config
Clients synchroniseren niet directocc notify_push:self-test
k3s kubectl -n nextcloud logs deploy/notify-push --tail=20
Previews vreten de schijf opocc preview:cleanup # never rm: previews live in the database
Waarschuwingen na een upgradeocc db:add-missing-indices
occ app:list --disabled
Na het terugzetten van een back-upocc maintenance:data-fingerprint

🎯 De lessen

  • Wat waardevol is – database en data – hoort op de host, wat vervangbaar is in het cluster.
  • Configuratie in lagen: latere *.config.php-bestanden winnen, notify_push leest alleen config.php.
  • Herstart na occ upgrade of app:update de pod, anders blijft oude bytecode draaien.
  • Een rolling update alleen waar twee versies tegelijk mogen draaien.
  • Ruim na een migratie de oude bestandsindex op.

⚖️ Alternatieven – en waarom Nextcloud

OptieSterk puntWaarom niet hier
SeafileVeel snellere sync, opslag op blokniveauMinder groupware-functies, data niet als gewone bestanden opgeslagen.
ownCloud Infinite ScaleGo, geen PHP, geen databaseAndere architectuur, kleiner app-ecosysteem, zou een migratie van alles betekenen.
Een propriëtaire cloudNiets zelf te draaienData en toegang bepaald door een leverancier – het tegendeel van het doel.
NextcloudFuncties, apps, clients, community, de bestaande dataGekozen.

Nextcloud is niet moeilijk te installeren; het is veeleisend om goed te draaien, omdat het een dozijn services is die doen alsof ze er één zijn. Ze opsplitsen langs “kostbaar of vervangbaar” – database en bestanden op de host, PHP en office in het cluster – maakte elk deel eenvoudiger om over na te denken. De fouten in deze post zaten bijna allemaal op de naden ertussen.

Sommige teksten en afbeeldingen op deze site zijn met hulp van AI gemaakt of door AI gegenereerd. Details