@bluedynamics/cdk8s-plone 0.1.9 → 0.1.11

package/examples/classic-ui/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "cdk8s-plone-example-classic-ui",
+  "version": "1.0.0",
+  "description": "Classic UI Plone deployment example using cdk8s-plone",
+  "main": "main.js",
+  "types": "main.ts",
+  "license": "Apache-2.0",
+  "private": true,
+  "scripts": {
+    "import": "cdk8s import",
+    "synth": "cdk8s synth",
+    "compile": "tsc --build",
+    "watch": "tsc --build -w",
+    "test": "jest",
+    "test-update": "jest --updateSnapshot",
+    "build": "npm run compile && npm run test && npm run synth",
+    "upgrade": "npm i cdk8s@latest cdk8s-cli@latest",
+    "upgrade:next": "npm i cdk8s@next cdk8s-cli@next"
+  },
+  "dependencies": {
+    "@bluedynamics/cdk8s-plone": "../../",
+    "cdk8s": "^2.70.27",
+    "cdk8s-plus-30": "^2.4.10",
+    "constructs": "^10.4.2",
+    "dotenv": "^16.4.5"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^18.19.64",
+    "cdk8s-cli": "^2.198.268",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

package/examples/classic-ui/postgres.bitnami.ts

@@ -0,0 +1,49 @@
+import { Construct } from 'constructs';
+import { Helm } from 'cdk8s';
+
+export class PGBitnamiChart extends Construct {
+    public readonly dbServiceName: string;
+
+    constructor(scope: Construct, id: string) {
+        super(scope, id);
+
+        const dbname = 'plone';
+        const dbuser = 'plone';
+        const dbpass = 'admin@plone';
+
+        const db = new Helm(this, 'db', {
+            chart: 'postgresql',
+            repo: 'https://charts.bitnami.com/bitnami',
+            // XXX: in fact I do not want a namespace here.
+            // I want to use the passed in with kubectl apply.
+            // need to figure out how to achieve this. Could be bitnami specific.
+            namespace: 'plone',
+            values: {
+                'commonLabels': { 'app.kubernetes.io/part-of': 'plone' },
+                'global': {
+                    'postgresql': {
+                        'postgresPassword': 'admin@postgres',
+                        'username': dbuser,
+                        'password': dbpass,
+                        'database': dbname,
+                    },
+                },
+                'auth': {
+                    'username': dbuser,
+                    'password': dbpass,
+                    'database': dbname,
+                }
+            }
+        });
+        const dbService = db.apiObjects.find(construct => {
+            if ((construct.kind === 'Service') && (construct.metadata.name?.endsWith('postgresql'))) {
+                return construct.name;
+            }
+            return undefined;
+        });
+        if (dbService === undefined) {
+            throw new Error('Could not find postgresql service');
+        }
+        this.dbServiceName = dbService.name;
+    }
+};

package/examples/classic-ui/postgres.cloudnativepg.ts

@@ -0,0 +1,63 @@
+import { Construct } from 'constructs';
+import * as cnpg from './imports/postgresql.cnpg.io'
+
+export class PGCloudNativePGChart extends Construct {
+    // uses the CloudNativePG operator
+    // https://cloudnative-pg.io/
+
+    public readonly dbServiceName: string;
+    public readonly clusterName: string;
+
+    constructor(scope: Construct, id: string) {
+        super(scope, id);
+
+        const db = new cnpg.Cluster(
+            this,
+            'db',
+            {
+                metadata: {
+                    labels: {
+                        'app.kubernetes.io/name': 'plone-postgresql',
+                        'app.kubernetes.io/instance': 'postgresql',
+                        'app.kubernetes.io/component': 'database',
+                        'app.kubernetes.io/part-of': 'plone',
+                    }
+                },
+                spec: {
+                    instances: 2,
+                    postgresql: {
+                        parameters: {
+                            'max_connections': '200',
+                            'shared_buffers': '256MB',
+                            'effective_cache_size': '1GB',
+                            'maintenance_work_mem': '64MB',
+                            'checkpoint_completion_target': '0.9',
+                            'wal_buffers': '16MB',
+                            'default_statistics_target': '100',
+                            'random_page_cost': '1.1',
+                            'effective_io_concurrency': '200',
+                            'work_mem': '4MB',
+                            'min_wal_size': '1GB',
+                            'max_wal_size': '4GB',
+                        }
+                    },
+                    bootstrap: {
+                        initdb: {
+                            database: 'plone',
+                            owner: 'plone',
+                        }
+                    },
+                    storage: {
+                        size: '10Gi',
+                    },
+                }
+            }
+        );
+
+        // CloudNativePG creates a service named {cluster-name}-rw for read-write access
+        // CloudNativePG creates a secret named {cluster-name}-app with username/password
+        // Use the CDK8S-generated name, never hard-code metadata.name
+        this.clusterName = db.name;
+        this.dbServiceName = `${db.name}-rw`;
+    }
+}

package/examples/production-volto/.env.example

@@ -0,0 +1,20 @@
+# This file contains the environment variables for the project.
+# Copy this file to .env and adjust the values as needed.
+# The variables are loaded when "cdk8s synth" is called.
+
+# Configure domain names
+DOMAIN_CACHED=plone.example.com
+DOMAIN_UNCACHED=plone-test.example.com
+DOMAIN_MAINTENANCE=plone-admin.example.com
+
+# Cluster issuer to use (cert-manager ClusterIssuer for TLS certificates)
+CLUSTER_ISSUER=letsencrypt-prod
+
+# Configure the Plone images to use
+# Leave commented to use defaults (official Plone images)
+#PLONE_FRONTEND_IMAGE=plone/plone-frontend:latest
+#PLONE_BACKEND_IMAGE=plone/plone-backend:6.1.3
+
+# Configure database backend
+# Options: 'bitnami' (default, simple) or 'cloudnativepg' (production-ready)
+DATABASE=cloudnativepg

package/examples/production-volto/README.md

@@ -0,0 +1,295 @@
+# Production Volto Example
+
+This example demonstrates a **production-ready Plone deployment** using the [@bluedynamics/cdk8s-plone](https://www.npmjs.com/package/@bluedynamics/cdk8s-plone) TypeScript package.
+
+## Features
+
+This example includes:
+
+- **Plone 6.1 with Volto** (React frontend + REST API backend)
+- **PostgreSQL with RelStorage** - Choose between:
+  - [CloudNativePG](https://cloudnative-pg.io/) (CNCF project, production-ready with HA)
+  - [Bitnami PostgreSQL](https://github.com/bitnami/charts/tree/main/bitnami/postgresql) Helm chart (simple, for dev/testing)
+- **HTTP Caching with Varnish** - Using [kube-httpcache](https://github.com/mittwald/kube-httpcache)
+- **Ingress** - Supports both Traefik and Kong with TLS/cert-manager
+- **Three access domains**:
+  - Cached (public, via Varnish)
+  - Uncached (testing, direct to frontend)
+  - Maintenance (backend API access)
+
+## Prerequisites
+
+### Node.js Setup
+
+Configure Node.js:
+```bash
+nvm use lts/*
+```
+
+Install dependencies:
+```bash
+npm install
+```
+
+### Kubernetes Cluster Requirements
+
+Your cluster needs:
+
+1. **PostgreSQL Operator** (choose one):
+   - **CloudNativePG** (recommended for production):
+     ```bash
+     kubectl apply -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.24/releases/cnpg-1.24.0.yaml
+     ```
+   - **Bitnami** (no operator needed, uses Helm):
+     - Requires namespace `plone` to exist: `kubectl create namespace plone`
+
+2. **Ingress Controller** (choose one):
+   - Traefik v3 with CRDs installed
+   - Kong Gateway
+
+3. **cert-manager** (for TLS certificates):
+   ```bash
+   kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.0/cert-manager.yaml
+   ```
+
+4. **kube-httpcache Operator** (for Varnish caching):
+   ```bash
+   kubectl apply -f https://github.com/mittwald/kube-httpcache/releases/latest/download/kube-httpcache.yaml
+   ```
+
+## Usage
+
+### 1. Import CRDs
+
+Import the required Custom Resource Definitions:
+
+```bash
+npm run import
+```
+
+This will generate TypeScript bindings in `./imports/` for:
+- Kubernetes core API
+- Traefik IngressRoute CRDs
+- CloudNativePG Cluster CRDs
+
+### 2. Configure Environment
+
+Create a `.env` file (copy from `.env.example`):
+
+```bash
+# Domain names
+DOMAIN_CACHED=plone.example.com
+DOMAIN_UNCACHED=plone-test.example.com
+DOMAIN_MAINTENANCE=plone-admin.example.com
+
+# TLS certificate issuer (cert-manager ClusterIssuer)
+CLUSTER_ISSUER=letsencrypt-prod
+
+# Plone images (defaults to official images if not set)
+PLONE_BACKEND_IMAGE=plone/plone-backend:6.1.3
+PLONE_FRONTEND_IMAGE=plone/plone-frontend:latest
+
+# Database backend: 'bitnami' (default) or 'cloudnativepg'
+DATABASE=cloudnativepg
+```
+
+### 3. Generate Kubernetes Manifests
+
+```bash
+npm run synth
+```
+
+This generates `dist/plone-example.k8s.yaml` with all Kubernetes resources.
+
+### 4. Deploy to Kubernetes
+
+```bash
+kubectl apply -f dist/plone-example.k8s.yaml
+```
+
+Or deploy to a specific namespace:
+```bash
+kubectl apply -f dist/plone-example.k8s.yaml -n plone
+```
+
+## Database Options
+
+### CloudNativePG (Production)
+
+**Pros:**
+- CNCF Sandbox project (Cloud Native Computing Foundation)
+- Built-in high availability (2 instances)
+- Automated backups and point-in-time recovery
+- Monitoring and observability
+- Connection pooling support
+- Modern, actively maintained
+
+**Configuration:**
+```bash
+DATABASE=cloudnativepg
+```
+
+**Secrets:** CloudNativePG automatically creates a secret `plone-postgresql-app` with:
+- `username` - Database user
+- `password` - Database password
+
+### Bitnami PostgreSQL (Development/Testing)
+
+**Pros:**
+- No operator required
+- Simple setup
+- Good for development and testing
+- Helm-based deployment
+
+**Cons:**
+- Requires namespace `plone` to be pre-created
+- No built-in HA features
+- Less suitable for production
+
+**Configuration:**
+```bash
+DATABASE=bitnami
+```
+
+## Architecture
+
+```
+                    ┌─────────────────┐
+                    │   cert-manager  │
+                    │  (TLS Certs)    │
+                    └────────┬────────┘
+                             │
+┌──────────────────┐    ┌────▼────────────┐
+│   External       │───▶│    Ingress      │
+│   Traffic        │    │ (Traefik/Kong)  │
+└──────────────────┘    └────┬─────┬──────┘
+                             │     │
+              ┌──────────────┘     └──────────────┐
+              │                                    │
+    ┌─────────▼─────────┐              ┌─────────▼─────────┐
+    │  HTTP Cache       │              │  Plone Frontend   │
+    │  (Varnish)        │              │  (Volto/React)    │
+    └─────────┬─────────┘              └─────────┬─────────┘
+              │                                    │
+              └──────────────┬─────────────────────┘
+                             │
+                   ┌─────────▼─────────┐
+                   │  Plone Backend    │
+                   │  (Python/Zope)    │
+                   └─────────┬─────────┘
+                             │
+                   ┌─────────▼─────────┐
+                   │   PostgreSQL      │
+                   │  (RelStorage)     │
+                   └───────────────────┘
+```
+
+## Development
+
+### Build and Test
+
+```bash
+# Compile TypeScript
+npm run compile
+
+# Run tests
+npm test
+
+# Update test snapshots
+npm run test-update
+
+# Full build (compile + test + synth)
+npm run build
+```
+
+### Watch Mode
+
+```bash
+npm run watch
+```
+
+## Customization
+
+### Changing Plone Configuration
+
+Edit [main.ts](main.ts) to customize:
+- RelStorage settings (cache sizes, blob mode)
+- Resource limits
+- Environment variables
+- Number of replicas
+
+### Modifying Varnish Caching
+
+Edit [config/varnish.tpl.vcl](config/varnish.tpl.vcl) to customize:
+- Cache rules
+- Request routing logic
+- Authentication handling
+- PURGE/BAN configurations
+
+### Ingress Configuration
+
+Edit [ingress.ts](ingress.ts) to:
+- Add/modify domain routes
+- Change TLS settings
+- Customize path rewrites
+- Add middleware
+
+## Troubleshooting
+
+### Check Pod Status
+
+```bash
+kubectl get pods -l app.kubernetes.io/part-of=plone
+```
+
+### View Logs
+
+```bash
+# Backend logs
+kubectl logs -l app.kubernetes.io/name=plone-backend -f
+
+# Frontend logs
+kubectl logs -l app.kubernetes.io/name=plone-frontend -f
+
+# Varnish cache logs
+kubectl logs -l app.kubernetes.io/name=plone-httpcache -f
+```
+
+### Database Connection Issues
+
+**CloudNativePG:**
+```bash
+# Check cluster status
+kubectl get cluster plone-postgresql
+
+# Check secret
+kubectl get secret plone-postgresql-app -o yaml
+```
+
+**Bitnami:**
+```bash
+# Check service
+kubectl get svc -l app.kubernetes.io/part-of=plone
+
+# Check secret
+kubectl get secret <service-name> -o yaml
+```
+
+### Access Logs
+
+```bash
+# Get all Plone-related resources
+kubectl get all -l app.kubernetes.io/part-of=plone
+```
+
+## References
+
+- [cdk8s-plone Documentation](https://bluedynamics.github.io/cdk8s-plone/)
+- [Plone 6 Documentation](https://6.docs.plone.org/)
+- [CloudNativePG Documentation](https://cloudnative-pg.io/documentation/)
+- [CDK8S Documentation](https://cdk8s.io/)
+- [Varnish Documentation](https://varnish-cache.org/docs/)
+
+## License
+
+Apache-2.0