Quick Start¶

Goal: go from zero to a browser-accessible Nextcloud with a managed PostgreSQL database in roughly 10 minutes.

This is the golden path — one NextcloudInstance, one ingress host, one admin login. For multi-tenant onboarding with pre-provisioned pools, see Pool Provisioning after completing this page.

Prerequisites¶

You need a cluster with the following already installed and working. If something is missing, fix that first — the operator assumes these primitives exist.

Requirement	Why	Check
Kubernetes 1.24+	CRD + status subresource support	`kubectl version`
Flux CD v2	Operator creates `HelmRelease` resources; Flux applies them	`flux check`
Ingress controller (NGINX, Traefik, etc.)	External access to the Nextcloud URL	`kubectl get ingressclass`
Default `StorageClass`	PVCs for Nextcloud data and the managed DB	`kubectl get sc`
Percona PG Operator	Required for `database.managed: true`	`kubectl get crd perconapgclusters.pgv2.percona.com`
A DNS name that resolves to your ingress	So you can open the URL at the end	`dig nextcloud.example.com`

The Installation page covers installing the operator itself and the Percona PG Operator.

Step 1 — Create a namespace¶

kubectl create namespace nextcloud-demo

Step 2 — Apply a minimal NextcloudInstance¶

Save as nextcloud-demo.yaml, replacing nextcloud.example.com with your real DNS name and choosing a strong admin password:

apiVersion: k8s.bnerd.com/v1alpha1
kind: NextcloudInstance
metadata:
  name: demo
  namespace: nextcloud-demo
spec:
  profile: production
  ingress:
    host: nextcloud.example.com
    tls:
      enabled: true
  database:
    managed: true
    type: postgresql
  admin:
    username: admin
    password: change-me-to-something-strong

Apply it:

kubectl apply -f nextcloud-demo.yaml

Step 3 — Watch the instance come up¶

kubectl get nci demo -n nextcloud-demo -w

You will see the PHASE column move through Pending → Creating → Ready. The first time takes roughly 2–3 minutes because the managed PostgreSQL cluster has to provision first.

If it gets stuck for more than 5 minutes, stop watching and read the troubleshooting tips below.

Step 4 — Verify everything deployed¶

Press Ctrl+C to exit the watch, then:

# Instance status
kubectl describe nci demo -n nextcloud-demo

# Underlying Flux HelmRelease
kubectl get helmrelease -n nextcloud-demo

# Pods should all be Running
kubectl get pods -n nextcloud-demo

# Managed database cluster (if database.managed: true)
kubectl get perconapgcluster -n nextcloud-demo

The instance status should show phase: Ready and the HelmRelease should show Ready=True.

Step 5 — Open Nextcloud and log in¶

Open your browser to https://nextcloud.example.com (or whatever host you set). Log in with:

Username: admin
Password: what you set in spec.admin.password

You should land on the Nextcloud dashboard. That is the golden path completed.

Step 6 — Clean up (optional)¶

When you're done experimenting:

kubectl delete namespace nextcloud-demo

PVCs are retained by default

Deleting a NextcloudInstance removes the HelmRelease and its managed resources but keeps PersistentVolumeClaims so data survives a redeploy. To remove everything including data, delete the whole namespace as shown above.

Troubleshooting this page¶

If the instance stays in Pending or Creating:

# Operator logs — the single best diagnostic
kubectl logs -n nextcloud-operator-system -l app.kubernetes.io/name=nextcloud-operator --tail=200

# Events on the instance itself
kubectl describe nci demo -n nextcloud-demo

# HelmRelease status
kubectl describe helmrelease -n nextcloud-demo

Common causes:

Percona PG Operator not installed — database.managed: true needs it. Install it or switch to an external database.
No ingress controller — the Helm release will still go Ready but the URL won't resolve. Install NGINX or Traefik.
No default StorageClass — PVCs will be Pending. Set a default with kubectl patch sc ... -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'.
TLS cert not ready — if you enabled TLS, check cert-manager logs; the rest of the instance will be fine, just the TLS handshake won't work yet.

For a deeper reference see the Troubleshooting guide.

What's next¶

You have a working single-instance deployment. From here:

Multiple tenants or customers? → Pool Provisioning maintains pre-warmed instances for ~30s assignment.
External secrets / Vault? → Secret Management explains the credentialsSecret pattern.
Custom configuration? → Configuration Profiles shows the 4-layer override cascade.
Version upgrades? → Version Management covers the spec.version → chart version resolution.
Monitoring? → Monitoring enables the Prometheus ServiceMonitor and Grafana dashboard.
Running occ commands? → Running occ Commands uses NextcloudCommand for kubectl-native execution.