Configuration Reference¶

Complete reference for config.yaml configuration options.

config.yaml Structure¶

namespace: string             # Kubernetes namespace
domain: string                # Primary domain
versions:                     # Component versions
  nextcloud: string
  postgres: string
  redis: string
  collabora: string
  whiteboard: string
s3:                           # S3 object storage
  endpoint: string
  region: string
  buckets:
    data: string
    backups: string
storage:                      # Persistent storage
  storageClass: string
  postgresSize: string
  redisSize: string
resources:                    # Resource allocation
  nextcloud: ResourceSpec
  postgres: ResourceSpec
  redis: ResourceSpec
replicas:                     # Replica counts
  nextcloud: number
  postgres: number
  redis: number
collabora:                    # Collabora configuration
  enabled: boolean
  domain: string
  resources: ResourceSpec
whiteboard:                   # Whiteboard configuration
  enabled: boolean
  resources: ResourceSpec

Field Descriptions¶

namespace¶

Type: string Required: Yes Example: nextcloudkup

Kubernetes namespace for all resources. Must be DNS-compatible.

domain¶

Type: string Required: Yes Example: cloud.kup6s.com

Primary domain for Nextcloud. Used for:

Ingress hostname
TLS certificate
trusted_domains in config.php
WOPI server URL for Collabora

versions¶

versions.nextcloud¶

Type: string Required: Yes Example: "31.0.13"

Nextcloud Docker image tag from Docker Hub.

Version Compatibility:

Must match or be newer than database version
Downgrading not supported
Check upgrade path in Nextcloud docs

versions.postgres¶

Type: string Required: Yes Example: "16"

PostgreSQL major version. Used by CloudNativePG operator.

Supported Versions: 12, 13, 14, 15, 16

versions.redis¶

Type: string Required: Yes Example: "7.4"

Redis Docker image tag from Docker Hub.

versions.collabora¶

Type: string Required: No (if collabora.enabled: false) Example: "25.04.8.2.1"

Collabora Online Docker image tag from Docker Hub.

Finding Tags:

# List available tags
curl -s https://registry.hub.docker.com/v2/repositories/collabora/code/tags | jq -r '.results[].name' | head -20

versions.whiteboard¶

Type: string Required: No (if whiteboard.enabled: false) Example: "latest"

Whiteboard Docker image tag from GitHub Container Registry.

s3¶

s3.endpoint¶

Type: string Required: Yes Example: https://fsn1.your-objectstorage.com

S3-compatible endpoint URL. For Hetzner S3:

fsn1 (Falkenstein): https://fsn1.your-objectstorage.com
nbg1 (Nuremberg): https://nbg1.your-objectstorage.com
hel1 (Helsinki): https://hel1.your-objectstorage.com

s3.region¶

Type: string Required: Yes Example: fsn1

S3 region identifier. Must match endpoint location.

s3.buckets.data¶

Type: string Required: Yes Example: data-nextcloudkup-kup6s

S3 bucket name for user files. Created via Crossplane.

Naming Convention: data-{instance}-kup6s

s3.buckets.backups¶

Type: string Required: Yes Example: backups-nextcloudkup-kup6s

S3 bucket name for PostgreSQL backups. Created via Crossplane.

Naming Convention: backups-{instance}-kup6s

storage¶

storage.storageClass¶

Type: string Required: Yes Example: longhorn

Kubernetes StorageClass for persistent volumes.

Options:

longhorn - Replicated block storage (recommended)
hcloud-volumes - Hetzner Cloud Volumes
smb-csi - SMB/CIFS network storage (RWX support)

storage.postgresSize¶

Type: string Required: Yes Example: 10Gi

PVC size for each PostgreSQL replica.

Sizing Guidelines:

Small (< 10,000 files): 10Gi
Medium (10,000-100,000 files): 20Gi
Large (> 100,000 files): 50Gi

Growth Rate: ~30KB per file (metadata only)

storage.redisSize¶

Type: string Required: Yes Example: 5Gi

PVC size for Redis data (cache only).

Recommendation: 5Gi sufficient for most workloads.

resources¶

Resource specifications follow Kubernetes ResourceRequirements format:

resources:
  component:
    requests:
      cpu: string      # e.g., "200m" = 0.2 CPU cores
      memory: string   # e.g., "512Mi" = 512 MiB RAM
    limits:
      cpu: string
      memory: string

resources.nextcloud¶

Requests:

cpu: Minimum CPU guaranteed
memory: Minimum memory guaranteed

Limits:

cpu: Maximum CPU (throttled above)
memory: Maximum memory (OOMKilled above)

Sizing Guidelines:

Workload	CPU Request	Memory Request	CPU Limit	Memory Limit
Small (< 10 users)	200m	512Mi	1000m	2Gi
Medium (10-50 users)	500m	1Gi	2000m	4Gi
Large (> 50 users)	1000m	2Gi	4000m	8Gi

resources.postgres¶

Recommended:

requests:
  cpu: 100m
  memory: 256Mi
limits:
  cpu: 500m
  memory: 512Mi

PostgreSQL is generally I/O bound, not CPU bound.

resources.redis¶

Recommended:

requests:
  cpu: 50m
  memory: 128Mi
limits:
  cpu: 200m
  memory: 256Mi

Redis used only for caching (not persistent data).

replicas¶

replicas.nextcloud¶

Type: number Required: Yes Example: 1 or 3

Number of Nextcloud pod replicas.

Important: Multiple replicas require RWX storage for config/apps directory.

Current Limitation:

Longhorn: RWO only → Use replicas: 1
SMB CSI: RWX support → Can use replicas: 3

replicas.postgres¶

Type: number Required: Yes Example: 2

Number of PostgreSQL replicas in CNPG cluster.

Recommendations:

Production: 2 (primary + standby)
Development: 1 (no HA)

replicas.redis¶

Type: number Required: Yes Example: 1

Number of Redis replicas.

Recommendation: 1 (cache only, no HA needed)

collabora¶

collabora.enabled¶

Type: boolean Required: Yes Example: true

Enable Collabora Online for document editing.

collabora.domain¶

Type: string Required: If enabled: true Example: collabora.kup6s.com

Collabora Ingress hostname. Should be subdomain of main domain.

collabora.resources¶

Type: ResourceSpec Required: If enabled: true

Resource allocation for Collabora pods.

Recommended:

requests:
  cpu: 100m
  memory: 512Mi
limits:
  cpu: 1000m
  memory: 1Gi

whiteboard¶

whiteboard.enabled¶

Type: boolean Required: Yes Example: true

Enable Nextcloud Whiteboard app.

whiteboard.resources¶

Type: ResourceSpec Required: If enabled: true

Resource allocation for Whiteboard pod.

Recommended:

requests:
  cpu: 50m
  memory: 256Mi
limits:
  cpu: 500m
  memory: 512Mi

Example Configurations¶

Production (Multi-User)¶

namespace: nextcloudprod
domain: cloud.example.com

versions:
  nextcloud: "31.0.13"
  postgres: "16"
  redis: "7.4"
  collabora: "25.04.8.2.1"
  whiteboard: "latest"

s3:
  endpoint: https://fsn1.your-objectstorage.com
  region: fsn1
  buckets:
    data: data-nextcloudprod-kup6s
    backups: backups-nextcloudprod-kup6s

storage:
  storageClass: longhorn
  postgresSize: 20Gi
  redisSize: 5Gi

resources:
  nextcloud:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: 2000m
      memory: 4Gi
  postgres:
    requests:
      cpu: 200m
      memory: 512Mi
    limits:
      cpu: 1000m
      memory: 1Gi
  redis:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: 500m
      memory: 512Mi

replicas:
  nextcloud: 1  # RWO limitation
  postgres: 2
  redis: 1

collabora:
  enabled: true
  domain: collabora.example.com
  resources:
    requests:
      cpu: 100m
      memory: 512Mi
    limits:
      cpu: 1000m
      memory: 1Gi

whiteboard:
  enabled: true
  resources:
    requests:
      cpu: 50m
      memory: 256Mi
    limits:
      cpu: 500m
      memory: 512Mi

Development (Single User)¶

namespace: nextclouddev
domain: dev.kup6s.com

versions:
  nextcloud: "31.0.13"
  postgres: "16"
  redis: "7.4"
  collabora: "25.04.8.2.1"
  whiteboard: "latest"

s3:
  endpoint: https://fsn1.your-objectstorage.com
  region: fsn1
  buckets:
    data: data-nextclouddev-kup6s
    backups: backups-nextclouddev-kup6s

storage:
  storageClass: longhorn
  postgresSize: 10Gi
  redisSize: 5Gi

resources:
  nextcloud:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: 500m
      memory: 1Gi
  postgres:
    requests:
      cpu: 50m
      memory: 128Mi
    limits:
      cpu: 200m
      memory: 256Mi
  redis:
    requests:
      cpu: 25m
      memory: 64Mi
    limits:
      cpu: 100m
      memory: 128Mi

replicas:
  nextcloud: 1
  postgres: 1  # No HA in dev
  redis: 1

collabora:
  enabled: false  # Disable for dev

whiteboard:
  enabled: false  # Disable for dev

Validation¶

Check Configuration¶

# Validate YAML syntax
yamllint config.yaml

# Check for required fields
yq eval '.namespace, .domain, .versions.nextcloud' config.yaml

Test Manifest Generation¶

# Generate manifests
npm run synth

# Validate Kubernetes resources
kubectl apply --dry-run=client -f manifests/*.k8s.yaml

# Check for common issues
kubectl apply --dry-run=server -f manifests/*.k8s.yaml

Configuration Reference¶

config.yaml Structure¶

Field Descriptions¶

namespace¶

domain¶

versions¶

versions.nextcloud¶

versions.postgres¶

versions.redis¶

versions.collabora¶

versions.whiteboard¶

s3¶

s3.endpoint¶

s3.region¶

s3.buckets.data¶

s3.buckets.backups¶

storage¶

storage.storageClass¶

storage.postgresSize¶

storage.redisSize¶

resources¶

resources.nextcloud¶

resources.postgres¶

resources.redis¶

replicas¶

replicas.nextcloud¶

replicas.postgres¶

replicas.redis¶

collabora¶

collabora.enabled¶

collabora.domain¶

collabora.resources¶

whiteboard¶

whiteboard.enabled¶

whiteboard.resources¶

Example Configurations¶

Production (Multi-User)¶

Development (Single User)¶

Validation¶

Check Configuration¶

Test Manifest Generation¶

Related Documentation¶