@bluedynamics/cdk8s-plone 0.1.10 → 0.1.11

package/.claude/claude.md

@@ -0,0 +1,39 @@
+# CDK8S Best Practices
+
+## Naming Convention Rule
+
+**NEVER use `metadata.name` in CDK8S constructs.**
+
+- CDK8S automatically generates unique names for all Kubernetes resources
+- Always let CDK8S decide the name and reference it via the construct's `name` property
+- Manual names can cause conflicts and break CDK8S's naming conventions
+
+### ❌ Wrong:
+```typescript
+const db = new cnpg.Cluster(this, 'db', {
+    metadata: {
+        name: 'my-cluster',  // NEVER do this!
+    },
+    spec: { /* ... */ }
+});
+this.dbServiceName = 'my-cluster-rw';  // Wrong: hard-coded name
+```
+
+### ✅ Correct:
+```typescript
+const db = new cnpg.Cluster(this, 'db', {
+    metadata: {
+        // No name property - let CDK8S generate it
+        labels: { /* ... */ }
+    },
+    spec: { /* ... */ }
+});
+// Reference the generated name
+this.dbServiceName = `${db.name}-rw`;
+```
+
+This ensures:
+- No naming conflicts
+- Proper CDK8S resource tracking
+- Consistent naming across the application
+- Easy refactoring and composition

package/.claude/settings.local.json

@@ -0,0 +1,31 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(echo $?)",
+      "Bash(find:*)",
+      "Bash(gh issue view:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh run list:*)",
+      "Bash(gh run view:*)",
+      "Bash(git add:*)",
+      "Bash(git checkout:*)",
+      "Bash(git cherry-pick:*)",
+      "Bash(git commit:*)",
+      "Bash(git log:*)",
+      "Bash(git ls-tree:*)",
+      "Bash(git push)",
+      "Bash(git stash:*)",
+      "Bash(make docs:*)",
+      "Bash(npm install:*)",
+      "Bash(npm run compile:*)",
+      "Bash(npm test:*)",
+      "Bash(npx projen:*)",
+      "Bash(nvm use:*)",
+      "Bash(source:*)",
+      "Bash(yarn install)",
+      "Bash(npm run test-update:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/.jsii

@@ -7,7 +7,7 @@
     ]
   },
   "dependencies": {
-    "cdk8s": "^2.70.27",
+    "cdk8s": "^2.70.28",
     "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 (modern React frontend) and Classic UI\n- 📦 High availability with configurable replicas\n- ⚡ Optional Varnish HTTP caching layer\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\nSee the [cdk8s-plone-example](https://github.com/bluedynamics/cdk8s-plone-example) repository for complete working examples.\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- [Example Project](https://github.com/bluedynamics/cdk8s-plone-example)\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 (modern React frontend) and Classic UI\n- 📦 High availability with configurable replicas\n- ⚡ Optional Varnish HTTP caching layer\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 modern UI:\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- **[Classic UI](examples/classic-ui/)** - Traditional Plone deployment with server-side rendering:\n  - Classic UI (traditional Plone interface)\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"
   },
   "repository": {
     "type": "git",
@@ -1314,6 +1314,6 @@
       "symbolId": "src/plone:PloneVariant"
     }
   },
-  "version": "0.1.10",
-  "fingerprint": "yv5KDYY6NCn6j/9ok2cN64Q9Oj+jMBev8qebF6rwRos="
+  "version": "0.1.11",
+  "fingerprint": "vSBaDJVhNiduiyG/9IONZopUT6TCBilfaudzkMnJ7ec="
 }

package/README.md

@@ -73,7 +73,20 @@ kubectl apply -f dist/
 
 ## Examples
 
-See the [cdk8s-plone-example](https://github.com/bluedynamics/cdk8s-plone-example) repository for complete working examples.
+Complete working examples are available in the [`examples/`](examples/) directory:
+
+- **[Production Volto](examples/production-volto/)** - Production-ready Plone 6 deployment with modern UI:
+  - Volto frontend (React) + REST API backend
+  - PostgreSQL with RelStorage (CloudNativePG or Bitnami)
+  - Varnish HTTP caching with kube-httpcache
+  - Ingress support (Traefik/Kong) with TLS
+
+- **[Classic UI](examples/classic-ui/)** - Traditional Plone deployment with server-side rendering:
+  - Classic UI (traditional Plone interface)
+  - PostgreSQL with RelStorage (CloudNativePG or Bitnami)
+  - Varnish HTTP caching with kube-httpcache
+  - Ingress support (Traefik/Kong) with TLS
+  - Simpler architecture (no separate frontend)
 
 ### Prometheus Metrics
 
@@ -128,7 +141,7 @@ For detailed development instructions, see [CONTRIBUTING.md](./CONTRIBUTING.md)
 - [CDK8S Documentation](https://cdk8s.io/)
 - [Plone CMS](https://plone.org/)
 - [kube-httpcache](https://github.com/mittwald/kube-httpcache) (for HTTP caching)
-- [Example Project](https://github.com/bluedynamics/cdk8s-plone-example)
+- [CloudNativePG](https://cloudnative-pg.io/) (for PostgreSQL management)
 
 ## License
 

package/documentation/sources/how-to/deploy-classic-ui.md

@@ -0,0 +1,322 @@
+# Deploy Classic UI Example
+
+This guide shows you how to deploy the Classic UI example to your Kubernetes cluster.
+
+## What You'll Deploy
+
+The [Classic UI example](https://github.com/bluedynamics/cdk8s-plone/tree/main/examples/classic-ui) provides traditional Plone with server-side rendering:
+
+- **Plone 6.1 Classic UI** (traditional interface, no separate frontend)
+- **PostgreSQL** with RelStorage (CloudNativePG or Bitnami)
+- **Varnish HTTP caching** with kube-httpcache
+- **Ingress** with TLS (Traefik or Kong)
+- **Simpler architecture** (single backend service)
+
+## Classic UI vs Volto
+
+| Feature | Classic UI | Volto |
+|---------|-----------|-------|
+| **Architecture** | Single backend | Frontend + Backend |
+| **Rendering** | Server-side | Client-side (React) |
+| **Deployment** | Simpler | More complex |
+| **Best for** | Migrations, intranets | Modern projects |
+
+:::{tip}
+Choose Classic UI if you're migrating from older Plone versions or need specific Classic UI add-ons. For new projects, consider [Volto](deploy-production-volto.md).
+:::
+
+## Prerequisites
+
+Same as the [Production Volto guide](deploy-production-volto.md#prerequisites), you need:
+
+- Ingress controller (Traefik or Kong)
+- cert-manager
+- kube-httpcache operator
+- PostgreSQL operator (CloudNativePG or Bitnami)
+
+See [Setup Prerequisites](setup-prerequisites.md) for detailed instructions.
+
+## Step 1: Get the Example
+
+```bash
+git clone https://github.com/bluedynamics/cdk8s-plone.git
+cd cdk8s-plone/examples/classic-ui
+```
+
+## Step 2: Install Dependencies
+
+```bash
+npm install
+```
+
+## Step 3: Import CRDs
+
+```bash
+npm run import
+```
+
+## Step 4: Configure Environment
+
+Create `.env` from the example:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```bash
+# Your domains
+DOMAIN_CACHED=plone.example.com
+DOMAIN_UNCACHED=plone-test.example.com
+DOMAIN_MAINTENANCE=plone-admin.example.com
+
+# Your cert-manager ClusterIssuer
+CLUSTER_ISSUER=letsencrypt-prod
+
+# Optional: Custom backend image
+#PLONE_BACKEND_IMAGE=plone/plone-backend:6.1.3
+
+# Database: 'bitnami' or 'cloudnativepg'
+DATABASE=cloudnativepg
+```
+
+:::{note}
+Classic UI only needs one image (backend). There's no frontend image configuration.
+:::
+
+## Step 5: Generate Manifests
+
+```bash
+npm run synth
+```
+
+Creates `dist/plone-classic.k8s.yaml` (~27 KB, smaller than Volto's 32 KB).
+
+## Step 6: Review Manifests
+
+```bash
+# Count resources
+grep "^kind:" dist/plone-classic.k8s.yaml | sort | uniq -c
+
+# Dry run
+kubectl apply --dry-run=client -f dist/plone-classic.k8s.yaml
+```
+
+## Step 7: Deploy
+
+```bash
+kubectl apply -f dist/plone-classic.k8s.yaml
+```
+
+Or to a specific namespace:
+
+```bash
+kubectl apply -f dist/plone-classic.k8s.yaml -n plone
+```
+
+## Step 8: Monitor Deployment
+
+```bash
+# Watch pods
+kubectl get pods -l app.kubernetes.io/part-of=plone -w
+
+# Wait for ready
+kubectl wait --for=condition=ready pod \
+  -l app.kubernetes.io/part-of=plone \
+  --timeout=300s
+```
+
+:::{note}
+Classic UI deploys fewer pods than Volto (no frontend pods).
+:::
+
+## Step 9: Verify Services
+
+```bash
+kubectl get svc -l app.kubernetes.io/part-of=plone
+```
+
+You should see:
+- `plone-backend` (Classic UI service)
+- `plone-httpcache` (Varnish cache)
+- Database service
+
+## Step 10: Check Ingress
+
+```bash
+kubectl get ingress
+kubectl get certificate
+```
+
+## Step 11: Access Your Site
+
+Once DNS and TLS are ready:
+
+- **Public (cached)**: https://plone.example.com
+- **Testing (uncached)**: https://plone-test.example.com
+- **Maintenance**: https://plone-admin.example.com
+
+### Create Plone Site
+
+1. Access maintenance domain: https://plone-admin.example.com
+2. Click "Create a new Plone site"
+3. Configure:
+   - **Site ID**: `Plone`
+   - **Title**: Your site name
+   - **Language**: Select language
+   - **Add-ons**: Choose Classic UI add-ons
+4. Click "Create Plone Site"
+
+## Key Differences from Volto
+
+### Architecture
+
+Classic UI routing is simpler - all traffic goes to the backend:
+
+```
+Traffic → Ingress → Varnish → Plone Backend (Classic UI)
+```
+
+Compared to Volto:
+
+```
+Traffic → Ingress → {Varnish → Frontend, Backend}
+```
+
+### Ingress Routes
+
+Classic UI uses virtual host rewriting for direct backend access:
+
+- **Cached**: Routes through Varnish to backend
+- **Uncached**: Direct to backend with VirtualHostBase rewrite
+- **Maintenance**: Direct backend access with VirtualHostRoot
+
+### No Frontend Service
+
+The manifest doesn't include:
+- Frontend deployment
+- Frontend service
+- Frontend-to-backend internal routing
+
+This makes the deployment ~15% smaller and simpler to manage.
+
+## Troubleshooting
+
+### Backend Not Starting
+
+Check backend logs:
+
+```bash
+kubectl logs -l app.kubernetes.io/name=plone-backend -f
+```
+
+Common issues:
+- Database connection failures
+- Memory limits too low
+- Image pull errors
+
+### Classic UI Interface Not Loading
+
+1. Check if backend pods are running:
+   ```bash
+   kubectl get pods -l app.kubernetes.io/name=plone-backend
+   ```
+
+2. Verify virtual host rewriting in ingress:
+   ```bash
+   kubectl describe ingress
+   ```
+
+3. Check Varnish routing:
+   ```bash
+   kubectl logs -l app.kubernetes.io/name=plone-httpcache
+   ```
+
+### Add-on Compatibility
+
+Some add-ons are Volto-specific. For Classic UI:
+- Use Classic UI themes (not Volto themes)
+- Check add-on compatibility with Plone 6 Classic UI
+- Avoid Volto-specific frontend add-ons
+
+## Migrating to Volto
+
+If you want to migrate from Classic UI to Volto later:
+
+1. Keep your backend deployment (same configuration)
+2. Add Volto frontend from the [Volto example](deploy-production-volto.md)
+3. Update ingress to route to frontend
+4. Both UIs can run simultaneously during migration
+
+See the [Production Volto deployment guide](deploy-production-volto.md) for details.
+
+## Customization
+
+### Backend Configuration
+
+Edit `main.ts` to customize:
+
+```typescript
+const plone = new Plone(this, 'plone', {
+  variant: PloneVariant.CLASSICUI,
+  backend: {
+    image: 'plone/plone-backend:6.1.3',
+    replicas: 2,
+    limitMemory: '1Gi',
+    limitCpu: '1000m',
+    environment: env,
+  },
+})
+```
+
+### Varnish Caching
+
+Edit `config/varnish.tpl.vcl` for caching rules specific to Classic UI.
+
+Classic UI VCL is simpler than Volto's - all traffic routes to one backend.
+
+## Scaling
+
+Scale backend replicas:
+
+```typescript
+backend: {
+  replicas: 3,  // Increase for higher traffic
+}
+```
+
+Then:
+```bash
+npm run synth
+kubectl apply -f dist/plone-classic.k8s.yaml
+```
+
+## Performance
+
+Classic UI performance characteristics:
+
+- **Server-side rendering** can be slower than Volto's client-side
+- **Varnish caching** is critical for performance
+- **Database** is the main bottleneck (use CloudNativePG for HA)
+- **Fewer HTTP requests** than Volto (no separate frontend API calls)
+
+## Cleanup
+
+```bash
+kubectl delete -f dist/plone-classic.k8s.yaml
+```
+
+## Next Steps
+
+- Add [Prometheus monitoring](../reference/configuration-options.md#monitoring)
+- Configure [CloudNativePG backups](https://cloudnative-pg.io/documentation/)
+- Customize [Classic UI theme](https://6.docs.plone.org/classic-ui/theming.html)
+- Set up [content migration](https://6.docs.plone.org/install/upgrade-guide.html)
+
+## See Also
+
+- [Deploy Production Volto](deploy-production-volto.md) - For modern React UI
+- [Setup Prerequisites](setup-prerequisites.md) - Cluster requirements
+- [Configuration Options](../reference/configuration-options.md) - API reference
+- [Plone 6 Classic UI Documentation](https://6.docs.plone.org/classic-ui/)