Skip to content

nextcloud

Metadata

Field Value
Service nextcloud
Purpose Self-hosted collaboration, file sync, and cloud storage service
Criticality Tier 2
Owner Application / platform owner
Clusters dev, local
Namespace nextcloud
Exposure internet
Stateful yes
Backup class app-native
RPO / RTO Daily backup target, 4 to 8 hours to restore
Last reviewed 2026-08-17

1. Service Overview

Nextcloud provides user-facing file synchronization and collaboration workflows backed by MySQL, Redis, and multiple persistent volumes.

Summary

If it fails, file access and collaboration stop and user data is at risk until application, DB, and storage are recovered.

Dependencies

Dependency Type Why it matters
MySQL database Stores primary application state
Redis cache / locking Required for performant and safe file operations
Traefik and Authelia ingress and auth Public HTTPS path and access control
AppAPI HaRP optional ExApp runtime Proxies and operates Kubernetes-native ExApps such as Context Agent

2. Architecture Diagram

[Browser / sync client]
  -> [Traefik]
  -> [Nextcloud]
  -> [MySQL]
  -> [Redis]
  -> [PVC-backed application storage]

[Nextcloud AppAPI]
  -> [HaRP ClusterIP in nextcloud-exapps]
  -> [Context Agent ExApp]

3. Deployment Specifications

Item Value
Source path nextcloud/base and nextcloud/overlays/*
Deployment model Kustomize plus Fleet bundle
Namespace nextcloud
Workload kind Deployment plus database and cache workloads
Chart or image version See base manifests for current image tags
Config files base/kustomization.yaml, overlays/dev, overlays/local, fleet.yaml

The companion nextcloud-appapi/ deployment unit is separately reconciled on the local cluster. This keeps its ServiceAccount and generated ExApps out of the core nextcloud namespace and avoids granting the Nextcloud pod Kubernetes API access.

Cluster mapping

Cluster Overlay path Notes
dev nextcloud/overlays/dev Development deployment
local nextcloud/overlays/local Main local-cluster deployment

4. Configuration Guide

Environment variables

Variable Source Purpose Secret?
Nextcloud runtime settings overlay env files, Secrets, and manifests Application bootstrap, DB, cache, and SMTP settings mixed

ConfigMaps

Resource Path Purpose
Nextcloud runtime config nextcloud/base and nextcloud/overlays/* Configures trusted domains and environment-specific behavior

Secrets management

  • Secret names: app secrets, DB credentials, cache credentials, and SMTP credentials in the nextcloud namespace
  • Source of truth: overlay secret inputs and generated manifests
  • Rotation trigger: credential updates or security response
  • Recovery note: restore all required secrets before restarting the app

5. Access Protocols

Path URL or endpoint Audience Auth TLS terminates at
Internal Nextcloud service in the nextcloud namespace Cluster workloads namespace RBAC Traefik / Nextcloud
External https://cloud.mutana.fr End users Nextcloud auth plus optional Authelia controls Traefik
Context Agent MCP https://cloud.mutana.fr/index.php/apps/app_api/proxy/context_agent/mcp/ Nextcloud users and restricted agents Nextcloud app-password bearer token Traefik

6. Operations and Observability

  • Primary health indicators: app pod healthy, MySQL and Redis healthy, and external file access working.
  • Dashboards or alerts: shared cluster monitoring and PVC health.
  • Log locations: Nextcloud app logs, MySQL logs, and Redis logs.
  • Known failure modes: DB migrations, lock/cache issues, PVC attach failure, or ingress problems.
  • AppAPI/Context Agent operations and recovery are documented in the nextcloud-appapi runbook.

7. Backup and Recovery Notes

  • Backup method: database backup plus file-data snapshot and secret backup.
  • Restore prerequisites: restored DB, restored data volume, and runtime secrets.
  • Related runbook: ../runbooks/nextcloud.md

8. Release and Change Notes

  • Current deployed app version: see nextcloud/base image tags.
  • Current chart version: N/A.
  • Last significant change: added the isolated Kubernetes-native AppAPI/HaRP companion and Context Agent MCP path without modifying the core Nextcloud workload or public exposure.
  • Rollback reference: previous overlay revision in Git.