Skip to content

nextcloud Runbook

Metadata

Field Value
Service nextcloud
Criticality Tier 2
Owner Application / platform owner
Namespace nextcloud
Clusters dev, local
Last validated 2026-08-17
Related service page ../services/nextcloud.md

Trigger Conditions

  • Web UI or sync clients fail.
  • File uploads or locking fail.
  • MySQL or Redis is unhealthy.
  • PVC-backed storage is unavailable.
  • AppAPI or Context Agent failures affect the MCP path while core Nextcloud remains healthy; use the linked AppAPI runbook for that isolated component.

1. Health Checks

kubectl -n nextcloud get pods,svc,pvc,ingressroute
kubectl -n nextcloud logs deploy/nextcloud --tail=200
kubectl -n nextcloud get deploy,statefulset
kubectl -n nextcloud-exapps get deploy,pod,svc,pvc

2. Troubleshooting Workflows

Check app, DB, cache, and storage together:

kubectl -n nextcloud logs deploy/nextcloud --tail=400
kubectl -n nextcloud logs statefulset/mysql --tail=100
kubectl -n nextcloud logs deploy/redis --tail=100

Look for trusted-domain drift, DB migrations, Redis lock issues, and PVC attach failures.

For AppAPI daemon, HaRP RBAC, generated ExApp, or MCP failures, follow the nextcloud-appapi runbook. Do not broaden the core Nextcloud ServiceAccount or hand-edit AppAPI-generated Deployments.

3. Disaster Recovery

  1. Restore MySQL state.
  2. Restore file data from snapshot.
  3. Restore application secrets.
  4. Reconcile the active overlay.
  5. Validate web access and a sync-client login.

4. Scaling and Resource Management

kubectl -n nextcloud top pod

Increase application, DB, or cache resources in Git when uploads, previews, or background jobs saturate the current allocation.

5. Maintenance Procedures

  • Rotate DB and SMTP credentials.
  • Review trusted domains after hostname changes.
  • Plan upgrades during low-traffic windows because migrations can be slow.
  • Check AppAPI and Context Agent compatibility as a separate application change before a Nextcloud major-version upgrade.

6. Rollback Strategy

  • Revert the active overlay revision.
  • Restore the previous DB and file snapshot if schema or config changes broke startup.

7. Post-Incident Actions

  1. Add a changelog fragment for manual interventions.
  2. Update the service page if dependencies or hostnames changed.
  3. Extend this runbook with any newly observed operational issue.