Overview
Nextcloud is a self-hosted file sync and sharing platform. It gives your team a web UI, desktop and mobile sync clients, public share links, and calendars and contacts over CalDAV and CardDAV, with every file mountable as a WebDAV drive. This template runs Nextcloud with a background-jobs worker, a bundled PostgreSQL (single-instance by default, highly available behind one flag) and a bundled Redis, with files on a shared volume or in an S3 bucket. Nextcloud Server is licensed AGPL-3.0 and this is the free community edition. Above 500 users, Nextcloud’s free push service for the mobile apps stops delivering notifications and the web UI shows a community-release notice.location to it. The bundled PostgreSQL and Redis start in every location the GVC has; if location is not a location of your GVC, Nextcloud starts nothing.What Gets Created
postgresHA.enabled: true the HA workloads also get their own volume sets, identities and policies. With storage.type: s3 and AWS the Nextcloud identity is linked to your cloud account.
Prerequisites
Three dictionary secrets must exist before you install, in a GVC with one location. The template creates none of them; it references yours by name and grants Nextcloudreveal on exactly those secrets.
Create the admin login secret
username and password (10 or more characters) of the first administrator. It is read on the first boot only.admin.secretName to this name.Create the database credentials secret
username, password and database. The bundled PostgreSQL initializes with them and Nextcloud connects with them.postgres.config.credentialsSecretName (default) or postgresHA.config.credentialsSecretName (HA) to this name.Create the Redis password secret
password. Use a hex value: Nextcloud reads it through PHP settings, where some punctuation has a meaning.redis.redis.auth.fromSecret.name to this name.Installation
Install from the marketplace registry, naming your three secrets and the one location of your GVC:storage.type now: it cannot be changed after install. For the highly available database set postgres.enabled=false, postgresHA.enabled=true and postgresHA.config.credentialsSecretName instead of the postgres one.
To install using another method, follow the instructions for your preferred tool:
UI
CLI
Terraform
Pulumi
Configuration
Location and Nextcloud
Background Jobs
Admin Account and Volume
File Storage
storage.type: local keeps every file on the shared volume. storage.type: s3 keeps files in your bucket as objects named urn:oid:<id>, so the bucket is not browsable as a folder tree. See Storage Setup for the bucket and credentials.
Access
PostgreSQL
Highly Available PostgreSQL
Redis
backup blocks pass straight through to the postgres and postgres-highly-available templates; their pages carry the bucket, cloud account and IAM policy setup.
Storage Setup
Only forstorage.type: s3. If Nextcloud cannot write to the bucket (a policy without s3:PutObject, a wrong key or a wrong endpoint), the first boot exits and restarts and Nextcloud never becomes reachable. The reason is in the logs:
YOUR_BUCKET_NAME). Set storage.s3.cloudAccountName and storage.s3.policyName to the cloud account and the policy.
accessKeyId and secretAccessKey, then set storage.s3.endpoint, storage.s3.usePathStyle: true and storage.s3.auth.secretName to the secret name:
http://WORKLOAD_NAME.GVC_NAME.cpln.local:9000. Static keys are written to config.php on the volume; keyless AWS writes none.
Connecting
Calendar and Contacts
CalDAV and CardDAV work out of the box, so calendar and contact clients connect to the.well-known URLs above. The Calendar and Contacts web apps are not installed by default: /apps/calendar/ and /apps/contacts/ return 404 until you install them. Install them with occ, one app per command:
Running occ
Run Nextcloud’socc command as www-data (uid 33), the owner of config.php and the data directory, so anything it writes stays readable by Nextcloud:
read keeps it out of your shell history):
Operations
Backing Up
Three things make up an instance, and they are backed up separately:- The database holds users, shares, calendars, contacts and the file index. Turn on
postgres.backup.enabledorpostgresHA.backup.enabledand follow the bucket and cloud account setup on the postgres or postgres-highly-available page. - Files are on the volume with
storage.type: local, which is not snapshotted. Withstorage.type: s3they are in your bucket; back it up with your provider. config/config.phpholds the instancesecret,passwordsaltandinstanceid, which exist only on the volume. Copy it out after the first install; see Important Notes.
config.php too.
Scaling and Availability
Setnextcloud.replicas to 2 or more (up to 10) for more capacity and rolling restarts without downtime; this requires redis.enabled: true. Set postgresHA.enabled: true (and postgres.enabled: false) for a database that survives restarts and failover. Both together give near-zero-downtime restarts. Only one replica installs or upgrades Nextcloud at a time, and Nextcloud version upgrades always take it offline for a few minutes.
Rotating Secrets
Each secret rotates differently:- Admin: the secret is read on the first boot only. Reset the password as shown under Running occ.
- Database: run
ALTER ROLE ... PASSWORDfirst (in HA mode follow the postgres-highly-available rotation steps), then update the secret. - Redis: update the value with
cpln secret edit REDIS_SECRET_NAME, then force a redeployment ofRELEASE_NAME-redis. The old password stops working, browser users may need to sign in again, and sync clients and app passwords carry on.
Troubleshooting
No logs and the deployment never becomes ready
No logs and the deployment never becomes ready
cpln workload get-deployments RELEASE_NAME-nextcloud --gvc GVC_NAME -o yaml and read status.versions[].message. Create the secret and force a redeployment.Deployment reports deactivated because maxScale is set to 0
Deployment reports deactivated because maxScale is set to 0
location is not a location of your GVC. Set location to a location the GVC already has.First boot restarts in a loop with AccessDenied or SignatureDoesNotMatch
First boot restarts in a loop with AccessDenied or SignatureDoesNotMatch
storage.type: s3, Nextcloud cannot write to the bucket. AccessDenied on s3:PutObject means the IAM policy lacks it; SignatureDoesNotMatch means the keys or endpoint are wrong. Read the cause with cpln logs, fix the policy or the secret, and redeploy.HTTP 503 after an upgrade
HTTP 503 after an upgrade
occ upgrade was cut short and maintenance mode is still on. The next start resumes the upgrade. If the 503 lingers, run occ maintenance:mode --off as shown under Running occ.New replicas stop at boot after a storage change
New replicas stop at boot after a storage change
storage.type and storage.s3.bucket are fixed at install; a changed value stops new replicas while the old ones keep serving. Restore the original values.Important Notes
- Copy
config/config.phpsomewhere safe after the first install. It holds the instancesecret,passwordsaltandinstanceid, which are on the volume only: a database backup cannot fully restore Nextcloud without them. It also holds the Redis password (and S3 keys, if set), so store it as a secret:cpln workload exec RELEASE_NAME-nextcloud --gvc GVC_NAME --container nextcloud -- cat /srv/nextcloud/config/config.php > config.php. The database password is never written to it. - The volume is not snapshotted and is deleted on uninstall, with every file when
storage.typeislocal. Usestorage.type: s3for files that must outlive the release. storage.typeandstorage.s3.bucketare fixed at install. Nextcloud cannot move files between them.- Upgrade Nextcloud one major version at a time and never downgrade. Upgrades run in maintenance mode (HTTP 503) for a few minutes, and the first
helm upgradecan briefly restart the single-instance PostgreSQL, and Nextcloud with it; usepostgresHAwhen that matters. - A single upload request must finish within 600 seconds. Browser and desktop uploads are chunked; single
curlorrclonePUTs are not. - Nextcloud’s log goes to stderr: read it with
cpln logs; the Logging app’s log viewer is empty. - Install into a GVC with one location and set
locationto it.