Nextcloud – Betriebs­dokumentation

Überblick

Nextcloud läuft auf einem Single-Node-K3s-Cluster auf AlmaLinux 9. Die gesamte Infrastruktur wird mit einem Ansible-Playbook (nextcloud-k3s.yml) aufgebaut und verwaltet. Das Playbook ist idempotent – es kann jederzeit neu ausgeführt werden, ohne Daten zu verändern oder Dienste unnötig zu unterbrechen.

Architektur

Gesamtüberblick

Warum dieser Ansatz?

Nextcloud-Pod im Detail

Beide Container teilen sich denselben Pod (= dasselbe Netzwerk-Namespace und die gleichen Volumes). Dadurch kann nginx via 127.0.0.1:9000 mit PHP-FPM kommunizieren, ohne einen Kubernetes-Service zu benötigen.

Speicher & Daten

Warum sind App und Daten getrennt?

Nextcloud-App-Dateien (/srv/nextcloud-www) und Benutzerdaten (/data) sind bewusst in zwei separate HostPath-Volumes aufgeteilt, weil:

• Benutzerdaten können unabhängig gesichert werden (täglich empfohlen)
• App-Dateien werden bei einem Update durch das neue Image ersetzt
• Bei einer Neu-Installation genügt ein leeres /srv/nextcloud-www – Nextcloud installiert sich selbst beim ersten Start

Wichtige Konfigurationsdatei: config.php

Nextcloud liest alle *.php-Dateien aus /var/www/html/config/ automatisch. Es gibt zwei Quellen:

• config.php – von Nextcloud selbst geschrieben (Erstinstallation)
• custom.config.php – aus dem Kubernetes-ConfigMap nextcloud-custom-config, verwaltet durch Ansible. Diese Datei hat Vorrang und überschreibt Werte aus config.php.

Netzwerk & TLS

IP-Adressbereiche

Benötigte DNS-Einträge

Vor dem ersten Playbook-Lauf müssen die DNS-Einträge beim Domain-Registrar angelegt sein. cert-manager benötigt sie für den Let's Encrypt HTTP-01-Challenge – ohne gültige Einträge schlägt die Zertifikatsausstellung fehl.

Wie Pods den Host erreichen (MariaDB / Redis)

MariaDB und Redis laufen als Host-Dienste. Pods verbinden sich darüber via K8s ExternalServices: ein Service ohne Selector mit manuell gepflegten Endpoints, die auf die öffentliche IP des Hosts zeigen.

Pod → mariadb.nextcloud.svc.cluster.local (10.43.x.x)
   → Endpoint: 82.165.165.230:3306
   → iptables ACCEPT für 10.42.0.0/16 auf :3306

Der MariaDB-Datenbanknutzer ist auf den Pod-CIDR eingeschränkt ('nextcloud'@'10.42.%'). Eine direkte Verbindung vom Host funktioniert nur als root via Unix-Socket.

TLS und Proxy-Kette

Internet
  → nginx-ingress (F5) (Port 443, TLS terminiert, setzt X-Forwarded-For / -Proto)
    → nginx-Sidecar (Port 80, plain HTTP)
      → PHP-FPM (Port 9000, FastCGI)
        fastcgi_param HTTPS on
        fastcgi_param HTTP_SCHEME https

Nextcloud muss wissen, dass Anfragen über einen Proxy kommen:

'trusted_proxies'       => ['10.42.0.0/16'],
'forwarded_for_headers' => ['HTTP_X_FORWARDED_FOR'],
'overwriteprotocol'     => 'https',

WOPI (Collabora)

Collabora ruft für die Dokument-Bearbeitung Nextclouds WOPI-API auf. Diese Rückrufe kommen von der Pod-IP des Collabora-Pods (10.42.x.x) – nicht von der Service-IP. Die wopi_allowlist muss daher den Pod-CIDR enthalten:

# inventory/host_vars/<host>/vars.yml
wopi_allowed_hosts:
  - "10.42.0.0/16"   # Pod-CIDR (Collabora-Pod → Nextcloud WOPI)
  - "10.43.0.0/16"   # Service-CIDR
  - "collabora.inspired-as-code.de"

Wichtige Dateien im Repository

Inventory & Variablen

Ansible-Rollen (Nextcloud-spezifisch)

Templates (erzeugen die K8s-Manifeste)

Variablen & Secrets

Wo Credentials liegen

Alle Passwörter stehen in inventory/host_vars/<host>/vault.yml, verschlüsselt mit Ansible Vault. Diese Datei darf niemals unverschlüsselt in git committed werden.

# Verschlüsseln vor dem Commit:
ansible-vault encrypt inventory/host_vars/test/vault.yml

# Entschlüsseln zum Bearbeiten:
ansible-vault decrypt inventory/host_vars/test/vault.yml
# (danach sofort wieder verschlüsseln!)

# Direkt im Editor öffnen (bevorzugt):
ansible-vault edit inventory/host_vars/test/vault.yml

Passwort-Eintrag für unbeaufsichtigte Runs

# .vault_pass (niemals committen – steht in .gitignore)
echo "mein-vault-passwort" > .vault_pass
# In ansible.cfg einkommentieren:
# vault_password_file = .vault_pass

Secrets im K8s-Cluster

Die Vault-Variablen fließen beim Playbook-Run in das K8s-Secret nextcloud-secrets im Namespace nextcloud. Das Secret wird als Umgebungsvariablen in den Pod injiziert.

# Secret anzeigen (dekodiert):
k3s kubectl get secret nextcloud-secrets -n nextcloud \
  -o jsonpath='{.data}' | python3 -c \
  "import sys,json,base64; [print(k,base64.b64decode(v).decode()) \
   for k,v in json.load(sys.stdin).items()]"

Container-Images & Versionen

Alle Image-Tags sind in inventory/group_vars/all.yml zentral definiert. Da imagePullPolicy standardmäßig IfNotPresent für getaggte Images ist, zieht K3s automatisch ein neues Image nur dann, wenn der Tag im Manifest geändert wurde.

# inventory/group_vars/all.yml
nextcloud_image_fpm:       "nextcloud:33-fpm"      # Nextcloud PHP-FPM
nextcloud_image_nginx:     "nginx:1.30-alpine"          # nginx Sidecar
nextcloud_image_collabora: "collabora/code:25.04.9.4.1" # Collabora CODE
nextcloud_image_busybox:   "busybox:1"             # Init-Container

Tag-Strategie

crictl pull docker.io/library/nextcloud:33-fpm
k3s kubectl rollout restart deployment/nextcloud -n nextcloud

Nextcloud-Konfiguration

Die Konfiguration erfolgt auf zwei Wegen:

1. custom.config.php (via Ansible ConfigMap) – statische Einstellungen, die bei jedem Playbook-Run aktualisiert werden
2. occ-Befehle (via kubectl exec) – dynamische Einstellungen wie trusted_domains, WOPI-URL, App-Installation

custom.config.php – Übersicht der Schlüsselwerte

// Sprache
'default_language'     => 'de',
'default_locale'       => 'de_DE',
'force_language'       => 'de',

// Session (1 Stunde, kein "Angemeldet bleiben")
'session_lifetime'               => 3600,
'auto_logout'                    => true,
'remember_login_cookie_lifetime' => 0,

// Redis (Cache, Locking, Sessions)
'memcache.local'       => '\\OC\\Memcache\\Redis',
'memcache.distributed' => '\\OC\\Memcache\\Redis',
'memcache.locking'     => '\\OC\\Memcache\\Redis',
'redis' => ['host' => 'redis', 'port' => 6379],

// Reverse-Proxy
'trusted_proxies'       => ['10.42.0.0/16'],
'forwarded_for_headers' => ['HTTP_X_FORWARDED_FOR'],
'overwriteprotocol'     => 'https',

// Logging (in /data/nextcloud.log auf dem Host)
'loglevel'        => 4,
'logtimezone'     => 'Europe/Berlin',
'log_rotate_size' => 104857600,   // 100 MB

// Wartungsfenster (1 Uhr nachts)
'maintenance_window_start' => 1,

Konfiguration nach Playbook-Run prüfen

k3s kubectl exec -n nextcloud deployment/nextcloud -c nextcloud-fpm -- \
  runuser -u www-data -- php /var/www/html/occ config:list system

k3s kubectl exec -n nextcloud deployment/nextcloud -c nextcloud-fpm -- \
  runuser -u www-data -- php /var/www/html/occ setupchecks

Playbook ausführen

Vollständiger Erstlauf (neue Server-Installation)

1. SSH-Port auf 22 setzen in inventory/host_vars/test/vars.yml: ansible_port: 22
2. Vault-Passwörter in vault.yml eintragen und verschlüsseln
3. Collections installieren: ansible-galaxy collection install -r requirements.yml
4. Playbook ausführen:

   ansible-playbook nextcloud-k3s.yml --limit test --ask-vault-pass

5. SSH-Port in vars.yml auf 10022 ändern (nach SSH-Hardening durch common_ssh)

Idempotente Wiederholung (z.B. nach Konfig-Änderung)

ansible-playbook nextcloud-k3s.yml --limit test --ask-vault-pass

Das Playbook erkennt, was bereits korrekt konfiguriert ist, und ändert nur, was nötig ist. Kubernetes-Manifeste werden nur dann neu gerollt, wenn sich das Manifest geändert hat (changed: "configured" in output).

Nur bestimmte Rollen ausführen

# Nur Nextcloud-Konfiguration (occ-Befehle)
ansible-playbook nextcloud-k3s.yml --limit test --tags next_config --ask-vault-pass

# Nur K8s-Deployments aktualisieren
ansible-playbook nextcloud-k3s.yml --limit test --tags next_k3s_deploy --ask-vault-pass

Wichtige Betriebsbefehle

Pod-Status

# Alle Pods im nextcloud-Namespace
k3s kubectl get pods -n nextcloud

# Detaillierter Status (Events bei Problemen)
k3s kubectl describe pod -l app=nextcloud -n nextcloud

# Logs
k3s kubectl logs deployment/nextcloud -c nextcloud-fpm -n nextcloud --tail=50
k3s kubectl logs deployment/nextcloud -c nginx -n nextcloud --tail=50
k3s kubectl logs deployment/collabora -n nextcloud --tail=50

occ-Befehle (Nextcloud-CLI)

# Prefix für alle occ-Befehle:
k3s kubectl exec -n nextcloud deployment/nextcloud -c nextcloud-fpm -- \
  runuser -u www-data -- php /var/www/html/occ <BEFEHL>

# Beispiele:
... occ status
... occ check
... occ setupchecks
... occ maintenance:mode --on
... occ maintenance:mode --off
... occ files:scan --all
... occ db:add-missing-indices
... occ app:list
... occ config:list system
... occ config:system:get trusted_domains

Pod neustarten

# Nextcloud (rollt graceful durch wegen Recreate-Strategie)
k3s kubectl rollout restart deployment/nextcloud -n nextcloud
k3s kubectl rollout status  deployment/nextcloud -n nextcloud --timeout=300s

# Collabora
k3s kubectl rollout restart deployment/collabora -n nextcloud

Namespace-Übersicht

k3s kubectl get all -n nextcloud

MariaDB (Host)

# Als root via Socket (Credentials in /root/.my.cnf):
mysql test_nextcloud

# DB-Dump erstellen:
mysqldump --single-transaction test_nextcloud > /tmp/dump.sql

Redis (Host)

# Verbindung testen:
redis-cli ping

# Cache leeren (z.B. nach Konfigurationsänderung):
redis-cli FLUSHALL

Monitoring

Der Monitoring-Stack (Prometheus + Grafana + Node Exporter + mysqld_exporter + php-fpm_exporter) läuft teils als Host-Dienste, teils als Sidecar-Container im Nextcloud-K3s-Pod. Grafana ist über K3s-Ingress am Nextcloud-Hostname unter /grafana/ erreichbar.

MariaDB Slow Query Log

Der Host-MariaDB schreibt langsame Queries (≥ 1 Sekunde) nach /var/log/mariadb/slow.log. Die Datei wird von MariaDB automatisch angelegt und kann per journalctl oder direkt gelesen werden.

# Slow-Query-Log live lesen
tail -f /var/log/mariadb/slow.log

# Queries der letzten 24 Stunden filtern
grep -A 3 "Query_time" /var/log/mariadb/slow.log | grep -v "^--$"

# Log-Größe prüfen
ls -lh /var/log/mariadb/slow.log

Konfiguration: /etc/my.cnf.d/nextcloud-k3s.cnf → slow_query_log = 1, long_query_time = 1

PHP-FPM Slow Log

PHP-FPM loggt Requests, die länger als 5 Sekunden dauern, nach /proc/1/fd/2 (stderr des Pod-Hauptprozesses). Da ptrace in Containern nicht verfügbar ist, werden keine Stack-Traces geschrieben – nur der Request-Zeitstempel.

# Slow FPM Requests verfolgen
k3s kubectl logs -n nextcloud deployment/nextcloud -c nextcloud-fpm -f | grep -i "slow"

Konfiguration: ConfigMap nextcloud-fpm-pool-config → pm.status_path = /fpm-status, slowlog = /proc/1/fd/2, request_slowlog_timeout = 5s

Grafana Dashboards

Node Exporter Full (ID 1860) – Host-Metriken

Zeigt den Gesundheitszustand des gesamten Servers in Echtzeit.

MySQL Overview (ID 7362) – MariaDB-Datenbankmetriken

Zeigt die Performance der Nextcloud-Datenbank (Host-MariaDB, Port 9104).

PHP-FPM (ID 4912) – PHP-Prozesspool

Zeigt wie gut PHP-FPM die eingehenden Nextcloud-Anfragen verarbeitet (K3s-Pod, NodePort 30254).

mysqld_exporter – Status prüfen

# Service-Status
systemctl status mysqld_exporter

# Logs
journalctl -u mysqld_exporter -n 50

# Metriken direkt abrufen (Test)
curl -s http://127.0.0.1:9104/metrics | grep mysql_up

Updates

Betriebssystem (AlmaLinux 9)

Security-Updates werden durch dnf-automatic täglich automatisch eingespielt. Für ein vollständiges System-Update:

1. ssh -p 10022 root@server
   dnf upgrade -y

2. Prüfen ob ein Reboot nötig ist:

   needs-restarting -r

3. Bei Bedarf: Server rebooten. K3s startet automatisch nach dem Reboot, Pods kommen selbst wieder hoch.

   reboot
   # Danach prüfen:
   k3s kubectl get pods -n nextcloud

Container-Update: Patch innerhalb desselben Tags

Wenn Docker Hub z.B. nextcloud:33-fpm von 33.0.2 auf 33.0.3 aktualisiert und der Tag im Ansible unverändert bleibt:

1. Neues Image manuell pullen:

   crictl pull docker.io/library/nextcloud:33-fpm

2. Pod neu starten (nutzt jetzt das frisch gepullte Image):

   k3s kubectl rollout restart deployment/nextcloud -n nextcloud
   k3s kubectl rollout status  deployment/nextcloud -n nextcloud --timeout=300s

3. DB-Migrationen sicherstellen:

   ansible-playbook nextcloud-k3s.yml --limit test --tags next_config --ask-vault-pass

Container-Update: Major-Versionssprung (z.B. 33 → 34)

1. Tag in inventory/group_vars/all.yml ändern:

   nextcloud_image_fpm: "nextcloud:34-fpm"
   # ggf. auch:
   nextcloud_image_collabora: "collabora/code:25.08"

2. Playbook ausführen – K3s zieht das neue Image automatisch und rollt den Pod durch:

   ansible-playbook nextcloud-k3s.yml --limit test --ask-vault-pass

3. Der Nextcloud-Container führt occ upgrade beim Start automatisch aus. Der Playbook-Lauf führt anschließend die next_config-Rolle aus (DB-Indices, WOPI-Config, App-Einstellungen).
4. Admin-Panel auf Warnungen prüfen:

   k3s kubectl exec -n nextcloud deployment/nextcloud -c nextcloud-fpm -- \
     runuser -u www-data -- php /var/www/html/occ setupchecks

Wo neue Versionen nachschauen

Backup & Restore

Was gesichert wird

Backup ausführen

Das Skript erwartet den Instanz-Namen als Argument. Die Instanz steuert welcher Server kontaktiert wird und wohin lokal gesichert wird.

# Beispiel: Test-Instanz sichern
cd ~/www_k3s
./scripts/nextcloud-backup.sh test

# Ablauf (gilt für alle Instanzen):
# 1. Maintenance-Modus an  (kubectl exec occ maintenance:mode --on)
# 2. mysqldump --single-transaction → /data/nextcloud/<env>/db.sql
# 3. rsync /srv/nextcloud-www/      → /data/nextcloud/<env>/nextcloud/
# 4. rsync /data/                   → /data/nextcloud/<env>/data/
# 5. Maintenance-Modus aus

Das Skript liegt im Repository-Verzeichnis scripts/nextcloud-backup.sh. Sofie und CVJM sind erst nutzbar sobald IP und Hostname in inventory/host_vars/<env>/vars.yml eingetragen sind – das Skript prüft das und bricht mit einer Fehlermeldung ab falls noch changeme drin steht.

Restore-Workflow

Auch das Restore-Skript erwartet den Instanz-Namen als Argument:

1. Server neu aufsetzen (Infrastructure) – test durch Instanz-Namen ersetzen:

   ansible-playbook nextcloud-k3s.yml --limit test --ask-vault-pass

2. Restore-Skript ausführen (überschreibt die frische Installation):

   cd ~/www_k3s
   ./scripts/nextcloud-restore.sh test

   Ablauf: Maintenance an → Pod stoppen → rsync App-Dateien → rsync User-Daten → SQL-Import → Ownership fix → Pod starten → files:scan → Maintenance aus

3. Ansible erneut ausführen (stellt occ-Config sicher: trusted_domains, WOPI, Apps):

   ansible-playbook nextcloud-k3s.yml --limit test --ask-vault-pass

   Dieser Schritt ist bei einem Hostname-Wechsel zwingend, sonst empfohlen.

Manuelle Einzel-Befehle (Referenz)

# Maintenance-Modus
k3s kubectl exec -n nextcloud deployment/nextcloud -c nextcloud-fpm -- \
  runuser -u www-data -- php /var/www/html/occ maintenance:mode --on

# Datenbank-Dump (auf dem Server)
mysqldump --single-transaction <db_name> > /tmp/nc.sql

# Ownership nach manuellem rsync
chown -R 33:33 /srv/nextcloud-www /data
chmod 0755 /srv/nextcloud-www && chmod 0770 /data

# File-Index neu aufbauen
k3s kubectl exec -n nextcloud deployment/nextcloud -c nextcloud-fpm -- \
  runuser -u www-data -- php /var/www/html/occ files:scan --all

Troubleshooting

Pod startet nicht / bleibt in CrashLoopBackOff

k3s kubectl describe pod -l app=nextcloud -n nextcloud
k3s kubectl logs deployment/nextcloud -c nextcloud-fpm -n nextcloud --previous

Typische Ursachen:

• DB nicht erreichbar: MariaDB-Service läuft nicht oder iptables-Regeln fehlen (nach Reboot?)
• config.php leer (0 Byte): Erster Start konnte config/ nicht beschreiben wegen falscher Ownership. Lösung: chown 33:33 /srv/nextcloud-www/config, leere Datei löschen, Pod neu starten.
• Redis nicht erreichbar: systemctl status redis auf dem Host prüfen

Nextcloud-Seite lädt, aber CSS/JS fehlt (Seite sieht defekt aus)

# MIME-Typen der Assets prüfen:
curl -sI "https://nextcloud.example.com/core/css/server.css" | grep content-type
# Muss: text/css sein

curl -sI "https://nextcloud.example.com/dist/core-main.js" | grep content-type
# Muss: application/javascript sein

Ursache war in der Vergangenheit ein types {}-Block im nginx-Server-Kontext, der alle geerbten MIME-Typen überschrieben hat. Die aktuelle Konfiguration nutzt für .mjs einen dedizierten Location-Block.

Admin-Warnung: "Reverse-Proxy-Header ist falsch"

trusted_proxies fehlt in custom.config.php oder enthält nicht den K3s Pod-CIDR (10.42.0.0/16).

k3s kubectl exec -n nextcloud deployment/nextcloud -c nextcloud-fpm -- \
  runuser -u www-data -- php /var/www/html/occ config:system:get trusted_proxies

Collabora: "Unautorisierter WOPI-Host"

Die wopi_allowlist enthält nicht den Pod-CIDR (10.42.x.x). Collabora-Pods verbinden sich zum Nextcloud-WOPI von ihrer Pod-IP aus.

k3s kubectl exec -n nextcloud deployment/nextcloud -c nextcloud-fpm -- \
  runuser -u www-data -- php /var/www/html/occ \
  config:app:get richdocuments wopi_allowlist

# Korrektur:
k3s kubectl exec -n nextcloud deployment/nextcloud -c nextcloud-fpm -- \
  runuser -u www-data -- php /var/www/html/occ \
  config:app:set richdocuments wopi_allowlist \
  --value="10.42.0.0/16,10.43.0.0/16,collabora.example.de,82.165.165.230"

Zertifikat wird nicht ausgestellt

# cert-manager Logs prüfen:
k3s kubectl logs -n cert-manager deployment/cert-manager --tail=50

# Certificate-Objekt prüfen:
k3s kubectl describe certificate nextcloud-tls -n nextcloud

# ClusterIssuer-Status:
k3s kubectl describe clusterissuer letsencrypt-prod

Häufige Ursache: Port 80 ist durch iptables oder den Provider blockiert. cert-manager benötigt Port 80 für den HTTP-01-Challenge.

CronJob läuft nicht

# Status der letzten Jobs:
k3s kubectl get cronjob nextcloud-cron -n nextcloud
k3s kubectl get jobs -n nextcloud --sort-by=.metadata.creationTimestamp | tail -5

# Logs des letzten Job-Pods:
k3s kubectl logs -n nextcloud -l job-name=nextcloud-cron-<id>

Sicherheit

Mehrschichtige Schutzstrategie

Firewall im Detail

Das Skript /root/fw/fw_ipv4.sh (aus common_firewall) wird per @reboot-Cronjob nach jedem Neustart angewendet. K3s fügt danach seine eigenen KUBE-*-Chains oben in die INPUT/OUTPUT-Chains ein.

# Geblockte Pakete live verfolgen
journalctl -k -f --grep "IPTables-Dropped"

# Portscan-Blockliste anzeigen
cat /proc/net/xt_recent/portscan | awk '{print $1}'

# Firewall-Regeln neu laden (nach Reboot passiert das automatisch)
/root/fw/fw_ipv4.sh && /root/fw/fw_ipv6.sh

Wichtige Sicherheitshinweise