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.

🌐 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
| Component | Waar | Rol |
|---|---|---|
| nginx + PHP-FPM + exporter | Pod nextcloud | next_k3s_deploy |
| notify_push | Eigen Deployment, zelfde image | next_k3s_deploy |
| Collabora Online | Eigen Deployment | next_k3s_deploy |
| Achtergrondtaken | CronJob elke 5 min | next_k3s_deploy |
| MariaDB | Host, mysqld_t | next_mariadb |
| Redis | Host, redis_t | next_redis |
| Instellingen, apps, WOPI, wachtwoordbeleid | via occ | next_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 A | Nextcloud B | |
|---|---|---|
| Versie | 34.0.5 | 34.0.5 |
| Accounts / actief in de laatste 7 dagen | 152 / 27 | 26 / 1 |
| Data | 388 GB | 16 GB |
| Items in de file cache | 73.061 | 7.415 |
| Apps ingeschakeld / uitgeschakeld | 43 / 22 | 61 / 8 |
| Run van de achtergrondtaken (cron.php) | 8–16 s elke 5 min | 6–8 s elke 5 min |
| Langste afzonderlijke taak | 133 s (updatecontrole) | 59 s (updatecontrole) |
| Beheeroverzicht | alle 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
mariadbniet 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.
| Symptoom | Commando |
|---|---|
| Eerste blik | occ statusocc setupchecks |
| Vast in onderhoudsmodus | occ maintenance:mode --off |
| Buiten Nextcloud gewijzigde bestanden ontbreken | occ files:scan --path="/<user>/files" |
| Oude code na een app-update | k3s kubectl -n nextcloud rollout restart deployment/nextcloud |
| Achtergrondtaken lopen achter | occ background-job:list --limit=20k3s kubectl -n nextcloud get cronjob nextcloud-cron |
| Office-documenten openen niet | k3s kubectl -n nextcloud logs deploy/collabora --tail=50occ richdocuments:activate-config |
| Clients synchroniseren niet direct | occ notify_push:self-testk3s kubectl -n nextcloud logs deploy/notify-push --tail=20 |
| Previews vreten de schijf op | occ preview:cleanup # never rm: previews live in the database |
| Waarschuwingen na een upgrade | occ db:add-missing-indicesocc app:list --disabled |
| Na het terugzetten van een back-up | occ 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 alleenconfig.php. - Herstart na
occ upgradeofapp:updatede 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
| Optie | Sterk punt | Waarom niet hier |
|---|---|---|
| Seafile | Veel snellere sync, opslag op blokniveau | Minder groupware-functies, data niet als gewone bestanden opgeslagen. |
| ownCloud Infinite Scale | Go, geen PHP, geen database | Andere architectuur, kleiner app-ecosysteem, zou een migratie van alles betekenen. |
| Een propriëtaire cloud | Niets zelf te draaien | Data en toegang bepaald door een leverancier – het tegendeel van het doel. |
| Nextcloud | Functies, apps, clients, community, de bestaande data | Gekozen. |
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.
