Nextcloud - Family Cloud¶

Nextcloud is deployed as the primary file storage and collaboration platform for the homelab, running on a dedicated worker node with 3TB of storage.

Overview¶

Property	Value
URL	cloud.ajandrews.pro
Node	k8s-worker-5 (dedicated)
Storage	3TB Longhorn HA volume
Database	MariaDB 11.2
Cache	Redis 7 Alpine
Image	nextcloud:30-apache

Architecture¶

graph TB
    subgraph Internet
        CF[Cloudflare Tunnel]
    end

    subgraph "k8s-worker-5 (Dedicated)"
        NC[Nextcloud Pod]
        EXP[Nextcloud Exporter]
        DB[(MariaDB)]
        REDIS[(Redis)]
        PVC[3TB Longhorn PVC]
    end

    subgraph Monitoring
        PROM[Prometheus]
        GRAF[Grafana]
    end

    CF -->|cloud.ajandrews.pro| NC
    NC --> DB
    NC --> REDIS
    NC --> PVC
    NC --> EXP
    EXP -->|:9205/metrics| PROM
    PROM --> GRAF

Node Configuration¶

The dedicated node is labeled and tainted to ensure only Nextcloud workloads run on it:

# Label for identification
kubectl label node k8s-worker-5 dedicated=nextcloud

# Taint to prevent other workloads
kubectl taint nodes k8s-worker-5 dedicated=nextcloud:NoSchedule

All Nextcloud pods include tolerations to run on this tainted node:

spec:
  tolerations:
  - key: "dedicated"
    operator: "Equal"
    value: "nextcloud"
    effect: "NoSchedule"
  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
        - matchExpressions:
          - key: dedicated
            operator: In
            values:
            - nextcloud

Email Configuration¶

Nextcloud uses Microsoft Graph API OAuth2 for sending emails (password resets, notifications, sharing).

Graph OAuth2 SMTP Relay¶

Instead of traditional SMTP authentication, we use a dedicated relay service that authenticates via Microsoft Graph API client credentials flow.

graph LR
    NC[Nextcloud] -->|SMTP :25| RELAY[Graph SMTP Relay]
    RELAY -->|OAuth2| GRAPH[Microsoft Graph API]
    GRAPH -->|Send| M365[Microsoft 365]
    M365 -->|Email| USER[Recipients]

Benefits:

No need for app passwords
Works with MFA-enabled accounts
OAuth2 token auto-refresh
Secure client credentials flow

See Operations > Email Relay for detailed configuration.

Monitoring¶

Prometheus Metrics¶

The nextcloud-exporter sidecar exposes metrics on port 9205:

nextcloud_users_total - Total registered users
nextcloud_files_total - Total files stored
nextcloud_shares_total - Total shares created
nextcloud_active_users_total - Users active in last 5 minutes
nextcloud_free_space_bytes - Available storage space
nextcloud_apps_installed_total - Number of installed apps

ServiceMonitor¶

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: nextcloud
  namespace: nextcloud
  labels:
    app: nextcloud
    release: prometheus  # Required for Prometheus discovery
spec:
  selector:
    matchLabels:
      app: nextcloud
  endpoints:
  - port: metrics
    interval: 60s
    path: /metrics
  namespaceSelector:
    matchNames:
    - nextcloud

Grafana Dashboard¶

A custom Grafana dashboard is provisioned via ConfigMap with the grafana_dashboard: "1" label, showing:

Total Users / Active Users
Total Files / Total Shares
Storage Usage / Free Space
Nextcloud Status (UP/DOWN)
Installed Apps count
Users Over Time graph
Free Space Over Time graph

Background Jobs¶

A Kubernetes CronJob runs Nextcloud's background tasks every 5 minutes:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: nextcloud-cron
  namespace: nextcloud
spec:
  schedule: "*/5 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: cron
            image: nextcloud:30-apache
            command:
            - /bin/sh
            - -c
            - php /var/www/html/cron.php

Storage¶

Persistent Volume Claims¶

PVC	Size	StorageClass	Purpose
nextcloud-data	3TB	longhorn-ha	User files, app data
nextcloud-db	50Gi	longhorn-ha	MariaDB database
nextcloud-redis	1Gi	longhorn	Redis session cache

Longhorn Backup¶

Longhorn provides:

Automatic snapshots
Cross-node replication (HA)
S3-compatible backup support

User Management¶

User registration is admin-controlled:

Admin creates user account in Nextcloud
User receives email notification with password reset link
User sets their own password and logs in

Demo Access:

Username: DemoUser
Password: DemoUser

Deployed Resources¶

Resource	Name	Namespace
Deployment	nextcloud	nextcloud
StatefulSet	nextcloud-mariadb	nextcloud
Deployment	nextcloud-redis	nextcloud
CronJob	nextcloud-cron	nextcloud
Service	nextcloud	nextcloud
Service	nextcloud-db	nextcloud
ServiceMonitor	nextcloud	nextcloud
ConfigMap	nextcloud-dashboard	monitoring
PVC	nextcloud-data	nextcloud
PVC	nextcloud-db	nextcloud
Secret	nextcloud-secrets	nextcloud

Troubleshooting¶

Check Pod Status¶

kubectl get pods -n nextcloud
kubectl describe pod -n nextcloud nextcloud-xxx

Check Logs¶

kubectl logs -n nextcloud deployment/nextcloud -c nextcloud
kubectl logs -n nextcloud deployment/nextcloud -c nextcloud-exporter

Test Email¶

kubectl exec -n nextcloud deployment/nextcloud -- \
  php /var/www/html/occ mail:test [email protected]

Check Metrics¶

kubectl port-forward -n nextcloud svc/nextcloud 9205:9205
curl http://localhost:9205/metrics

Run occ Commands¶

kubectl exec -n nextcloud deployment/nextcloud -- \
  php /var/www/html/occ status

Repository¶

Source: github.com/AjAndrews51/nextcloud

Managed via ArgoCD with automatic sync enabled.