@r8s/nextcloud 0.2.0

package/__tests__/nextcloud.test.ts

@@ -0,0 +1,409 @@
+import { describe, it, expect } from 'vitest'
+import { render, jsx } from '@r8s/core'
+import { OperatorContext, SecretContext, RoutingContext } from '@r8s/core/defaults'
+import { runGuardrails, noPlaintextSecrets, validateResource } from '@r8s/core'
+import { operators } from '@r8s/crds'
+import type { r8sElement } from '@r8s/core'
+
+// Nextcloud recipe tests:
+//   1. Operator declarations (deduped via OperatorContext)
+//   2. Rendering: defaults, all props, gateway/ingress adaptation, cron
+//   3. Persistence: /var/www/html claim shared by app + cron
+//   4. Security: no plaintext credentials in rendered output
+import { Nextcloud } from '../src/index'
+
+const openbao = { backend: 'openbao', mount: 'kv', path: 'test' }
+
+/** Render Nextcloud inside a Platform-like secrets backend (OpenBao). */
+function renderNextcloud(props: Record<string, unknown>): ReturnType<typeof render> {
+  return render(
+    jsx(SecretContext.Provider, {
+      value: openbao as never,
+      children: jsx(Nextcloud, props as never),
+    })
+  )
+}
+
+/** Wrap Nextcloud in an OperatorContext (no secrets backend). */
+function elementWithContext(ops: any[], props: Record<string, unknown>): r8sElement {
+  return jsx(OperatorContext.Provider, {
+    value: ops,
+    children: jsx(Nextcloud, props as never),
+  })
+}
+
+const objectStorage = {
+  endpoint: 's3.internal.example.com',
+  bucket: 'cloud-files',
+  credentialsSecret: 'cloud-files-credentials',
+}
+
+function findAppDeployment(result: ReturnType<typeof render>, name = 'nextcloud'): any {
+  return result.resources.find(
+    (r: any) => r.kind === 'Deployment' && r.metadata.name === name
+  ) as any
+}
+
+function findCron(result: ReturnType<typeof render>, name = 'nextcloud-cron'): any {
+  return result.resources.find((r: any) => r.kind === 'CronJob' && r.metadata.name === name) as any
+}
+
+describe('operator declarations', () => {
+  it('declares the redis operator when cache is enabled', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com' })
+    expect(result.operators.some((op) => op.name === 'redis-operator')).toBe(true)
+  })
+
+  it('declares the cnpg operator via the Database recipe', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com' })
+    expect(result.operators.some((op) => op.name === 'cnpg')).toBe(true)
+  })
+
+  it('skips the redis operator when cache is disabled', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com', cache: false })
+    expect(result.operators.some((op) => op.name === 'redis-operator')).toBe(false)
+  })
+
+  it('deduplicates operators provided via context', () => {
+    const result = render(
+      elementWithContext([operators['redis-operator'](), operators['cnpg']()], {
+        host: 'cloud.example.com',
+        secretsName: 'existing-secrets',
+      })
+    )
+    const names = result.operators.map((op) => op.name)
+    expect(names.filter((n) => n === 'redis-operator')).toHaveLength(1)
+    expect(names.filter((n) => n === 'cnpg')).toHaveLength(1)
+  })
+})
+
+describe('rendering defaults', () => {
+  it('renders app deployment, service, ingress, database cluster, cron job, redis and html claim', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com' })
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('Deployment')
+    expect(kinds).toContain('Service')
+    expect(kinds).toContain('Ingress')
+    expect(kinds).toContain('Cluster')
+    expect(kinds).toContain('CronJob')
+    expect(kinds).toContain('RedisReplication')
+    expect(kinds).toContain('PersistentVolumeClaim')
+  })
+
+  it('renders the app on nextcloud:31-apache, port 80, as a raw deployment', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com' })
+    const app = findAppDeployment(result)
+    expect(app).toBeDefined()
+    const container = app.spec.template.spec.containers[0]
+    expect(container.image).toBe('nextcloud:31-apache')
+    expect(container.ports[0].containerPort).toBe(80)
+    expect(container.name).toBe('app')
+  })
+
+  it('probes /status.php on port 80 for liveness and readiness', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com' })
+    const container = findAppDeployment(result).spec.template.spec.containers[0]
+    expect(container.livenessProbe.httpGet).toEqual({ path: '/status.php', port: 80 })
+    expect(container.livenessProbe.initialDelaySeconds).toBe(30)
+    expect(container.readinessProbe.httpGet).toEqual({ path: '/status.php', port: 80 })
+    expect(container.readinessProbe.initialDelaySeconds).toBe(20)
+    expect(container.readinessProbe.failureThreshold).toBe(5)
+  })
+
+  it('runs cron.php every 5 minutes with the same image, no busybox', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com' })
+    const cron = findCron(result)
+    expect(cron).toBeDefined()
+    expect(cron.apiVersion).toBe('batch/v1')
+    expect(cron.spec.schedule).toBe('*/5 * * * *')
+    const container = cron.spec.jobTemplate.spec.template.spec.containers[0]
+    expect(container.image).toBe('nextcloud:31-apache')
+    expect(container.command).toEqual(['php', '-f', '/var/www/html/cron.php'])
+    expect(container.env.find((e: any) => e.name === 'POSTGRES_HOST').value).toBe('nextcloud-rw')
+    expect(container.env.find((e: any) => e.name === 'POSTGRES_USER').value).toBe('nextcloud')
+  })
+
+  it('renders a ReadWriteMany html claim with the default 10Gi size', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com' })
+    const pvc = result.resources.find(
+      (r: any) => r.kind === 'PersistentVolumeClaim' && r.metadata.name === 'nextcloud-html'
+    ) as any
+    expect(pvc).toBeDefined()
+    expect(pvc.spec.accessModes).toEqual(['ReadWriteMany'])
+    expect(pvc.spec.resources.requests.storage).toBe('10Gi')
+    expect(pvc.spec.storageClassName).toBeUndefined()
+  })
+
+  it('honours storage and storageClassName props on the html claim', () => {
+    const result = renderNextcloud({
+      host: 'cloud.example.com',
+      storage: '25Gi',
+      storageClassName: 'nfs-client',
+    })
+    const pvc = result.resources.find(
+      (r: any) => r.kind === 'PersistentVolumeClaim' && r.metadata.name === 'nextcloud-html'
+    ) as any
+    expect(pvc.spec.resources.requests.storage).toBe('25Gi')
+    expect(pvc.spec.storageClassName).toBe('nfs-client')
+  })
+
+  it('mounts the html claim in both the app deployment and the cron job', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com' })
+    const appContainer = findAppDeployment(result).spec.template.spec.containers[0]
+    expect(appContainer.volumeMounts).toEqual([{ name: 'html', mountPath: '/var/www/html' }])
+    expect(findAppDeployment(result).spec.template.spec.volumes).toEqual([
+      { name: 'html', persistentVolumeClaim: { claimName: 'nextcloud-html' } },
+    ])
+    const cronPodSpec = findCron(result).spec.jobTemplate.spec.template.spec
+    expect(cronPodSpec.containers[0].volumeMounts).toEqual([
+      { name: 'html', mountPath: '/var/www/html' },
+    ])
+    expect(cronPodSpec.volumes).toEqual([
+      { name: 'html', persistentVolumeClaim: { claimName: 'nextcloud-html' } },
+    ])
+  })
+
+  it('forbids cron concurrency and never restarts jobs past the backoff limit', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com' })
+    const cron = findCron(result)
+    expect(cron.spec.concurrencyPolicy).toBe('Forbid')
+    const jobSpec = cron.spec.jobTemplate.spec
+    expect(jobSpec.backoffLimit).toBe(2)
+    expect(jobSpec.template.spec.restartPolicy).toBe('OnFailure')
+  })
+
+  it('renders a ClusterIP service that fronts the app on port 80', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com' })
+    const service = result.resources.find(
+      (r: any) => r.kind === 'Service' && r.metadata.name === 'nextcloud'
+    ) as any
+    expect(service).toBeDefined()
+    expect(service.spec.type).toBe('ClusterIP')
+    expect(service.spec.ports[0].port).toBe(80)
+  })
+
+  it('skips redis resources when cache is disabled', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com', cache: false })
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).not.toContain('RedisReplication')
+  })
+
+  it('renders gateway resources when platform uses gateway routing', () => {
+    const result = render(
+      jsx(RoutingContext.Provider, {
+        value: { mode: 'gateway', gatewayClassName: 'eg' },
+        children: jsx(SecretContext.Provider, {
+          value: openbao as never,
+          children: jsx(Nextcloud, { host: 'cloud.example.com' }),
+        }),
+      })
+    )
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('HTTPRoute')
+  })
+
+  it('renders a valid Ingress when platform uses ingress routing', () => {
+    const result = render(
+      jsx(RoutingContext.Provider, {
+        value: { mode: 'ingress' },
+        children: jsx(SecretContext.Provider, {
+          value: openbao as never,
+          children: jsx(Nextcloud, { host: 'cloud.example.com' }),
+        }),
+      })
+    )
+    const ingress = result.resources.find((r) => r.kind === 'Ingress') as any
+    expect(ingress).toBeDefined()
+    expect(ingress.spec.rules[0].host).toBe('cloud.example.com')
+  })
+
+  it('passes resource validation', () => {
+    const result = renderNextcloud({
+      host: 'cloud.example.com',
+      objectStorage,
+    })
+    for (const resource of result.resources) {
+      expect(validateResource(resource)).toEqual([])
+    }
+  })
+})
+
+describe('rendering with all props', () => {
+  it('accepts the full prop surface', () => {
+    const result = renderNextcloud({
+      name: 'cloud',
+      namespace: 'collab',
+      version: '31.0.5-apache',
+      host: 'cloud.example.com',
+      replicas: 3,
+      storage: '50Gi',
+      storageClassName: 'nfs-client',
+      objectStorage: {
+        ...objectStorage,
+        bucket: 'shared',
+        region: 'eu-north-1',
+        port: 9000,
+        ssl: false,
+      },
+      resources: {
+        requests: { memory: '1Gi', cpu: '500m' },
+        limits: { memory: '4Gi', cpu: '2000m' },
+      },
+      tls: { secretName: 'cloud-tls', clusterIssuer: 'letsencrypt-prod' },
+    })
+
+    const app = findAppDeployment(result, 'cloud')
+    expect(app).toBeDefined()
+    expect(app.spec.replicas).toBe(3)
+    expect(app.spec.template.spec.containers[0].image).toContain('31.0.5-apache')
+    expect(app.spec.template.spec.containers[0].resources.limits.memory).toBe('4Gi')
+
+    const env = app.spec.template.spec.containers[0].env
+    expect(env.find((e: any) => e.name === 'OBJECTSTORE_S3_BUCKET').value).toBe('shared')
+    expect(env.find((e: any) => e.name === 'OBJECTSTORE_S3_REGION').value).toBe('eu-north-1')
+    expect(env.find((e: any) => e.name === 'OBJECTSTORE_S3_PORT').value).toBe('9000')
+    expect(env.find((e: any) => e.name === 'OBJECTSTORE_S3_SSL').value).toBe('false')
+    expect(env.find((e: any) => e.name === 'OBJECTSTORE_S3_HOST').value).toBe(
+      's3.internal.example.com'
+    )
+    expect(env.find((e: any) => e.name === 'NEXTCLOUD_TRUSTED_DOMAINS').value).toBe(
+      'cloud.example.com'
+    )
+
+    const pvc = result.resources.find(
+      (r: any) => r.kind === 'PersistentVolumeClaim' && r.metadata.name === 'cloud-html'
+    ) as any
+    expect(pvc.spec.resources.requests.storage).toBe('50Gi')
+    expect(pvc.spec.storageClassName).toBe('nfs-client')
+  })
+
+  it('defaults OBJECTSTORE_S3_SSL to true and omits the port when unset', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com', objectStorage })
+    const env = findAppDeployment(result).spec.template.spec.containers[0].env
+    expect(env.find((e: any) => e.name === 'OBJECTSTORE_S3_SSL').value).toBe('true')
+    expect(env.find((e: any) => e.name === 'OBJECTSTORE_S3_PORT')).toBeUndefined()
+  })
+
+  it('wires the app and cron to redis and database by naming convention', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com' })
+    const env = findAppDeployment(result).spec.template.spec.containers[0].env
+    expect(env.find((e: any) => e.name === 'REDIS_HOST').value).toBe('nextcloud-redis')
+    expect(env.find((e: any) => e.name === 'REDIS_HOST_PORT').value).toBe('6379')
+    expect(env.find((e: any) => e.name === 'POSTGRES_HOST').value).toBe('nextcloud-rw')
+    const cronEnv = findCron(result).spec.jobTemplate.spec.template.spec.containers[0].env
+    expect(cronEnv.find((e: any) => e.name === 'REDIS_HOST').value).toBe('nextcloud-redis')
+  })
+
+  it('emits the redis replication component with 3 nodes', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com' })
+    const redis = result.resources.find(
+      (r: any) => r.kind === 'RedisReplication' && r.metadata.name === 'nextcloud-redis'
+    ) as any
+    expect(redis).toBeDefined()
+    expect(redis.spec.clusterSize).toBe(3)
+    expect(redis.spec.kubernetesConfig.image).toBe('redis:7.2-alpine')
+  })
+
+  it('keeps only POSTGRES_* database wiring (no DATABASE_URL)', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com' })
+    const env = findAppDeployment(result).spec.template.spec.containers[0].env
+    expect(env.find((e: any) => e.name === 'DATABASE_URL')).toBeUndefined()
+    expect(env.find((e: any) => e.name === 'POSTGRES_HOST').value).toBe('nextcloud-rw')
+    expect(env.find((e: any) => e.name === 'POSTGRES_PORT').value).toBe('5432')
+    expect(env.find((e: any) => e.name === 'POSTGRES_DB').value).toBe('nextcloud')
+    expect(env.find((e: any) => e.name === 'POSTGRES_USER').value).toBe('nextcloud')
+    expect(env.find((e: any) => e.name === 'POSTGRES_PASSWORD').value).toBe('$(PGPASSWORD)')
+  })
+})
+
+describe('secrets handling', () => {
+  it('provisions app secrets through a secrets backend', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com' })
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('OpenBaoStaticSecret')
+    const appSecret = result.resources.find(
+      (r: any) =>
+        r.kind === 'OpenBaoStaticSecret' && r.spec.destination.name === 'nextcloud-app-secrets'
+    ) as any
+    expect(appSecret).toBeDefined()
+    expect(appSecret.spec.path).toBe('test/nextcloud/secrets')
+  })
+
+  it('provisions app secrets through Vault', () => {
+    const result = render(
+      jsx(SecretContext.Provider, {
+        value: { backend: 'vault', mount: 'kv', path: 'apps' },
+        children: jsx(Nextcloud, { host: 'cloud.example.com' }),
+      })
+    )
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('VaultStaticSecret')
+  })
+
+  it('throws when no secrets backend and no secretsName', () => {
+    expect(() => render(jsx(Nextcloud, { host: 'cloud.example.com' }))).toThrow(
+      /application secrets/
+    )
+  })
+
+  it('accepts an existing secretsName without a backend', () => {
+    expect(() =>
+      render(jsx(Nextcloud, { host: 'cloud.example.com', secretsName: 'existing-secrets' }))
+    ).not.toThrow()
+  })
+
+  it('wires credentials via secretKeyRef (never plaintext env)', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com', secretsName: 'existing-secrets' })
+    const env = findAppDeployment(result).spec.template.spec.containers[0].env
+    const adminPassword = env.find((e: any) => e.name === 'NEXTCLOUD_ADMIN_PASSWORD')
+    const pgPassword = env.find((e: any) => e.name === 'PGPASSWORD')
+    expect(adminPassword.valueFrom.secretKeyRef.name).toBe('existing-secrets')
+    expect(adminPassword.valueFrom.secretKeyRef.key).toBe('adminPassword')
+    expect(pgPassword.valueFrom.secretKeyRef.name).toBe('nextcloud-db-credentials')
+    expect(adminPassword.value).toBeUndefined()
+    expect(pgPassword.value).toBeUndefined()
+  })
+
+  it('wires object storage credentials to the referenced bucket secret', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com', objectStorage })
+    const env = findAppDeployment(result).spec.template.spec.containers[0].env
+    const accessKey = env.find((e: any) => e.name === 'AWS_ACCESS_KEY_ID')
+    const secretAccessKey = env.find((e: any) => e.name === 'AWS_SECRET_ACCESS_KEY')
+    expect(accessKey.valueFrom.secretKeyRef).toEqual({
+      name: 'cloud-files-credentials',
+      key: 'accessKey',
+    })
+    expect(secretAccessKey.valueFrom.secretKeyRef).toEqual({
+      name: 'cloud-files-credentials',
+      key: 'secretKey',
+    })
+    expect(accessKey.value).toBeUndefined()
+    expect(secretAccessKey.value).toBeUndefined()
+    // Nextcloud-native envs are $(...) references to the secret-backed vars
+    expect(env.find((e: any) => e.name === 'OBJECTSTORE_S3_KEY').value).toBe('$(AWS_ACCESS_KEY_ID)')
+    expect(env.find((e: any) => e.name === 'OBJECTSTORE_S3_SECRET').value).toBe(
+      '$(AWS_SECRET_ACCESS_KEY)'
+    )
+  })
+
+  it('cron job reads the database password via secretKeyRef', () => {
+    const result = renderNextcloud({ host: 'cloud.example.com' })
+    const env = findCron(result).spec.jobTemplate.spec.template.spec.containers[0].env
+    const pgPassword = env.find((e: any) => e.name === 'PGPASSWORD')
+    expect(pgPassword.valueFrom.secretKeyRef.name).toBe('nextcloud-db-credentials')
+    expect(pgPassword.valueFrom.secretKeyRef.key).toBe('password')
+    expect(pgPassword.value).toBeUndefined()
+  })
+
+  it('renders no plaintext credentials anywhere', () => {
+    const result = renderNextcloud({
+      host: 'cloud.example.com',
+      objectStorage,
+    })
+    const { passed, errors } = runGuardrails(result.resources as any[], [noPlaintextSecrets])
+    if (!passed) {
+      console.error('Plaintext credential violations:', errors)
+    }
+    expect(passed).toBe(true)
+  })
+})

package/examples/basic.tsx

@@ -0,0 +1,16 @@
+import { Platform } from '@r8s/recipes'
+import { Nextcloud } from '@r8s/nextcloud'
+
+export default (
+  <Platform secrets={{ backend: 'openbao', mount: 'kv', path: 'apps' }}>
+    <Nextcloud
+      name="cloud"
+      host="cloud.example.com"
+      objectStorage={{
+        endpoint: 's3.internal.example.com',
+        bucket: 'cloud-files',
+        credentialsSecret: 'cloud-files-credentials',
+      }}
+    />
+  </Platform>
+)

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@r8s/nextcloud",
+  "version": "0.2.0",
+  "description": "Nextcloud file cloud — Postgres file index, Redis cache, S3-compatible primary storage, cron background jobs",
+  "license": "MIT",
+  "author": "Berget AI AB",
+  "homepage": "https://r8s.berget.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/berget-ai/r8s.git",
+    "directory": "packages/nextcloud"
+  },
+  "bugs": "https://github.com/berget-ai/r8s/issues",
+  "keywords": [
+    "nextcloud",
+    "files",
+    "collaboration",
+    "calendar"
+  ],
+  "r8s": {
+    "category": "File & Collaboration"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc --build",
+    "test": "vitest run",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
+  },
+  "category": "Collaboration & Productivity",
+  "dependencies": {
+    "@r8s/core": "^0.2.0",
+    "@r8s/crds": "^0.2.0",
+    "@r8s/k8s-types": "^0.2.0",
+    "@r8s/recipes": "^0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}

package/src/index.tsx

@@ -0,0 +1,447 @@
+import { jsx, Fragment, useContext, declareOperator } from '@r8s/core'
+import type { Deployment, EnvVar, PersistentVolumeClaim, Service } from '@r8s/k8s-types'
+import { OperatorContext, SecretContext } from '@r8s/core/defaults'
+import { operators } from '@r8s/crds'
+import { Database, Endpoint } from '@r8s/recipes'
+import { RedisReplicationComponent } from '@r8s/crds/redis'
+import type { SecretRef } from '@r8s/recipes'
+
+export interface NextcloudProps {
+  /** Resource name (defaults to 'nextcloud') */
+  name?: string
+  /** Kubernetes namespace (defaults to 'default') */
+  namespace?: string
+  /** Container image tag (defaults to '31-apache' — pin a version in production) */
+  version?: string
+  /** Public hostname for the web UI and WebDAV (required) */
+  host: string
+  /**
+   * Number of replicas. Safe to scale beyond 1 when `objectStorage` is
+   * configured (file blobs live in S3) and `cache` is enabled — Nextcloud
+   * becomes effectively stateless. Requires a StorageClass with
+   * ReadWriteMany support for the /var/www/html claim.
+   */
+  replicas?: number
+  /** Provision a Redis replication set for file locking and caching (default: true) */
+  cache?: boolean
+  /**
+   * Size of the PersistentVolumeClaim backing /var/www/html (defaults to
+   * '10Gi'). Apps, config and the data directory all live in this tree.
+   */
+  storage?: string
+  /**
+   * StorageClass for the /var/www/html PersistentVolumeClaim. Must provide
+   * ReadWriteMany when `replicas` > 1 (e.g. NFS or EFS). Defaults to the
+   * cluster default StorageClass when omitted.
+   */
+  storageClassName?: string
+  /**
+   * S3-compatible object storage used as primary storage for files
+   * (RustFS in the platform). Reference a bucket whose credentials live
+   * in a Secret provisioned by the secrets backend (keys: accessKey,
+   * secretKey) — never plaintext.
+   */
+  objectStorage?: {
+    /** S3 host WITHOUT protocol/scheme, e.g. s3.internal.example.com */
+    endpoint: string
+    /** Bucket used for user files */
+    bucket: string
+    /** Name of the Secret holding accessKey / secretKey */
+    credentialsSecret: string
+    /** Region string for the S3 client (defaults to 'us-east-1') */
+    region?: string
+    /** TCP port of the S3 endpoint (defaults to the provider default, typically 443) */
+    port?: number
+    /** Use TLS against the S3 endpoint (default: true) */
+    ssl?: boolean
+  }
+  /**
+   * Name of an existing Secret holding the Nextcloud app secrets
+   * (key: adminPassword). Required unless a secrets backend
+   * (openbao/vault) is configured on the surrounding Platform — the
+   * backend then provisions them automatically. Plaintext admin
+   * passwords are not supported.
+   */
+  secretsName?: string
+  /** Requested resources */
+  resources?: {
+    requests?: { cpu?: string; memory?: string }
+    limits?: { cpu?: string; memory?: string }
+  }
+  /** TLS configuration (defaults to letsencrypt-prod cluster issuer) */
+  tls?: {
+    secretName: string
+    clusterIssuer: string
+  }
+}
+
+const OPERATOR_REDIS = 'redis-operator'
+const HTML_MOUNT = '/var/www/html'
+const STATUS_PATH = '/status.php'
+
+/**
+ * Nextcloud — self-hosted file cloud with Postgres, Redis, S3 primary
+ * storage and background cron jobs.
+ *
+ * @title Nextcloud
+ * @category File & Collaboration
+ *
+ * Composes:
+ * - CNPG Postgres cluster (file index, shares, user data)
+ * - Redis replication set for file locking and caching (default on)
+ * - PersistentVolumeClaim backing /var/www/html (ReadWriteMany)
+ * - Nextcloud Deployment + Service + Endpoint (nextcloud:31-apache,
+ *   probed via /status.php)
+ * - CronJob running `php -f /var/www/html/cron.php` every 5 minutes on
+ *   the same claim (concurrency forbidden)
+ * - S3/RustFS bucket reference for primary file storage
+ * - Admin bootstrap password provisioned by the Platform secrets
+ *   backend (openbao / vault), or referenced from an existing Secret
+ *
+ * The main app is a raw Deployment (not WebService) because Nextcloud
+ * needs the /var/www/html claim volume-mounted; the CronJob shares the
+ * same claim so background jobs operate on the live data tree.
+ *
+ * @example
+ * import { Platform } from '@r8s/recipes'
+ * import { Nextcloud } from '@r8s/nextcloud'
+ *
+ * export default (
+ *   <Platform secrets={{ backend: 'openbao', mount: 'kv', path: 'apps' }}>
+ *     <Nextcloud
+ *       name="cloud"
+ *       host="cloud.example.com"
+ *       objectStorage={{
+ *         endpoint: 's3.internal.example.com',
+ *         bucket: 'cloud-files',
+ *         credentialsSecret: 'cloud-files-credentials',
+ *       }}
+ *     />
+ *   </Platform>
+ * )
+ * @example
+ * import { Nextcloud } from '@r8s/nextcloud'
+ *
+ * export default (
+ *   <Nextcloud
+ *     name="cloud"
+ *     host="${env:CLOUD_HOST}"
+ *     secretsName="cloud-app-secrets"
+ *     objectStorage={{
+ *       endpoint: '${env:S3_ENDPOINT}',
+ *       bucket: 'cloud-files',
+ *       credentialsSecret: 'cloud-files-credentials',
+ *     }}
+ *   />
+ * )
+ */
+export function Nextcloud(props: NextcloudProps) {
+  const {
+    name = 'nextcloud',
+    namespace = 'default',
+    version = '31-apache',
+    host,
+    replicas = 1,
+    cache = true,
+    storage = '10Gi',
+    storageClassName,
+    objectStorage,
+    secretsName,
+    resources = {
+      requests: { memory: '512Mi', cpu: '250m' },
+      limits: { memory: '2Gi', cpu: '1000m' },
+    },
+    tls = { secretName: `${name}-tls`, clusterIssuer: 'letsencrypt-prod' },
+  } = props
+
+  const sharedOperators = useContext(OperatorContext)
+  const secretProvider = useContext(SecretContext)
+  const resources_: ReturnType<typeof jsx>[] = []
+
+  const dbHost = `${name}-rw`
+  const dbCredentialsName = `${name}-db-credentials`
+  const appSecretsName = secretsName ?? `${name}-app-secrets`
+  const htmlClaim = `${name}-html`
+  const image = `nextcloud:${version}`
+  const cronSchedule = '*/5 * * * *'
+
+  // --- App secrets provisioning ---------------------------------------------
+  // The admin bootstrap password must never be rendered as plaintext. With a
+  // secrets backend it is provisioned through the backend (key `adminPassword`);
+  // otherwise reference a pre-created Secret.
+  if (!secretsName) {
+    if (
+      !secretProvider ||
+      (secretProvider.backend !== 'vault' && secretProvider.backend !== 'openbao')
+    ) {
+      throw new Error(
+        `Nextcloud "${name}" requires application secrets (NEXTCLOUD_ADMIN_PASSWORD).\n` +
+          `\n` +
+          `Nextcloud bootstraps its admin account from this password — it must not ` +
+          `be rendered as plaintext.\n` +
+          `\n` +
+          `Fix: configure a secrets backend on the Platform:\n` +
+          `  <Platform secrets={{ backend: 'openbao', mount: 'kv', path: 'apps' }}>\n` +
+          `    <Nextcloud name="${name}" host="${host}" />\n` +
+          `  </Platform>\n` +
+          `\n` +
+          `Or reference a pre-created Secret (key: adminPassword):\n` +
+          `  <Nextcloud name="${name}" host="${host}" secretsName="${name}-app-secrets" />`
+      )
+    }
+
+    const spec = {
+      ...(secretProvider.backend === 'vault'
+        ? { vaultAuthRef: secretProvider.authRef }
+        : { openbaoAuthRef: secretProvider.authRef }),
+      mount: secretProvider.mount,
+      type: 'kv-v2' as const,
+      path: `${secretProvider.path ?? name}/${name}/secrets`,
+      destination: { create: true, name: appSecretsName },
+    }
+    resources_.push(
+      secretProvider.backend === 'vault'
+        ? jsx('VaultStaticSecret', {
+            apiVersion: 'secrets.hashicorp.com/v1beta1',
+            kind: 'VaultStaticSecret',
+            metadata: { name: `${name}-secrets`, namespace },
+            spec,
+          })
+        : jsx('OpenBaoStaticSecret', {
+            apiVersion: 'secrets.openbao.org/v1beta1',
+            kind: 'OpenBaoStaticSecret',
+            metadata: { name: `${name}-secrets`, namespace },
+            spec,
+          })
+    )
+  }
+
+  // --- Operators -------------------------------------------------------------
+  if (cache && !sharedOperators.some((op) => op.name === OPERATOR_REDIS)) {
+    resources_.push(declareOperator(operators[OPERATOR_REDIS]()))
+  }
+
+  // Redis — file locking + caching (OT-Container-Kit operator). A
+  // RedisReplication (master/replica) is what Nextcloud's locking needs;
+  // cluster mode is overkill and the `${name}-redis` service fronts it.
+  if (cache) {
+    resources_.push(
+      RedisReplicationComponent({
+        metadata: { name: `${name}-redis`, namespace },
+        spec: {
+          clusterSize: 3,
+          kubernetesConfig: { image: 'redis:7.2-alpine' },
+        },
+      })
+    )
+  }
+
+  // --- /var/www/html persistence ----------------------------------------------
+  // Apps, config and the data directory live under /var/www/html and must
+  // survive pod restarts. ReadWriteMany lets the cron job share the same
+  // tree and keeps replicas > 1 viable (requires an RWX StorageClass).
+  const htmlPvc: PersistentVolumeClaim = {
+    apiVersion: 'v1',
+    kind: 'PersistentVolumeClaim',
+    metadata: { name: htmlClaim, namespace, labels: { app: name } },
+    spec: {
+      accessModes: ['ReadWriteMany'],
+      resources: { requests: { storage } },
+      ...(storageClassName && { storageClassName }),
+    },
+  }
+  resources_.push(jsx('PersistentVolumeClaim', htmlPvc))
+
+  // --- Env wiring --------------------------------------------------------------
+  // Every credential is referenced with $(VAR) expansion or secretKeyRef —
+  // no plaintext in the manifest. Secret-backed vars are declared BEFORE
+  // plain env vars so dependent $(VAR) expansion resolves. Nextcloud
+  // natively reads POSTGRES_* and OBJECTSTORE_S3_*; the S3 keys/secrets are
+  // expanded from the AWS_* secret-backed vars. (Nextcloud ignores
+  // DATABASE_URL — do not add it back.)
+  const secrets: Record<string, SecretRef | string> = {
+    PGPASSWORD: { secret: dbCredentialsName, key: 'password' },
+    NEXTCLOUD_ADMIN_PASSWORD: { secret: appSecretsName, key: 'adminPassword' },
+    ...(objectStorage
+      ? {
+          AWS_ACCESS_KEY_ID: { secret: objectStorage.credentialsSecret, key: 'accessKey' },
+          AWS_SECRET_ACCESS_KEY: { secret: objectStorage.credentialsSecret, key: 'secretKey' },
+        }
+      : {}),
+  }
+
+  const env: Record<string, string> = {
+    POSTGRES_HOST: dbHost,
+    POSTGRES_PORT: '5432',
+    POSTGRES_DB: name,
+    POSTGRES_USER: name,
+    POSTGRES_PASSWORD: '$(PGPASSWORD)',
+    NEXTCLOUD_ADMIN_USER: 'admin',
+    NEXTCLOUD_TRUSTED_DOMAINS: host,
+    OVERWRITEHOST: host,
+    OVERWRITEPROTOCOL: 'https',
+    OVERWRITECLIURL: `https://${host}`,
+    ...(cache ? { REDIS_HOST: `${name}-redis`, REDIS_HOST_PORT: '6379' } : {}),
+    ...(objectStorage
+      ? {
+          OBJECTSTORE_S3_HOST: objectStorage.endpoint,
+          OBJECTSTORE_S3_BUCKET: objectStorage.bucket,
+          OBJECTSTORE_S3_REGION: objectStorage.region ?? 'us-east-1',
+          OBJECTSTORE_S3_SSL: (objectStorage.ssl ?? true) ? 'true' : 'false',
+          ...(objectStorage.port !== undefined && {
+            OBJECTSTORE_S3_PORT: String(objectStorage.port),
+          }),
+          OBJECTSTORE_S3_USEPATH_STYLE: 'true',
+          OBJECTSTORE_S3_AUTOCREATE: 'true',
+          OBJECTSTORE_S3_KEY: '$(AWS_ACCESS_KEY_ID)',
+          OBJECTSTORE_S3_SECRET: '$(AWS_SECRET_ACCESS_KEY)',
+        }
+      : {}),
+  }
+
+  const envVars: EnvVar[] = Object.entries(secrets).map(([envName, ref]) => ({
+    name: envName,
+    valueFrom: {
+      secretKeyRef:
+        typeof ref === 'string'
+          ? { name: ref, key: envName }
+          : { name: ref.secret, key: ref.key || envName },
+    },
+  }))
+  envVars.push(...Object.entries(env).map(([envName, value]) => ({ name: envName, value })))
+
+  // --- Database (CNPG) + app + endpoint ------------------------------------------
+  // <Database> is the parent wrapper so the CNPG operator and the Cluster
+  // piggyback on the r8s Database recipe (connect info stays by convention:
+  // host `${name}-rw`, secret `${name}-db-credentials` key `password`). The
+  // app is a raw Deployment because WebService cannot mount volumes.
+  const app: Deployment = {
+    apiVersion: 'apps/v1',
+    kind: 'Deployment',
+    metadata: { name, namespace, labels: { app: name } },
+    spec: {
+      replicas,
+      selector: { matchLabels: { app: name } },
+      template: {
+        metadata: { labels: { app: name } },
+        spec: {
+          containers: [
+            {
+              name: 'app',
+              image,
+              imagePullPolicy: 'Always',
+              ports: [{ containerPort: 80 }],
+              env: envVars,
+              resources,
+              livenessProbe: {
+                httpGet: { path: STATUS_PATH, port: 80 },
+                initialDelaySeconds: 30,
+                periodSeconds: 10,
+              },
+              readinessProbe: {
+                httpGet: { path: STATUS_PATH, port: 80 },
+                initialDelaySeconds: 20,
+                periodSeconds: 10,
+                failureThreshold: 5,
+              },
+              volumeMounts: [{ name: 'html', mountPath: HTML_MOUNT }],
+            },
+          ],
+          volumes: [{ name: 'html', persistentVolumeClaim: { claimName: htmlClaim } }],
+        },
+      },
+    },
+  }
+
+  const appService: Service = {
+    apiVersion: 'v1',
+    kind: 'Service',
+    metadata: { name, namespace },
+    spec: {
+      type: 'ClusterIP',
+      selector: { app: name },
+      ports: [{ port: 80, targetPort: 80 }],
+    },
+  }
+
+  resources_.push(
+    jsx(Database, {
+      name,
+      namespace,
+      storage: '10Gi',
+      children: jsx(Fragment, {
+        children: [jsx('Deployment', app), jsx('Service', appService)],
+      }),
+    })
+  )
+
+  // --- CronJob — background jobs (php -f cron.php) --------------------------------
+  // WebService cannot express a separate scheduled workload, so the cron job
+  // is a raw CronJob that mounts the SAME `${name}-html` claim and runs the
+  // image's own php. It cannot see DatabaseContext: host/user are hardcoded
+  // by convention and the DB password arrives via secretKeyRef.
+  resources_.push(
+    jsx('CronJob', {
+      apiVersion: 'batch/v1',
+      kind: 'CronJob',
+      metadata: { name: `${name}-cron`, namespace },
+      spec: {
+        schedule: cronSchedule,
+        concurrencyPolicy: 'Forbid',
+        successfulJobsHistoryLimit: 1,
+        failedJobsHistoryLimit: 1,
+        jobTemplate: {
+          spec: {
+            backoffLimit: 2,
+            template: {
+              metadata: { labels: { app: `${name}-cron` } },
+              spec: {
+                restartPolicy: 'OnFailure',
+                containers: [
+                  {
+                    name: 'nextcloud-cron',
+                    image,
+                    command: ['php', '-f', '/var/www/html/cron.php'],
+                    env: [
+                      { name: 'POSTGRES_HOST', value: dbHost },
+                      { name: 'POSTGRES_PORT', value: '5432' },
+                      { name: 'POSTGRES_DB', value: name },
+                      { name: 'POSTGRES_USER', value: name },
+                      {
+                        name: 'PGPASSWORD',
+                        valueFrom: {
+                          secretKeyRef: { name: dbCredentialsName, key: 'password' },
+                        },
+                      },
+                      ...(cache ? [{ name: 'REDIS_HOST', value: `${name}-redis` }] : []),
+                    ],
+                    resources: {
+                      requests: { memory: '128Mi', cpu: '100m' },
+                      limits: { memory: '512Mi', cpu: '500m' },
+                    },
+                    volumeMounts: [{ name: 'html', mountPath: HTML_MOUNT }],
+                  },
+                ],
+                volumes: [{ name: 'html', persistentVolumeClaim: { claimName: htmlClaim } }],
+              },
+            },
+          },
+        },
+      },
+    })
+  )
+
+  // --- Endpoint — web UI and WebDAV share the host --------------------------------
+  resources_.push(
+    <Endpoint
+      name={`${name}-endpoint`}
+      namespace={namespace}
+      host={host}
+      serviceName={name}
+      servicePort={80}
+      tls={tls}
+    />
+  )
+
+  return jsx(Fragment, { children: resources_ })
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true
+  },
+  "include": ["src/**/*"],
+  "references": [
+    { "path": "../core" },
+    { "path": "../k8s-types" },
+    { "path": "../crds" },
+    { "path": "../recipes" }
+  ]
+}