Skip to content
antalos

Nextcloud · Operate

This runbook deploys the service from apps/nextcloud/ and completes the configuration that Kubernetes cannot supply by itself. Start with the shared deployment workflow for repository rendering, credentials, and Argo CD ownership.

1. Prepare dependencies and inputs

  1. Prepare CNPG, OpenEBS, NFS CSI, Garage, Traefik, cert-manager, and the identity service. Set the Nextcloud and companion hostname/storage variables.

  2. Create the Garage bucket and permissions before first install; this is primary object storage, not an ordinary external-files mount. Prepare the app export for UID/GID 33.

  3. Reseal the main, companion, Context Chat, and Talk credentials. Preserve the original instance ID, secret, password salt, and storage credentials when recovering data.

  4. Follow the Nextcloud deployment details for app configuration and upgrade procedure for an existing installation.

2. Reconcile the application

Nextcloud add-on archives are selected by the release versions in apps/variables.yaml, without repository-pinned SHA-512 checksums. The installer records each installed version in a .APP_ID.gitops-version file beside the app directory and skips that version on later runs. Existing checksum markers are replaced on the first installation with this scheme, which downloads the configured releases again.

Publish the reviewed manifests and shared variables to the branch tracked by your Argo CD Applications. Local edits are not deployment inputs until that branch contains them. Let the root app-of-apps discover this service and retain its declared hook order; do not apply files containing unresolved variable placeholders directly.

From the repository root, inspect the Application and its namespace:

Inspect deployment state
/home/linuxbrew/.linuxbrew/bin/kubectl --kubeconfig kubeconfig \
  -n argocd get application nextcloud


/home/linuxbrew/.linuxbrew/bin/kubectl --kubeconfig kubeconfig \
  -n nextcloud get pods,svc,pvc

Wait for required controllers, database initialization, and migration Jobs before testing the user workflow. Synced configuration, ready workloads, and a successful user transaction are separate milestones.

3. Complete identity and first access

The repository installs user_oidc, but does not create its Authentik provider configuration for you. Add an OAuth2/OIDC provider in Authentik, bind the allowed group, and register the callback reported by the Nextcloud OIDC configuration. In Nextcloud administration, enter the client ID, client secret, discovery document, and stable user-ID mapping. Keep one working local administrator while verifying provisioning and existing-account linking. Do not assume that equal email addresses should merge accounts automatically.

4. Connect and operate the service

  1. Finish the office JWT, Whiteboard, Context Chat, and Talk setup described in the integration guide; several values are reapplied by startup hooks.

  2. Configure outbound mail, background-job scheduling, trusted domains/proxies, and allowed AI providers. Verify each feature with a non-admin account.

  3. Upload, share, sync, and download a file; edit a document with two users; test a Talk call across networks. Establish a coordinated database/object backup before inviting users.

Availability before maintenance

Partially HA overall: replicated web and many companions, with shared storage, session, Redis recovery, and upgrade limits.

Web, office, and Context Chat use zero-surge rolling updates. Redis HAProxy also uses zero surge and one unavailable, so replacements do not require a third anti-affined placement. Major Nextcloud upgrades still require the documented isolated maintenance and single-owner schema migration procedure.

Establish Redis election and safe rejoin behavior, protect shared storage, and exercise file/office/Talk workflows during degraded operation. A warm web replica does not make the whole Nextcloud suite outage-free.

Use the component-by-component failure contract before a node drain, database promotion, or upgrade. Restoring a healthy replica count must include data resynchronization and restored voting capacity, not just Running pods.

5. Maintain and recover

A recoverable Nextcloud installation needs the database, Garage objects, original secret/salt and credentials, Git configuration, and any NFS content that cannot be re-created. Pinned application code can be downloaded again, but Whiteboard recording files or manually installed extensions on shared storage need separate consideration. Redis locks and disposable pod files do not replace the data backup.

Before an upgrade, read the release notes for the pinned target and record a recovery point. A previous image tag is not a database rollback after a schema migration. Use routine operations and disaster recovery for the platform sequence.

Troubleshooting

For a 503 or incomplete rollout, separate database migration, app-code initialization, Redis discovery, and ingress failures. For missing files, verify database and object-store consistency before changing buckets. Read-only configuration requires the controlled maintenance procedure in the upgrade guide.

If /status.php succeeds but /login intermittently returns 500, inspect both nextcloud-redis-haproxy endpoints and Nextcloud Redis errors. A HAProxy pod can accept TCP connections while its redis-primary backend has no available server. The HAProxy health endpoint on port 8404 reports 503 in that state, so Kubernetes removes it from the Service. Liveness checks the proxy listener independently; an unavailable Redis primary must not trigger repeated proxy restarts. DNS resolvers refresh data-pod addresses after replacement. Confirm the login path after both proxies become ready.

Redis restart recovery

Redis starts from a writable redis.conf on its existing data PVC. Sentinel can therefore persist promotion and rejoin changes with CONFIG REWRITE. Data-side Sentinel configuration also lives on that PVC; the third voter uses an emptyDir and a stable identity. All three voters announce stable DNS names. Do not replace those files with ordinal-based defaults at each start.

When adopting this configuration, first establish one healthy writer and a synchronized replica; the initial configuration seeds ordinal 0 as primary. If neither instance is primary, compare replication IDs and offsets before selecting a recovery candidate. Never promote both. Inspect INFO replication, SENTINEL MASTER nextcloud, and SENTINEL CKQUORUM nextcloud on every voter. Stale Sentinel identities can prevent a majority even when two live voters communicate; reset stale topology only after identifying the correct writer. Wait for replica synchronization and test the login and Whiteboard paths separately from Argo health.

Manifest and upstream reference

Official Nextcloud documentation.