Skip to main content

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.
This template deploys into an existing GVC. It does not create or manage one. Every resource lands in the GVC you install into. Use a GVC with one location and set 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

With 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 Nextcloud reveal on exactly those secrets.
1

Create the admin login secret

A dictionary secret with the keys username and password (10 or more characters) of the first administrator. It is read on the first boot only.
Set admin.secretName to this name.
2

Create the database credentials secret

A dictionary secret with username, password and database. The bundled PostgreSQL initializes with them and Nextcloud connects with them.
Set postgres.config.credentialsSecretName (default) or postgresHA.config.credentialsSecretName (HA) to this name.
3

Create the Redis password secret

A dictionary secret with the key password. Use a hex value: Nextcloud reads it through PHP settings, where some punctuation has a meaning.
Set redis.redis.auth.fromSecret.name to this name.
A missing prerequisite secret wedges the install silently. The install exits 0, every resource is created, and Nextcloud then waits. Because the container never ran, cpln logs returns nothing.The only place the missing secret is named is status.versions[].message:
It is get-deployments: plain cpln workload get has no versions key. If you create the secret after installing, force a redeployment of both Nextcloud workloads; they do not pick it up on their own:
S3 file storage and database backups (optional). A bucket for files is described under Storage Setup; backup buckets are described under Backing Up.

Installation

Install from the marketplace registry, naming your three secrets and the one location of your GVC:
Choose 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

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

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

The 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 for storage.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:
AWS S3 (keyless). Create the bucket and a Control Plane cloud account for the AWS account, then create this IAM policy (replace YOUR_BUCKET_NAME). Set storage.s3.cloudAccountName and storage.s3.policyName to the cloud account and the policy.
S3-compatible servers (MinIO and others). Create the bucket and a dictionary secret with accessKeyId and secretAccessKey, then set storage.s3.endpoint, storage.s3.usePathStyle: true and storage.s3.auth.secretName to the secret name:
The endpoint takes a scheme and host. For a server in the same GVC use its fully qualified internal name, for example http://WORKLOAD_NAME.GVC_NAME.cpln.local:9000. Static keys are written to config.php on the volume; keyless AWS writes none.

Connecting

Sign in with the admin login, then add users under Accounts. Desktop and mobile clients take the server address and sign in through the browser. For scripts and WebDAV mounts, create an app password under Personal settings → Security.

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:
Or sign in as an administrator, open Apps from the profile menu and install Calendar and Contacts there. Apps live on the shared volume, so every replica sees them.

Running occ

Run Nextcloud’s occ command as www-data (uid 33), the owner of config.php and the data directory, so anything it writes stays readable by Nextcloud:
The admin password in the secret is read on the first boot only. Change it in Personal settings, or reset a forgotten one (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.enabled or postgresHA.backup.enabled and 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. With storage.type: s3 they are in your bucket; back it up with your provider.
  • config/config.php holds the instance secret, passwordsalt and instanceid, which exist only on the volume. Copy it out after the first install; see Important Notes.
A database backup alone does not restore Nextcloud; it needs the saved config.php too.

Scaling and Availability

Set nextcloud.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 ... PASSWORD first (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 of RELEASE_NAME-redis. The old password stops working, browser users may need to sign in again, and sync clients and app passwords carry on.
After a database or Redis change, force a redeployment of both Nextcloud workloads:

Troubleshooting

A prerequisite secret is missing. Run cpln workload get-deployments RELEASE_NAME-nextcloud --gvc GVC_NAME -o yaml and read status.versions[].message. Create the secret and force a redeployment.
location is not a location of your GVC. Set location to a location the GVC already has.
With 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.
An 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.
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.php somewhere safe after the first install. It holds the instance secret, passwordsalt and instanceid, 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.type is local. Use storage.type: s3 for files that must outlive the release.
  • storage.type and storage.s3.bucket are 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 upgrade can briefly restart the single-instance PostgreSQL, and Nextcloud with it; use postgresHA when that matters.
  • A single upload request must finish within 600 seconds. Browser and desktop uploads are chunked; single curl or rclone PUTs 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 location to it.

External References

Nextcloud Administration Manual

Official administration documentation

occ Command Reference

Command-line administration of Nextcloud

Object Storage as Primary Storage

How Nextcloud stores files in S3

Nextcloud Clients

Desktop and mobile sync clients

Nextcloud Template

View the source files, default values, and chart definition