@r8s/outline 0.2.0

package/__tests__/outline.test.ts

@@ -0,0 +1,213 @@
+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'
+
+// Outline recipe tests:
+//   1. Operator declarations (deduped via OperatorContext)
+//   2. Rendering: defaults, all props, gateway/ingress adaptation
+//   3. Security: no plaintext credentials in rendered output
+import { Outline } from '../src/index'
+
+const openbao = { backend: 'openbao', mount: 'kv', path: 'test' }
+
+/** Render Outline inside a Platform-like secrets backend (OpenBao). */
+function renderOutline(props: Record<string, unknown>): ReturnType<typeof render> {
+  return render(
+    jsx(SecretContext.Provider, {
+      value: openbao as never,
+      children: jsx(Outline, props as never),
+    })
+  )
+}
+
+/** Wrap Outline in an OperatorContext (no secrets backend). */
+function elementWithContext(ops: any[], props: Record<string, unknown>): r8sElement {
+  return jsx(OperatorContext.Provider, {
+    value: ops,
+    children: jsx(Outline, props as never),
+  })
+}
+
+const objectStorage = {
+  endpoint: 'https://s3.internal.example.com',
+  bucket: 'wiki-attachments',
+  credentialsSecret: 'wiki-attachments-credentials',
+}
+
+const sso = {
+  issuer: 'https://keycloak.example.com/realms/platform',
+  clientId: 'outline',
+  clientSecretRef: { secret: 'outline-sso', key: 'clientSecret' },
+}
+
+describe('operator declarations', () => {
+  it('declares the redis operator when cache is enabled', () => {
+    const result = renderOutline({ host: 'wiki.example.com' })
+    expect(result.operators.some((op) => op.name === 'redis-operator')).toBe(true)
+  })
+
+  it('declares the cnpg operator via the Database recipe', () => {
+    const result = renderOutline({ host: 'wiki.example.com' })
+    expect(result.operators.some((op) => op.name === 'cnpg')).toBe(true)
+  })
+
+  it('skips the redis operator when cache is disabled', () => {
+    const result = renderOutline({ host: 'wiki.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: 'wiki.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 deployment, service, ingress, database and redis', () => {
+    const result = renderOutline({ host: 'wiki.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('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(Outline, { host: 'wiki.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(Outline, { host: 'wiki.example.com' }),
+        }),
+      })
+    )
+    const ingress = result.resources.find((r) => r.kind === 'Ingress') as any
+    expect(ingress).toBeDefined()
+    expect(ingress.spec.rules[0].host).toBe('wiki.example.com')
+  })
+
+  it('passes resource validation', () => {
+    const result = renderOutline({
+      host: 'wiki.example.com',
+      objectStorage,
+      sso,
+    })
+    for (const resource of result.resources) {
+      expect(validateResource(resource)).toEqual([])
+    }
+  })
+})
+
+describe('rendering with all props', () => {
+  it('accepts the full prop surface', () => {
+    const result = renderOutline({
+      name: 'wiki',
+      namespace: 'docs',
+      version: '0.78.0',
+      host: 'docs.example.com',
+      replicas: 3,
+      objectStorage: { ...objectStorage, bucket: 'docs' },
+      sso,
+      resources: {
+        requests: { memory: '1Gi', cpu: '500m' },
+        limits: { memory: '4Gi', cpu: '2000m' },
+      },
+      tls: { secretName: 'docs-tls', clusterIssuer: 'letsencrypt-prod' },
+    })
+
+    const app = result.resources.find(
+      (r: any) => r.kind === 'Deployment' && r.metadata.name === 'wiki'
+    ) as any
+    expect(app).toBeDefined()
+    expect(app.spec.replicas).toBe(3)
+    expect(app.spec.template.spec.containers[0].image).toContain('0.78.0')
+    expect(app.spec.template.spec.containers[0].resources.limits.memory).toBe('4Gi')
+  })
+
+  it('wires S3 and SSO on the app when configured', () => {
+    const result = renderOutline({
+      host: 'wiki.example.com',
+      objectStorage,
+      sso,
+    })
+    const app = result.resources.find(
+      (r: any) => r.kind === 'Deployment' && r.metadata.name === 'outline'
+    ) as any
+    const env = app.spec.template.spec.containers[0].env
+    expect(env.find((e: any) => e.name === 'AWS_S3_UPLOAD_BUCKET_NAME').value).toBe(
+      'wiki-attachments'
+    )
+    expect(env.find((e: any) => e.name === 'OIDC_ISSUER').value).toBe(sso.issuer)
+  })
+})
+
+describe('secrets handling', () => {
+  it('provisions app secrets through a secrets backend', () => {
+    const result = renderOutline({ host: 'wiki.example.com' })
+    const kinds = result.resources.map((r) => r.kind)
+    expect(kinds).toContain('OpenBaoStaticSecret')
+  })
+
+  it('throws when no secrets backend and no secretsName', () => {
+    expect(() => render(jsx(Outline, { host: 'wiki.example.com' }))).toThrow(/application secrets/)
+  })
+
+  it('accepts an existing secretsName without a backend', () => {
+    expect(() =>
+      render(jsx(Outline, { host: 'wiki.example.com', secretsName: 'existing-secrets' }))
+    ).not.toThrow()
+  })
+
+  it('wires credentials via secretKeyRef (never plaintext env)', () => {
+    const result = renderOutline({ host: 'wiki.example.com', secretsName: 'existing-secrets' })
+    const app = result.resources.find(
+      (r: any) => r.kind === 'Deployment' && r.metadata.name === 'outline'
+    ) as any
+    const env = app.spec.template.spec.containers[0].env
+    const secretKey = env.find((e: any) => e.name === 'SECRET_KEY')
+    const pgPassword = env.find((e: any) => e.name === 'PGPASSWORD')
+    expect(secretKey.valueFrom.secretKeyRef.name).toBe('existing-secrets')
+    expect(pgPassword.valueFrom.secretKeyRef.name).toBe('outline-db-credentials')
+    expect(secretKey.value).toBeUndefined()
+    expect(pgPassword.value).toBeUndefined()
+  })
+
+  it('renders no plaintext credentials anywhere', () => {
+    const result = renderOutline({
+      host: 'wiki.example.com',
+      objectStorage,
+      sso,
+    })
+    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,21 @@
+import { Platform } from '@r8s/recipes'
+import { Outline } from '@r8s/outline'
+
+export default (
+  <Platform secrets={{ backend: 'openbao', mount: 'kv', path: 'apps' }}>
+    <Outline
+      name="wiki"
+      host="wiki.example.com"
+      objectStorage={{
+        endpoint: 'https://s3.internal.example.com',
+        bucket: 'wiki-attachments',
+        credentialsSecret: 'wiki-attachments-credentials',
+      }}
+      sso={{
+        issuer: 'https://keycloak.example.com/realms/platform',
+        clientId: 'outline',
+        clientSecretRef: { secret: 'outline-sso', key: 'clientSecret' },
+      }}
+    />
+  </Platform>
+)

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@r8s/outline",
+  "version": "0.2.0",
+  "description": "Outline wiki — Postgres persistence, Redis queue, S3 attachments, OIDC SSO via Keycloak",
+  "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/outline"
+  },
+  "bugs": "https://github.com/berget-ai/r8s/issues",
+  "keywords": [
+    "outline",
+    "wiki",
+    "documentation",
+    "knowledge"
+  ],
+  "r8s": {
+    "category": "Knowledge & Documentation"
+  },
+  "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,289 @@
+import { jsx, Fragment, useContext, declareOperator } from '@r8s/core'
+import { Namespace, OperatorContext, SecretContext } from '@r8s/core/defaults'
+import { operators } from '@r8s/crds'
+import { Database, WebService, Endpoint } from '@r8s/recipes'
+import { RedisReplicationComponent } from '@r8s/crds/redis'
+import type { SecretRef } from '@r8s/recipes'
+
+export interface OutlineProps {
+  /** Resource name (defaults to 'outline') */
+  name?: string
+  /** Kubernetes namespace (defaults to 'default') */
+  namespace?: string
+  /** Container image tag (defaults to 'latest' — pin a version in production) */
+  version?: string
+  /** Public hostname for the wiki */
+  host: string
+  /** Storage request for the CNPG Postgres cluster (defaults to '10Gi') */
+  storage?: string
+  /** Number of replicas (Outline is stateless — scale freely) */
+  replicas?: number
+  /** Provision a Redis cluster for the queue and rate limiting (default: true) */
+  cache?: boolean
+  /**
+   * S3-compatible object storage for attachments (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 endpoint URL, e.g. https://s3.internal.example.com */
+    endpoint: string
+    /** Bucket name for attachments */
+    bucket: string
+    /** Name of the Secret holding accessKey / secretKey */
+    credentialsSecret: string
+    /** Region string for Outline's S3 client (defaults to 'us-east-1') */
+    region?: string
+  }
+  /**
+   * OIDC SSO client — register Outline as a client in Keycloak (the
+   * Auth recipe) and reference the client secret through the backend.
+   */
+  sso?: {
+    issuer: string
+    clientId: string
+    clientSecretRef: SecretRef
+    scopes?: string
+  }
+  /**
+   * Name of an existing Secret holding `secretKey` and `utilsSecret`.
+   * Required unless a secrets backend (openbao/vault) is configured on
+   * the surrounding Platform — the backend then provisions them.
+   */
+  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'
+
+/**
+ * Outline — team wiki with Postgres, Redis, S3 attachments and OIDC SSO.
+ *
+ * @title Outline
+ * @category Knowledge & Documentation
+ *
+ * Composes:
+ * - CNPG Postgres cluster (documents, revisions, users)
+ * - Redis cluster for queue + rate limiting (default on)
+ * - Outline Deployment + Service + Endpoint
+ * - S3/RustFS bucket reference for attachments
+ * - SECRET_KEY / UTILS_SECRET provisioned by the Platform secrets
+ *   backend (openbao / vault), or referenced from an existing Secret
+ * - OIDC SSO against the Keycloak `Auth` recipe
+ *
+ * @example
+ * import { Platform } from '@r8s/recipes'
+ * import { Outline } from '@r8s/outline'
+ *
+ * export default (
+ *   <Platform secrets={{ backend: 'openbao', mount: 'kv', path: 'apps' }}>
+ *     <Outline
+ *       name="wiki"
+ *       host="wiki.example.com"
+ *       objectStorage={{
+ *         endpoint: 'https://s3.internal.example.com',
+ *         bucket: 'wiki-attachments',
+ *         credentialsSecret: 'wiki-attachments-credentials',
+ *       }}
+ *       sso={{
+ *         issuer: 'https://keycloak.example.com/realms/platform',
+ *         clientId: 'outline',
+ *         clientSecretRef: { secret: 'outline-sso', key: 'clientSecret' },
+ *       }}
+ *     />
+ *   </Platform>
+ * )
+ */
+export function Outline(props: OutlineProps) {
+  const {
+    name = 'outline',
+    namespace: namespaceProp,
+    version = 'latest',
+    host,
+    storage = '10Gi',
+    replicas = 1,
+    cache = true,
+    objectStorage,
+    sso,
+    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)
+  // Inherit namespace from <Platform> context — mirrors recipes/database.tsx
+  const contextNamespace = useContext(Namespace)
+  const namespace =
+    namespaceProp ?? (contextNamespace !== 'default' ? contextNamespace : undefined) ?? 'default'
+  const resources_: ReturnType<typeof jsx>[] = []
+
+  const dbHost = `${name}-rw`
+  const dbCredentialsName = `${name}-db-credentials`
+  const platformSecretsName = secretsName ?? `${name}-app-secrets`
+
+  // --- App secrets (SECRET_KEY / UTILS_SECRET) ------------------------------
+  if (!secretsName) {
+    if (
+      !secretProvider ||
+      (secretProvider.backend !== 'vault' && secretProvider.backend !== 'openbao')
+    ) {
+      throw new Error(
+        `Outline "${name}" requires application secrets (SECRET_KEY, UTILS_SECRET).\n` +
+          `\n` +
+          `These 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` +
+          `    <Outline name="${name}" host="${host}" />\n` +
+          `  </Platform>\n` +
+          `\n` +
+          `Or reference a pre-created Secret (keys: secretKey, utilsSecret):\n` +
+          `  <Outline 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: platformSecretsName },
+    }
+    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 — queue + rate limiting (OT-Container-Kit operator)
+  if (cache) {
+    resources_.push(
+      RedisReplicationComponent({
+        metadata: { name: `${name}-redis`, namespace },
+        spec: {
+          clusterSize: 3,
+          kubernetesConfig: { image: 'redis:7.2-alpine' },
+        },
+      })
+    )
+  }
+
+  // --- Env wiring --------------------------------------------------------------
+  // Every credential is referenced with $(VAR) expansion or secretKeyRef —
+  // no plaintext in the manifest. The WebService declares secret-backed
+  // vars before plain env vars, so dependent expansion resolves.
+  const env: Record<string, string> = {
+    PORT: '3000',
+    // Deterministic parts inlined; password arrives via PGPASSWORD
+    DATABASE_URL: `postgresql://${name}:$(PGPASSWORD)@${dbHost}:5432/${name}`,
+    SECRET_KEY: '$(SECRET_KEY)',
+    UTILS_SECRET: '$(UTILS_SECRET)',
+    URL: `https://${host}`,
+    APP_URL: `https://${host}`,
+    PROXY_HEADERS_TRUSTED: 'true',
+    ...(cache ? { REDIS_URL: `redis://${name}-redis:6379` } : {}),
+    ...(objectStorage
+      ? {
+          FILE_STORAGE: 's3',
+          AWS_REGION: objectStorage.region ?? 'us-east-1',
+          AWS_S3_UPLOAD_BUCKET_URL: `${objectStorage.endpoint}/${objectStorage.bucket}`,
+          AWS_S3_UPLOAD_BUCKET_NAME: objectStorage.bucket,
+          AWS_S3_FORCE_PATH_STYLE: 'true',
+          AWS_S3_ACL: 'private',
+        }
+      : {}),
+    ...(sso
+      ? {
+          OIDC_ISSUER: sso.issuer,
+          OIDC_CLIENT_ID: sso.clientId,
+          OIDC_CLIENT_SECRET: '$(OIDC_CLIENT_SECRET)',
+          OIDC_SCOPES: sso.scopes ?? 'openid email profile',
+          OIDC_AUTH_URI: '$(OIDC_ISSUER)/protocol/openid-connect/auth',
+          OIDC_TOKEN_URI: '$(OIDC_ISSUER)/protocol/openid-connect/token',
+          OIDC_USERINFO_URI: '$(OIDC_ISSUER)/protocol/openid-connect/userinfo',
+        }
+      : {}),
+  }
+
+  // Credentials delivered via secretKeyRef (runtime injection)
+  const secrets: Record<string, SecretRef | string> = {
+    SECRET_KEY: { secret: platformSecretsName, key: 'secretKey' },
+    UTILS_SECRET: { secret: platformSecretsName, key: 'utilsSecret' },
+    PGPASSWORD: { secret: dbCredentialsName, key: 'password' },
+    ...(objectStorage
+      ? {
+          AWS_ACCESS_KEY_ID: { secret: objectStorage.credentialsSecret, key: 'accessKey' },
+          AWS_SECRET_ACCESS_KEY: { secret: objectStorage.credentialsSecret, key: 'secretKey' },
+        }
+      : {}),
+    ...(sso ? { OIDC_CLIENT_SECRET: sso.clientSecretRef } : {}),
+  }
+
+  // --- Database + app + endpoint ------------------------------------------------
+  // Database wraps the app so credentials stay consistent with the r8s
+  // Database recipe (CNPG dedicated cluster provisions the secret).
+  resources_.push(
+    jsx(Database, {
+      name,
+      namespace,
+      storage,
+      children: (
+        <WebService
+          name={name}
+          namespace={namespace}
+          image={`outlinewiki/outline:${version}`}
+          port={3000}
+          replicas={replicas}
+          resources={resources}
+          probes={{ liveness: { tcp: true }, readiness: { tcp: true, initialDelaySeconds: 15 } }}
+          env={env}
+          secrets={secrets}
+        />
+      ),
+    })
+  )
+
+  resources_.push(
+    <Endpoint
+      name={`${name}-endpoint`}
+      namespace={namespace}
+      host={host}
+      serviceName={name}
+      servicePort={3000}
+      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" }
+  ]
+}