@bluedynamics/cdk8s-plone 0.1.43 → 0.1.45

package/.jsii

@@ -7,7 +7,7 @@
     ]
   },
   "dependencies": {
-    "cdk8s": "^2.70.79",
+    "cdk8s": "^2.70.82",
     "cdk8s-plus-30": "^2.4.10",
     "constructs": "^10.4.2"
   },
@@ -108,7 +108,7 @@
   },
   "name": "@bluedynamics/cdk8s-plone",
   "readme": {
-    "markdown": "# CDK8S Plone\n\n> TypeScript and Python library for deploying Plone CMS to Kubernetes using CDK8S\n\n[![npm version](https://badge.fury.io/js/%40bluedynamics%2Fcdk8s-plone.svg)](https://www.npmjs.com/package/@bluedynamics/cdk8s-plone)\n[![PyPI version](https://badge.fury.io/py/cdk8s-plone.svg)](https://pypi.org/project/cdk8s-plone/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n\n## Overview\n\ncdk8s-plone provides CDK8S constructs for deploying [Plone CMS](https://plone.org/) on Kubernetes. Define your infrastructure using TypeScript or Python and generate Kubernetes manifests automatically.\n\n**Key Features:**\n- 🚀 Supports Volto (React frontend) and Blicca (formerly Classic UI)\n- 📦 High availability with configurable replicas\n- ⚡ Optional Varnish HTTP caching via kube-httpcache (`PloneHttpcache`) or cloud-vinyl VinylCache operator (`PloneVinylCache`)\n- 🔧 Fine-grained resource and probe configuration\n- 🌍 Multi-language support (TypeScript/JavaScript and Python)\n- ✅ Type-safe infrastructure as code\n\n## Quick Start\n\n### Installation\n\n**TypeScript/JavaScript:**\n```bash\nnpm install @bluedynamics/cdk8s-plone\n```\n\n**Python:**\n```bash\npip install cdk8s-plone\n```\n\n### Basic Example\n\n```typescript\nimport { App, Chart } from 'cdk8s';\nimport { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';\n\nconst app = new App();\nconst chart = new Chart(app, 'PloneDeployment');\n\nnew Plone(chart, 'my-plone', {\n  variant: PloneVariant.VOLTO,\n  backend: {\n    image: 'plone/plone-backend:6.1.3',\n    replicas: 3,\n  },\n  frontend: {\n    image: 'plone/plone-frontend:16.0.0',\n    replicas: 2,\n  },\n});\n\napp.synth();\n```\n\nGenerate Kubernetes manifests:\n```bash\ncdk8s synth\nkubectl apply -f dist/\n```\n\n## Documentation\n\n**📚 Full documentation:** https://bluedynamics.github.io/cdk8s-plone/\n\n- [Quick Start Tutorial](https://bluedynamics.github.io/cdk8s-plone/tutorials/01-quick-start.html)\n- [Configuration Reference](https://bluedynamics.github.io/cdk8s-plone/reference/configuration-options.html)\n- [Architecture Overview](https://bluedynamics.github.io/cdk8s-plone/explanation/architecture.html)\n- [Complete API Documentation](./API.md)\n\n## Examples\n\nComplete working examples are available in the [`examples/`](examples/) directory:\n\n- **[Production Volto](examples/production-volto/)** - Production-ready Plone 6 deployment with the React single-page frontend:\n  - Volto frontend (React) + REST API backend\n  - PostgreSQL with RelStorage (CloudNativePG or Bitnami)\n  - Varnish HTTP caching with kube-httpcache\n  - Ingress support (Traefik/Kong) with TLS\n\n- **[Blicca](examples/blicca/)** - Plone deployment with server-side rendering (formerly Classic UI):\n  - Blicca (backend renders the UI, no separate frontend)\n  - PostgreSQL with RelStorage (CloudNativePG or Bitnami)\n  - Varnish HTTP caching with kube-httpcache\n  - Ingress support (Traefik/Kong) with TLS\n  - Simpler architecture (no separate frontend)\n\n### Prometheus Metrics\n\nEnable Prometheus ServiceMonitor for metrics collection (requires Prometheus Operator):\n\n```typescript\nnew Plone(chart, 'my-plone', {\n  backend: {\n    servicemonitor: true,\n    metricsPath: '/metrics',  // optional, defaults to '/metrics'\n  },\n  frontend: {\n    servicemonitor: true,\n    metricsPort: 9090,  // optional, defaults to service port\n  },\n});\n```\n\n**Note:** You must instrument your Plone backend/frontend to expose metrics at the configured endpoint. For Volto/Node.js frontends, consider using [prom-client](https://www.npmjs.com/package/prom-client) or [express-prometheus-middleware](https://www.npmjs.com/package/express-prometheus-middleware).\n\n## Requirements\n- **kubectl** - [Install kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)\n- **Node.js 16+** (for TypeScript/JavaScript) - [Install Node.js](https://nodejs.org/)\n- **Python 3.8+** (for Python) - [Install Python](https://www.python.org/)\n- **Kubernetes cluster** (local or cloud)\n\nFor detailed setup instructions, see [Setup Prerequisites](https://bluedynamics.github.io/cdk8s-plone/how-to/setup-prerequisites.html).\n\n## Development\n\nThis project uses [Projen](https://projen.io/) for project management.\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n\n# Update project configuration\n# Edit .projenrc.ts, then run:\nnpx projen\n```\n\nFor detailed development instructions, see [CONTRIBUTING.md](./CONTRIBUTING.md) (if available).\n\n## Resources\n\n- [CDK8S Documentation](https://cdk8s.io/)\n- [Plone CMS](https://plone.org/)\n- [kube-httpcache](https://github.com/mittwald/kube-httpcache) (for HTTP caching)\n- [CloudNativePG](https://cloudnative-pg.io/) (for PostgreSQL management)\n\n## License\n\n[Apache 2.0](LICENSE)\n\n## Maintainers\n\nMaintained by [Blue Dynamics Alliance](https://github.com/bluedynamics)\n\n**Author:** Jens W. Klein (jk@kleinundpartner.at)\n"
+    "markdown": "# CDK8S Plone\n\n> TypeScript and Python library for deploying Plone CMS to Kubernetes using CDK8S\n\n[![npm version](https://badge.fury.io/js/%40bluedynamics%2Fcdk8s-plone.svg)](https://www.npmjs.com/package/@bluedynamics/cdk8s-plone)\n[![PyPI version](https://badge.fury.io/py/cdk8s-plone.svg)](https://pypi.org/project/cdk8s-plone/)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n\n## Overview\n\ncdk8s-plone provides CDK8S constructs for deploying [Plone CMS](https://plone.org/) on Kubernetes. Define your infrastructure using TypeScript or Python and generate Kubernetes manifests automatically.\n\n**Key Features:**\n- 🚀 Supports Volto (React frontend) and Blicca (formerly Classic UI)\n- 📦 High availability with configurable replicas\n- ⚡ Optional Varnish HTTP caching via kube-httpcache (`PloneHttpcache`) or cloud-vinyl VinylCache operator (`PloneVinylCache`)\n- 🔧 Fine-grained resource and probe configuration\n- 🌍 Multi-language support (TypeScript/JavaScript and Python)\n- ✅ Type-safe infrastructure as code\n\n## Quick Start\n\n### Installation\n\n**TypeScript/JavaScript:**\n```bash\nnpm install @bluedynamics/cdk8s-plone\n```\n\n**Python:**\n```bash\npip install cdk8s-plone\n```\n\n### Basic Example\n\n```typescript\nimport { App, Chart } from 'cdk8s';\nimport { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';\n\nconst app = new App();\nconst chart = new Chart(app, 'PloneDeployment');\n\nnew Plone(chart, 'my-plone', {\n  variant: PloneVariant.VOLTO,\n  backend: {\n    image: 'plone/plone-backend:6.1.3',\n    replicas: 3,\n  },\n  frontend: {\n    image: 'plone/plone-frontend:16.0.0',\n    replicas: 2,\n  },\n});\n\napp.synth();\n```\n\nGenerate Kubernetes manifests:\n```bash\ncdk8s synth\nkubectl apply -f dist/\n```\n\n## Documentation\n\n**📚 Full documentation:** https://bluedynamics.github.io/cdk8s-plone/\n\n- [Quick Start Tutorial](https://bluedynamics.github.io/cdk8s-plone/tutorials/01-quick-start.html)\n- [Configuration Reference](https://bluedynamics.github.io/cdk8s-plone/reference/configuration-options.html)\n- [Architecture Overview](https://bluedynamics.github.io/cdk8s-plone/explanation/architecture.html)\n- [Complete API Documentation](./API.md)\n\n## Examples\n\nComplete working examples are available in the [`examples/`](examples/) directory:\n\n- **[Volto](examples/volto/)** - Production-ready Plone 6 deployment with the React single-page frontend:\n  - Volto frontend (React) + REST API backend\n  - PostgreSQL with RelStorage (plain PostgreSQL or CloudNativePG)\n  - Varnish HTTP caching with kube-httpcache\n  - Ingress support (Traefik/Kong) with TLS\n\n- **[Blicca](examples/blicca/)** - Plone deployment with server-side rendering (formerly Classic UI):\n  - Blicca (backend renders the UI, no separate frontend)\n  - PostgreSQL with RelStorage (plain PostgreSQL or CloudNativePG)\n  - Varnish HTTP caching with kube-httpcache\n  - Ingress support (Traefik/Kong) with TLS\n  - Simpler architecture (no separate frontend)\n\n### Prometheus Metrics\n\nEnable Prometheus ServiceMonitor for metrics collection (requires Prometheus Operator):\n\n```typescript\nnew Plone(chart, 'my-plone', {\n  backend: {\n    servicemonitor: true,\n    metricsPath: '/metrics',  // optional, defaults to '/metrics'\n  },\n  frontend: {\n    servicemonitor: true,\n    metricsPort: 9090,  // optional, defaults to service port\n  },\n});\n```\n\n**Note:** You must instrument your Plone backend/frontend to expose metrics at the configured endpoint. For Volto/Node.js frontends, consider using [prom-client](https://www.npmjs.com/package/prom-client) or [express-prometheus-middleware](https://www.npmjs.com/package/express-prometheus-middleware).\n\n## Requirements\n- **kubectl** - [Install kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)\n- **Node.js 16+** (for TypeScript/JavaScript) - [Install Node.js](https://nodejs.org/)\n- **Python 3.8+** (for Python) - [Install Python](https://www.python.org/)\n- **Kubernetes cluster** (local or cloud)\n\nFor detailed setup instructions, see [Setup Prerequisites](https://bluedynamics.github.io/cdk8s-plone/how-to/setup-prerequisites.html).\n\n## Development\n\nThis project uses [Projen](https://projen.io/) for project management.\n\n```bash\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build\nnpm run build\n\n# Update project configuration\n# Edit .projenrc.ts, then run:\nnpx projen\n```\n\nFor detailed development instructions, see [CONTRIBUTING.md](./CONTRIBUTING.md) (if available).\n\n## Resources\n\n- [CDK8S Documentation](https://cdk8s.io/)\n- [Plone CMS](https://plone.org/)\n- [kube-httpcache](https://github.com/mittwald/kube-httpcache) (for HTTP caching)\n- [CloudNativePG](https://cloudnative-pg.io/) (for PostgreSQL management)\n\n## License\n\n[Apache 2.0](LICENSE)\n\n## Maintainers\n\nMaintained by [Blue Dynamics Alliance](https://github.com/bluedynamics)\n\n**Author:** Jens W. Klein (jk@kleinundpartner.at)\n"
   },
   "repository": {
     "type": "git",
@@ -2036,7 +2036,7 @@
         },
         "locationInModule": {
           "filename": "src/vinylcache.ts",
-          "line": 403
+          "line": 405
         },
         "parameters": [
           {
@@ -2062,7 +2062,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/vinylcache.ts",
-        "line": 396
+        "line": 398
       },
       "name": "PloneVinylCache",
       "properties": [
@@ -2075,7 +2075,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 401
+            "line": 403
           },
           "name": "vinylCacheServiceName",
           "type": {
@@ -2170,7 +2170,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 291
+            "line": 293
           },
           "name": "image",
           "optional": true,
@@ -2236,13 +2236,14 @@
           "abstract": true,
           "docs": {
             "default": "false",
+            "remarks": "When true this turns on operator metrics,\na ServiceMonitor, and the prometheus_varnish_exporter sidecar (required\nfor cache hit-ratio and backend-health metrics).",
             "stability": "stable",
-            "summary": "Enable Prometheus monitoring (metrics + ServiceMonitor)."
+            "summary": "Enable Prometheus monitoring."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 285
+            "line": 287
           },
           "name": "monitoring",
           "optional": true,
@@ -2261,7 +2262,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 304
+            "line": 306
           },
           "name": "nodeSelector",
           "optional": true,
@@ -2439,7 +2440,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 297
+            "line": 299
           },
           "name": "tolerations",
           "optional": true,
@@ -2462,7 +2463,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 376
+            "line": 378
           },
           "name": "vclBackendErrorSnippet",
           "optional": true,
@@ -2480,7 +2481,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 370
+            "line": 372
           },
           "name": "vclBackendFetchSnippet",
           "optional": true,
@@ -2517,7 +2518,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 310
+            "line": 312
           },
           "name": "vclDeliverSnippet",
           "optional": true,
@@ -2535,7 +2536,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 364
+            "line": 366
           },
           "name": "vclFiniSnippet",
           "optional": true,
@@ -2553,7 +2554,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 352
+            "line": 354
           },
           "name": "vclHashSnippet",
           "optional": true,
@@ -2571,7 +2572,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 316
+            "line": 318
           },
           "name": "vclHitSnippet",
           "optional": true,
@@ -2589,7 +2590,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 358
+            "line": 360
           },
           "name": "vclInitSnippet",
           "optional": true,
@@ -2607,7 +2608,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 322
+            "line": 324
           },
           "name": "vclMissSnippet",
           "optional": true,
@@ -2625,7 +2626,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 328
+            "line": 330
           },
           "name": "vclPassSnippet",
           "optional": true,
@@ -2643,7 +2644,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 334
+            "line": 336
           },
           "name": "vclPipeSnippet",
           "optional": true,
@@ -2661,7 +2662,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 346
+            "line": 348
           },
           "name": "vclPurgeSnippet",
           "optional": true,
@@ -2698,7 +2699,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/vinylcache.ts",
-            "line": 340
+            "line": 342
           },
           "name": "vclSynthSnippet",
           "optional": true,
@@ -3118,6 +3119,6 @@
       "symbolId": "src/vinylcache:VinylCacheToleration"
     }
   },
-  "version": "0.1.43",
-  "fingerprint": "5arI0nYpog888exkSdJCCYEorrET0rqyYrN36ZpI76s="
+  "version": "0.1.45",
+  "fingerprint": "mBEQ2jnl2myvLvZ/h7T7aPtv4ozEnU3u4Xp37uWCh0U="
 }

package/API.md

@@ -1992,7 +1992,7 @@ const ploneVinylCacheOptions: PloneVinylCacheOptions = { ... }
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.invalidation">invalidation</a></code> | <code>boolean</code> | Enable cache invalidation (PURGE, BAN, xkey). |
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.limitCpu">limitCpu</a></code> | <code>string</code> | CPU limit for Varnish pods. |
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.limitMemory">limitMemory</a></code> | <code>string</code> | Memory limit for Varnish pods. |
-| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.monitoring">monitoring</a></code> | <code>boolean</code> | Enable Prometheus monitoring (metrics + ServiceMonitor). |
+| <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.monitoring">monitoring</a></code> | <code>boolean</code> | Enable Prometheus monitoring. |
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.nodeSelector">nodeSelector</a></code> | <code>{[ key: string ]: string}</code> | Node selector labels for the Varnish pods. |
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.replicas">replicas</a></code> | <code>number</code> | Number of Varnish pod replicas. |
 | <code><a href="#@bluedynamics/cdk8s-plone.PloneVinylCacheOptions.property.requestCpu">requestCpu</a></code> | <code>string</code> | CPU request for Varnish pods. |
@@ -2123,7 +2123,11 @@ public readonly monitoring: boolean;
 - *Type:* boolean
 - *Default:* false
 
-Enable Prometheus monitoring (metrics + ServiceMonitor).
+Enable Prometheus monitoring.
+
+When true this turns on operator metrics,
+a ServiceMonitor, and the prometheus_varnish_exporter sidecar (required
+for cache hit-ratio and backend-health metrics).
 
 ---
 

package/README.md

@@ -75,15 +75,15 @@ kubectl apply -f dist/
 
 Complete working examples are available in the [`examples/`](examples/) directory:
 
-- **[Production Volto](examples/production-volto/)** - Production-ready Plone 6 deployment with the React single-page frontend:
+- **[Volto](examples/volto/)** - Production-ready Plone 6 deployment with the React single-page frontend:
   - Volto frontend (React) + REST API backend
-  - PostgreSQL with RelStorage (CloudNativePG or Bitnami)
+  - PostgreSQL with RelStorage (plain PostgreSQL or CloudNativePG)
   - Varnish HTTP caching with kube-httpcache
   - Ingress support (Traefik/Kong) with TLS
 
 - **[Blicca](examples/blicca/)** - Plone deployment with server-side rendering (formerly Classic UI):
   - Blicca (backend renders the UI, no separate frontend)
-  - PostgreSQL with RelStorage (CloudNativePG or Bitnami)
+  - PostgreSQL with RelStorage (plain PostgreSQL or CloudNativePG)
   - Varnish HTTP caching with kube-httpcache
   - Ingress support (Traefik/Kong) with TLS
   - Simpler architecture (no separate frontend)

package/documentation/sources/conf.py

@@ -77,43 +77,69 @@ mermaid_output_format = "raw"  # Use client-side rendering with mermaid.js
 # This makes absolute paths in logo_target work correctly with path prefix
 html_baseurl = "https://bluedynamics.github.io/cdk8s-plone"
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
+# The theme to use for HTML and HTML Help pages.
+# Shibuya, matching the rest of the Cloudbrine ecosystem.
 html_theme = "shibuya"
 
 html_theme_options = {
-    # Logo configuration - absolute path resolves relative to html_baseurl
-    "logo_target": "/",
-
-    # Color scheme - using cyan from brand palette (#00d4ff)
+    "logo_target": "/cdk8s-plone/",
     "accent_color": "cyan",
-
-    # Color mode - force dark mode (brand is dark-first cyberpunk aesthetic)
     "color_mode": "dark",
-
-    # Dark code blocks
     "dark_code": True,
-
-    # Navigation
-    "nav_links": [],
+    "nav_links": [
+        {
+            "title": "Ecosystem",
+            "url": "https://bluedynamics.github.io/zodb-pgjsonb/ecosystem.html",
+            "children": [
+                {
+                    "title": "Dashboard",
+                    "url": "https://bluedynamics.github.io/zodb-pgjsonb/ecosystem.html",
+                    "summary": "Overview of all packages",
+                },
+                {
+                    "title": "zodb-pgjsonb",
+                    "url": "https://bluedynamics.github.io/zodb-pgjsonb/",
+                    "summary": "PostgreSQL JSONB storage",
+                },
+                {
+                    "title": "zodb-json-codec",
+                    "url": "https://bluedynamics.github.io/zodb-json-codec/",
+                    "summary": "Rust pickle↔JSON transcoder",
+                },
+                {
+                    "title": "plone-pgcatalog",
+                    "url": "https://bluedynamics.github.io/plone-pgcatalog/",
+                    "summary": "PostgreSQL-backed catalog",
+                },
+                {
+                    "title": "plone-pgthumbor",
+                    "url": "https://bluedynamics.github.io/plone-pgthumbor/",
+                    "summary": "Thumbor image scaling",
+                },
+                {
+                    "title": "cdk8s-plone",
+                    "url": "https://bluedynamics.github.io/cdk8s-plone/",
+                    "summary": "Deploy Plone to Kubernetes",
+                },
+            ],
+        },
+        {
+            "title": "GitHub",
+            "url": "https://github.com/bluedynamics/cdk8s-plone",
+        },
+        {
+            "title": "PyPI",
+            "url": "https://pypi.org/project/cdk8s-plone/",
+        },
+        {
+            "title": "npm",
+            "url": "https://www.npmjs.com/package/@bluedynamics/cdk8s-plone",
+        },
+    ],
 }
 
-# Logo configuration (Shibuya uses different approach)
-html_logo = "_static/kup6s-icon-plone.svg"
+html_logo = "_static/logo.svg"
 
 # Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
+# relative to this directory.
 html_static_path = ["_static"]
-
-# Custom CSS files
-html_css_files = [
-    "brand-theme.css",  # Main brand theme (includes fonts, colors, cyberpunk design, icons)
-    "custom-icons.css",  # Custom icon styling for section headers
-]
-
-# Custom JavaScript files
-html_js_files = [
-    "logo-fix.js",  # Fix logo link for path prefix deployment
-]

package/documentation/sources/explanation/architecture.md

@@ -103,35 +103,35 @@ The library is published in multiple languages:
 
 ```mermaid
 graph TB
-    subgraph "External Access"
-        Client[Client/Browser]
+    subgraph "External access"
+        Client[Client / Browser]
         Ingress[Ingress Controller]
     end
 
-    subgraph "HTTP Cache Layer (Optional)"
-        Varnish[Varnish Cache<br/>kube-httpcache]
+    subgraph "Cache layer (optional)"
+        Varnish[Varnish<br/>PloneHttpcache or PloneVinylCache]
     end
 
-    subgraph "Plone Frontend (Volto)"
+    subgraph "Frontend (Volto variant only)"
         FrontendSvc[Frontend Service]
-        Frontend1[Frontend Pod 1]
-        Frontend2[Frontend Pod 2]
+        Frontend1[Frontend Pod]
+        Frontend2[Frontend Pod]
     end
 
-    subgraph "Plone Backend (API)"
+    subgraph "Backend (REST API for Volto, HTML for Blicca)"
         BackendSvc[Backend Service]
-        Backend1[Backend Pod 1]
-        Backend2[Backend Pod 2]
-        Backend3[Backend Pod 3]
+        Backend1[Backend Pod]
+        Backend2[Backend Pod]
     end
 
-    subgraph "Data Layer"
-        DB[(External Database<br/>PostgreSQL/MySQL/Oracle<br/>with RelStorage)]
+    subgraph "Data layer"
+        DB[(PostgreSQL<br/>with RelStorage)]
     end
 
     Client --> Ingress
     Ingress --> Varnish
-    Varnish -.cache miss.-> FrontendSvc
+    Varnish -.Volto: cache miss.-> FrontendSvc
+    Varnish -.Blicca: cache miss.-> BackendSvc
     Varnish -.invalidation.-> BackendSvc
 
     FrontendSvc --> Frontend1
@@ -142,11 +142,9 @@ graph TB
 
     BackendSvc --> Backend1
     BackendSvc --> Backend2
-    BackendSvc --> Backend3
 
     Backend1 --> DB
     Backend2 --> DB
-    Backend3 --> DB
 ```
 
 ## Component responsibilities

package/documentation/sources/explanation/cdk8s-workflow.md

@@ -0,0 +1,66 @@
+---
+myst:
+  html_meta:
+    "description": "How cdk8s-plone fits into the cdk8s workflow: constructs, synthesis to Kubernetes manifests, and applying them by hand or through GitOps."
+    "property=og:description": "How cdk8s-plone fits into the cdk8s workflow: constructs, synthesis to Kubernetes manifests, and applying them by hand or through GitOps."
+    "property=og:title": "About the cdk8s workflow"
+    "keywords": "Plone, cdk8s, Kubernetes, synth, constructs, GitOps, ArgoCD, Helm"
+---
+
+# About the cdk8s workflow
+
+This page explains where `cdk8s-plone` sits in the cdk8s workflow and why that workflow looks the way it does.
+It is background reading, not a set of steps; for the steps, see {doc}`/tutorials/01-quick-start`.
+
+## Code, synth, apply
+
+[cdk8s](https://cdk8s.io/) is a framework for defining Kubernetes resources in a general-purpose programming language.
+You write TypeScript or Python that constructs objects, run a synthesis step, and get plain Kubernetes YAML.
+Nothing about cdk8s talks to a cluster: it is a manifest generator.
+
+The workflow has three distinct phases, and keeping them apart explains most of how cdk8s-plone behaves.
+First you write code that instantiates constructs inside an `App` and one or more `Chart` objects.
+Then you run `cdk8s synth`, which evaluates that code and writes Kubernetes manifests into the `dist/` directory.
+Finally you apply those manifests to a cluster, either with `kubectl apply` or through a GitOps controller.
+
+The separation matters because the manifests are an ordinary, reviewable artifact.
+You can read the YAML, diff it across changes, and run policy checks on it before anything reaches the cluster.
+
+## Where cdk8s-plone fits
+
+`cdk8s-plone` is a construct library, not an application you run.
+You compose its constructs, mainly `Plone` and one of the cache constructs, inside your own cdk8s app.
+A construct is a reusable building block: `Plone` expands into the Deployments, Services, and optional PodDisruptionBudget and ServiceMonitor that a Plone site needs, with production-minded defaults you can override.
+
+This is the same idea as a Helm chart or a Kustomize base, but expressed in code rather than templated YAML.
+Because the inputs are typed options rather than free-form values, your editor and the compiler catch mistakes before synthesis, and the {doc}`API reference </reference/api/index>` is generated from those types.
+
+## Synthesis time versus apply time
+
+The two cache constructs illustrate the phase distinction well, because they resolve at different times.
+
+`PloneHttpcache` renders the mittwald kube-httpcache Helm chart during synthesis.
+It shells out to the `helm` CLI, so `helm` must be present where you run `cdk8s synth`, and the chart's resources land in your `dist/` output as ordinary manifests.
+
+`PloneVinylCache` instead emits a `VinylCache` custom resource.
+That resource does nothing on its own; the cloud-vinyl operator reconciles it at apply time and creates the underlying Varnish deployment in the cluster.
+The work happens later, and in a different place, than the synthesis that produced the manifest.
+
+Neither approach is universally better.
+Rendering at synthesis keeps everything in one reviewable artifact, while delegating to an operator keeps the cluster as the source of truth and lets the operator manage the cache over its lifetime.
+For the practical trade-offs between the two caches, see {doc}`architecture`.
+
+## Applying by hand or through GitOps
+
+Because synthesis produces plain YAML, you can apply it however you already deploy Kubernetes resources.
+A small project applies `dist/` directly with `kubectl`.
+A larger one commits the synthesized manifests to a repository and lets a GitOps controller such as Argo CD or Flux reconcile them, so the cluster always matches what is in version control.
+
+A common middle path runs `cdk8s synth` in continuous integration and publishes the result, so the synthesis is reproducible and the applied manifests are auditable.
+In every case the cdk8s-plone code stays the single definition of the deployment, and the manifests are a derived, inspectable product of it.
+
+## See also
+
+- {doc}`architecture` — the components a `Plone` construct creates and how they relate.
+- {doc}`/tutorials/01-quick-start` — the workflow applied end to end.
+- [cdk8s documentation](https://cdk8s.io/docs/latest/) — the framework this builds on.

package/documentation/sources/explanation/index.md

@@ -7,11 +7,6 @@ myst:
     "keywords": "Plone, cdk8s, Kubernetes, architecture, design, concepts"
 ---
 
-```{image} ../_static/kup6s-icon-explanation.svg
-:align: center
-:class: section-icon-large
-```
-
 # Explanation
 
 **Understanding-oriented discussion of concepts, architecture, and design decisions.**
@@ -27,30 +22,9 @@ titlesonly: true
 ---
 features
 architecture
+cdk8s-workflow
 ```
 
-## Key topics
-
-*This section will explain:*
-- Plone architecture and component relationships
-- Backend and Frontend integration
-- Storage architecture for Plone data
-- CDK8S construct patterns and best practices
-- Configuration management strategies
-
-*Future topics:*
-- Security considerations
-- Scaling and high availability considerations
-- Performance optimization
-
-## Design decisions
-
-*This section will document:*
-- Why certain defaults were chosen
-- Trade-offs in configuration approaches
-- Integration strategies with external services
-- Testing philosophy
-
 ---
 
 **Ready to get started?** Jump into the [Tutorials](../tutorials/index.md) for hands-on lessons.

package/documentation/sources/how-to/backup-and-restore.md

@@ -0,0 +1,107 @@
+---
+myst:
+  html_meta:
+    "description": "Back up and restore a cdk8s-plone deployment by protecting the PostgreSQL database that holds the Plone content."
+    "property=og:description": "Back up and restore a cdk8s-plone deployment by protecting the PostgreSQL database that holds the Plone content."
+    "property=og:title": "Back up and restore"
+    "keywords": "Plone, cdk8s, Kubernetes, backup, restore, PostgreSQL, CloudNativePG, pg_dump, RelStorage"
+---
+
+# Back up and restore
+
+This guide shows you how to back up and restore a Plone deployment.
+
+`cdk8s-plone` does not run backups.
+It deploys the application; your data lives in PostgreSQL, so you protect the database.
+
+## What to back up
+
+Plone stores its content in the ZODB, which this stack keeps in PostgreSQL through RelStorage.
+A backup of the PostgreSQL database is a backup of your site content.
+
+If your configuration keeps blobs on a separate volume rather than in the database, back up that volume as well.
+The application images and Kubernetes manifests are reproducible from your `cdk8s-plone` code, so they do not need a backup.
+
+## Back up a CloudNativePG database
+
+CloudNativePG performs scheduled and on-demand backups to object storage through its own resources.
+
+Configure object-store backups on the `Cluster`, then schedule them with a `ScheduledBackup`:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: ScheduledBackup
+metadata:
+  name: plone-daily
+spec:
+  schedule: "0 0 2 * * *"
+  backupOwnerReference: self
+  cluster:
+    name: <cluster-name>
+```
+
+Take an immediate backup with a `Backup` resource:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Backup
+metadata:
+  name: plone-manual
+spec:
+  cluster:
+    name: <cluster-name>
+```
+
+See the [CloudNativePG backup documentation](https://cloudnative-pg.io/documentation/current/backup/) for object-store credentials and retention policies.
+
+## Back up a plain or standalone database
+
+For a database without an operator, take a logical dump with `pg_dump` from a client pod:
+
+```shell
+kubectl exec -n <namespace> <postgres-pod> -- \
+  pg_dump -U <user> -d <database> -Fc -f /tmp/plone.dump
+kubectl cp <namespace>/<postgres-pod>:/tmp/plone.dump ./plone.dump
+```
+
+Run this on a schedule with a `CronJob`, and store the dump off-cluster.
+
+## Restore
+
+For CloudNativePG, create a new `Cluster` with a `bootstrap.recovery` stanza that points at a backup, following the [CloudNativePG recovery guide](https://cloudnative-pg.io/documentation/current/recovery/).
+
+For a logical dump, restore into an empty database with `pg_restore`:
+
+```shell
+kubectl cp ./plone.dump <namespace>/<postgres-pod>:/tmp/plone.dump
+kubectl exec -n <namespace> <postgres-pod> -- \
+  pg_restore -U <user> -d <database> --clean --if-exists /tmp/plone.dump
+```
+
+After the database is restored, restart the backend so it reconnects:
+
+```shell
+kubectl rollout restart deployment/<backend-deployment> -n <namespace>
+```
+
+```{warning}
+Restoring overwrites the current database.
+Take a fresh backup before you restore, so you can return to the current state if the restore goes wrong.
+```
+
+## Verify
+
+Confirm a backup completed and is recent:
+
+```shell
+kubectl get backup -n <namespace>
+kubectl get scheduledbackup -n <namespace>
+```
+
+After a restore, open the site and confirm your content is present.
+
+## See also
+
+- {doc}`/how-to/upgrade-and-rollout` — back up before a risky upgrade.
+- {doc}`/explanation/architecture` — where Plone stores its data.
+- [CloudNativePG documentation](https://cloudnative-pg.io/documentation/current/) — backup, recovery, and retention.