@bluedynamics/cdk8s-plone 0.1.4 → 0.1.6

package/documentation/sources/reference/configuration-options.md

@@ -0,0 +1,370 @@
+# Configuration Options
+
+Complete reference for all configuration options in cdk8s-plone.
+
+## Key Constructs
+
+### `Plone`
+
+Main construct for deploying Plone CMS. Supports two variants:
+- **VOLTO**: Modern React frontend with REST API backend (default)
+- **CLASSICUI**: Traditional server-side rendered Plone
+
+**Properties:**
+- `backendServiceName` - Name of the backend Kubernetes service
+- `frontendServiceName` - Name of the frontend service (VOLTO only)
+- `variant` - Deployment variant (VOLTO or CLASSICUI)
+- `siteId` - Plone site ID in ZODB (default: 'Plone')
+
+**Example:**
+```typescript
+import { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';
+
+new Plone(chart, 'my-plone', {
+  variant: PloneVariant.VOLTO,
+  siteId: 'MySite',
+  backend: {
+    image: 'plone/plone-backend:6.1.3',
+    replicas: 3,
+  },
+  frontend: {
+    image: 'plone/plone-frontend:16.0.0',
+    replicas: 2,
+  },
+});
+```
+
+---
+
+### `PloneHttpcache`
+
+Varnish HTTP caching layer using the [kube-httpcache](https://github.com/mittwald/kube-httpcache) Helm chart. Provides cluster-wide cache invalidation.
+
+**Properties:**
+- `httpcacheServiceName` - Name of the Varnish service
+
+**Example:**
+```typescript
+import { PloneHttpcache } from '@bluedynamics/cdk8s-plone';
+
+new PloneHttpcache(chart, 'cache', {
+  plone: ploneInstance,
+  existingSecret: 'varnish-secret',
+  replicas: 2,
+});
+```
+
+---
+
+## Configuration Interfaces
+
+### `PloneOptions`
+
+Main configuration interface for the Plone construct.
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `version` | `string` | No | - | Version of your project |
+| `siteId` | `string` | No | `'Plone'` | Plone site ID in ZODB |
+| `variant` | `PloneVariant` | No | `VOLTO` | Deployment variant (VOLTO or CLASSICUI) |
+| `backend` | `PloneBaseOptions` | Yes | - | Backend configuration |
+| `frontend` | `PloneBaseOptions` | Conditional | - | Frontend configuration (required for VOLTO) |
+| `imagePullSecrets` | `string[]` | No | - | Image pull secrets for private registries |
+
+**Example:**
+```typescript
+const options: PloneOptions = {
+  version: '1.0.0',
+  siteId: 'MySite',
+  variant: PloneVariant.VOLTO,
+  backend: { /* ... */ },
+  frontend: { /* ... */ },
+  imagePullSecrets: ['my-registry-secret'],
+};
+```
+
+---
+
+### `PloneBaseOptions`
+
+Configuration for backend or frontend components.
+
+#### Container Configuration
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `image` | `string` | Yes | - | Container image (e.g., 'plone/plone-backend:6.1.3') |
+| `imagePullPolicy` | `string` | No | `'IfNotPresent'` | Image pull policy |
+| `replicas` | `number` | No | `2` | Number of pod replicas |
+| `environment` | `Env` | No | - | Environment variables (cdk8s-plus-30.Env) |
+
+**Example:**
+```typescript
+import { Env } from 'cdk8s-plus-30';
+
+backend: {
+  image: 'plone/plone-backend:6.1.3',
+  replicas: 3,
+  imagePullPolicy: 'Always',
+  environment: {
+    variables: {
+      SITE: Env.value('MySite'),
+      DEBUG_MODE: Env.value('off'),
+    },
+  },
+}
+```
+
+#### Resource Configuration
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `requestCpu` | `string` | CPU request (e.g., '500m', '1') |
+| `limitCpu` | `string` | CPU limit |
+| `requestMemory` | `string` | Memory request (e.g., '512Mi', '1Gi') |
+| `limitMemory` | `string` | Memory limit |
+
+**Example:**
+```typescript
+backend: {
+  image: 'plone/plone-backend:6.1.3',
+  requestCpu: '500m',
+  limitCpu: '2',
+  requestMemory: '512Mi',
+  limitMemory: '2Gi',
+}
+```
+
+#### High Availability
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `minAvailable` | `number` | Minimum pods available during updates (for PodDisruptionBudget) |
+| `maxUnavailable` | `number` | Maximum unavailable pods during updates |
+
+**Example:**
+```typescript
+backend: {
+  image: 'plone/plone-backend:6.1.3',
+  replicas: 5,
+  minAvailable: 3,  // At least 3 pods must be available during updates
+}
+```
+
+#### Readiness Probe
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `readinessEnabled` | `boolean` | `true` | Enable readiness probe |
+| `readinessInitialDelaySeconds` | `number` | - | Seconds before first probe |
+| `readinessTimeoutSeconds` | `number` | - | Probe timeout |
+| `readinessPeriodSeconds` | `number` | - | Probe frequency |
+| `readinessSuccessThreshold` | `number` | - | Consecutive successes required |
+| `readinessFailureThreshold` | `number` | - | Consecutive failures before marking unready |
+
+**Example:**
+```typescript
+backend: {
+  image: 'plone/plone-backend:6.1.3',
+  readinessEnabled: true,
+  readinessInitialDelaySeconds: 10,
+  readinessTimeoutSeconds: 5,
+  readinessPeriodSeconds: 10,
+  readinessFailureThreshold: 3,
+}
+```
+
+#### Liveness Probe
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `livenessEnabled` | `boolean` | `false` | Enable liveness probe (recommended `true` for frontend) |
+| `livenessInitialDelaySeconds` | `number` | - | Seconds before first probe |
+| `livenessTimeoutSeconds` | `number` | - | Probe timeout |
+| `livenessPeriodSeconds` | `number` | - | Probe frequency |
+| `livenessSuccessThreshold` | `number` | - | Consecutive successes required |
+| `livenessFailureThreshold` | `number` | - | Consecutive failures before restart |
+
+**Example:**
+```typescript
+frontend: {
+  image: 'plone/plone-frontend:16.0.0',
+  livenessEnabled: true,  // Recommended for frontend
+  livenessInitialDelaySeconds: 30,
+  livenessTimeoutSeconds: 5,
+  livenessPeriodSeconds: 30,
+  livenessFailureThreshold: 3,
+}
+```
+
+#### Annotations
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `annotations` | `Record<string, string>` | Deployment metadata annotations |
+| `podAnnotations` | `Record<string, string>` | Pod template annotations (e.g., for Prometheus) |
+| `serviceAnnotations` | `Record<string, string>` | Service annotations (e.g., for external-dns) |
+
+**Example:**
+```typescript
+backend: {
+  image: 'plone/plone-backend:6.1.3',
+  podAnnotations: {
+    'prometheus.io/scrape': 'true',
+    'prometheus.io/port': '8080',
+  },
+  serviceAnnotations: {
+    'external-dns.alpha.kubernetes.io/hostname': 'backend.example.com',
+  },
+}
+```
+
+---
+
+### `PloneHttpcacheOptions`
+
+Configuration for the Varnish HTTP cache layer.
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `plone` | `Plone` | Yes | - | Plone construct to attach cache to |
+| `varnishVcl` | `string` | No | - | VCL configuration as string |
+| `varnishVclFile` | `string` | No | - | Path to VCL configuration file |
+| `existingSecret` | `string` | No | - | Kubernetes secret for Varnish admin credentials |
+| `replicas` | `number` | No | `2` | Number of Varnish replicas |
+| `requestCpu` | `string` | No | - | CPU request |
+| `limitCpu` | `string` | No | - | CPU limit |
+| `requestMemory` | `string` | No | - | Memory request |
+| `limitMemory` | `string` | No | - | Memory limit |
+| `servicemonitor` | `boolean` | No | `false` | Enable Prometheus ServiceMonitor |
+| `exporterEnabled` | `boolean` | No | `true` | Enable Prometheus exporter sidecar |
+| `chartVersion` | `string` | No | latest | kube-httpcache Helm chart version |
+
+**Example:**
+```typescript
+new PloneHttpcache(chart, 'cache', {
+  plone: ploneInstance,
+  existingSecret: 'varnish-secret',
+  replicas: 3,
+  requestCpu: '250m',
+  limitCpu: '1',
+  requestMemory: '256Mi',
+  limitMemory: '1Gi',
+  servicemonitor: true,
+  exporterEnabled: true,
+});
+```
+
+**VCL Configuration:**
+```typescript
+// Inline VCL
+new PloneHttpcache(chart, 'cache', {
+  plone: ploneInstance,
+  varnishVcl: `
+    vcl 4.1;
+    backend default {
+      .host = "backend-service";
+      .port = "8080";
+    }
+  `,
+});
+
+// VCL from file
+new PloneHttpcache(chart, 'cache', {
+  plone: ploneInstance,
+  varnishVclFile: './varnish/default.vcl',
+});
+```
+
+---
+
+## PloneVariant Enum
+
+Defines the deployment variant:
+
+| Value | Description |
+|-------|-------------|
+| `PloneVariant.VOLTO` | Modern React frontend with REST API backend (default) |
+| `PloneVariant.CLASSICUI` | Traditional server-side rendered Plone |
+
+**Example:**
+```typescript
+import { PloneVariant } from '@bluedynamics/cdk8s-plone';
+
+// Volto (modern)
+variant: PloneVariant.VOLTO
+
+// Classic UI
+variant: PloneVariant.CLASSICUI
+```
+
+---
+
+## Complete Example
+
+```typescript
+import { App, Chart } from 'cdk8s';
+import { Plone, PloneVariant, PloneHttpcache } from '@bluedynamics/cdk8s-plone';
+import { Env } from 'cdk8s-plus-30';
+
+const app = new App();
+const chart = new Chart(app, 'PloneDeployment');
+
+const plone = new Plone(chart, 'my-plone', {
+  version: '1.0.0',
+  siteId: 'MySite',
+  variant: PloneVariant.VOLTO,
+  imagePullSecrets: ['registry-secret'],
+
+  backend: {
+    image: 'plone/plone-backend:6.1.3',
+    replicas: 3,
+    requestCpu: '500m',
+    limitCpu: '2',
+    requestMemory: '512Mi',
+    limitMemory: '2Gi',
+    minAvailable: 2,
+    readinessEnabled: true,
+    readinessInitialDelaySeconds: 10,
+    environment: {
+      variables: {
+        SITE: Env.value('MySite'),
+      },
+    },
+    podAnnotations: {
+      'prometheus.io/scrape': 'true',
+    },
+  },
+
+  frontend: {
+    image: 'plone/plone-frontend:16.0.0',
+    replicas: 2,
+    requestCpu: '250m',
+    limitCpu: '1',
+    requestMemory: '256Mi',
+    limitMemory: '1Gi',
+    livenessEnabled: true,
+    livenessInitialDelaySeconds: 30,
+  },
+});
+
+new PloneHttpcache(chart, 'cache', {
+  plone: plone,
+  existingSecret: 'varnish-secret',
+  replicas: 2,
+  requestCpu: '250m',
+  requestMemory: '256Mi',
+  servicemonitor: true,
+});
+
+app.synth();
+```
+
+---
+
+## See Also
+
+- [API Documentation](api/) - Complete API reference
+- [Quick Start Tutorial](../tutorials/01-quick-start.md) - Get started guide
+- [Scale Resources](../how-to/scale-resources.md) - How to adjust resources
+- [Configure Monitoring](../how-to/configure-monitoring.md) - Prometheus setup

package/documentation/sources/reference/index.md

@@ -0,0 +1,59 @@
+```{image} ../_static/kup6s-icon-reference.svg
+:align: center
+:class: section-icon-large
+```
+
+# Reference
+
+**Information-oriented technical specifications and configurations for cdk8s-plone.**
+
+Reference guides provide detailed technical information about cdk8s-plone's API, configuration options, and component specifications. They describe how things work and what parameters are available.
+
+## API Reference
+
+*This section will contain auto-generated or detailed documentation for:*
+- Main chart classes
+- Configuration interfaces
+- Individual construct classes
+- Utility functions and validators
+
+## Configuration Reference
+
+```{toctree}
+---
+maxdepth: 1
+titlesonly: true
+---
+configuration-options
+```
+
+## Component Specifications
+
+```{toctree}
+---
+maxdepth: 1
+titlesonly: true
+---
+```
+
+*Component specifications will be added in future releases.*
+
+## API Documentation
+
+See the `api/` directory for detailed construct documentation:
+
+```{toctree}
+---
+maxdepth: 1
+glob: true
+---
+api/*
+```
+
+---
+
+**Getting started?** Begin with the [Tutorials](../tutorials/index.md) for hands-on learning.
+
+**Solving a specific problem?** Check the [How-To Guides](../how-to/index.md) for task-oriented solutions.
+
+**Understanding concepts?** Read the [Explanation](../explanation/index.md) section for architecture and design.

package/documentation/sources/tutorials/01-quick-start.md

@@ -0,0 +1,157 @@
+# Quick Start
+
+This tutorial will guide you through deploying your first Plone instance using cdk8s-plone.
+
+## Prerequisites
+
+Before you start, ensure you have:
+
+- **Node.js 16+** and npm installed
+- **kubectl** configured to access your Kubernetes cluster
+- Basic familiarity with Kubernetes and TypeScript
+- A Kubernetes cluster (local or remote)
+
+For detailed prerequisites, see [Setup Prerequisites](../how-to/setup-prerequisites.md).
+
+## Step 1: Create a CDK8S Project
+
+Create a new CDK8S TypeScript project:
+
+```bash
+# Create project directory
+mkdir my-plone-deployment
+cd my-plone-deployment
+
+# Initialize CDK8S project
+cdk8s init typescript-app
+```
+
+This creates a basic CDK8S project structure.
+
+## Step 2: Install cdk8s-plone
+
+Install the cdk8s-plone library:
+
+```bash
+npm install @bluedynamics/cdk8s-plone
+```
+
+The library is also available for Python via PyPI:
+
+```bash
+pip install cdk8s-plone
+```
+
+## Step 3: Create a Basic Plone Deployment
+
+Edit `main.ts` with the following code:
+
+```typescript
+import { App, Chart } from 'cdk8s';
+import { Plone, PloneVariant } from '@bluedynamics/cdk8s-plone';
+
+const app = new App();
+const chart = new Chart(app, 'PloneDeployment');
+
+new Plone(chart, 'my-plone', {
+  variant: PloneVariant.VOLTO,
+  backend: {
+    image: 'plone/plone-backend:6.1.3',
+    replicas: 3,
+  },
+  frontend: {
+    image: 'plone/plone-frontend:16.0.0',
+    replicas: 2,
+  },
+});
+
+app.synth();
+```
+
+This creates:
+- A Plone backend with 3 replicas
+- A Volto frontend with 2 replicas
+- All necessary Kubernetes services and deployments
+
+## Step 4: Generate Kubernetes Manifests
+
+Generate the Kubernetes manifests:
+
+```bash
+cdk8s synth
+```
+
+This creates YAML files in the `dist/` directory containing all Kubernetes resources.
+
+## Step 5: Deploy to Kubernetes
+
+Apply the generated manifests to your cluster:
+
+```bash
+kubectl apply -f dist/
+```
+
+Check the deployment status:
+
+```bash
+kubectl get pods
+kubectl get services
+```
+
+## Step 6: Access Your Plone Site
+
+Once all pods are running, access your Plone site:
+
+```bash
+# Port-forward to the frontend service
+kubectl port-forward service/my-plone-frontend 3000:3000
+
+# Open in browser
+open http://localhost:3000
+```
+
+## Adding HTTP Caching (Optional)
+
+For production deployments, add Varnish HTTP caching:
+
+```typescript
+import { PloneHttpcache } from '@bluedynamics/cdk8s-plone';
+
+const plone = new Plone(chart, 'my-plone', {
+  variant: PloneVariant.VOLTO,
+  backend: { image: 'plone/plone-backend:6.1.3' },
+  frontend: { image: 'plone/plone-frontend:16.0.0' },
+});
+
+new PloneHttpcache(chart, 'cache', {
+  plone: plone,
+  existingSecret: 'varnish-secret',
+  replicas: 2,
+});
+```
+
+This adds a Varnish caching layer with cluster-wide cache invalidation using [kube-httpcache](https://github.com/mittwald/kube-httpcache).
+
+## Next Steps
+
+Now that you have a basic Plone deployment:
+
+- **Configure resources**: See [Scale Resources](../how-to/scale-resources.md) to adjust CPU and memory
+- **Add monitoring**: Configure [Prometheus metrics](../how-to/configure-monitoring.md)
+- **Explore variants**: Learn about [Classic UI vs Volto](../explanation/plone-variants.md)
+
+## Troubleshooting
+
+**Pods not starting?**
+- Check pod logs: `kubectl logs <pod-name>`
+- Verify images are accessible: `kubectl describe pod <pod-name>`
+
+**Can't access the site?**
+- Ensure port-forward is running
+- Check service endpoints: `kubectl get endpoints`
+
+For more help, see the [Troubleshooting guide](../how-to/troubleshooting.md).
+
+---
+
+**Complete example**: See the [cdk8s-plone-example](https://github.com/bluedynamics/cdk8s-plone-example) repository for a full working example.

package/documentation/sources/tutorials/index.md

@@ -0,0 +1,48 @@
+```{image} ../_static/kup6s-icon-tutorials.svg
+:align: center
+:class: section-icon-large
+```
+
+# Tutorials
+
+**Learning-oriented guides that take you through a series of steps to complete a project.**
+
+Tutorials are lessons that help you gain practical skills and familiarity with cdk8s-plone. They are designed to be followed step-by-step and will get you up and running.
+
+## What you'll learn
+
+These tutorials will teach you how to:
+
+- Deploy a basic Plone instance using cdk8s-plone
+- Configure PostgreSQL backend
+- Customize component resources and settings
+- Test your deployment
+
+## Available Tutorials
+
+```{toctree}
+---
+maxdepth: 1
+titlesonly: true
+---
+01-quick-start
+```
+
+## Before you start
+
+These tutorials assume you have:
+- Basic familiarity with Kubernetes concepts
+- Node.js 16+ and npm installed
+- A Kubernetes cluster (local or remote)
+- kubectl configured to access your cluster
+- Basic TypeScript knowledge
+
+If you're new to CDK8S, we recommend reading the [CDK8S documentation](https://cdk8s.io/) first to understand how constructs work.
+
+---
+
+**Looking for practical guidance?** Check out the [How-To Guides](../how-to/index.md) for specific solutions.
+
+**Need technical details?** See the [Reference](../reference/index.md) section for API documentation.
+
+**Want to understand the architecture?** Read the [Explanation](../explanation/index.md) section for concepts and design decisions.

package/lib/httpcache.d.ts

@@ -65,6 +65,12 @@ export interface PloneHttpcacheOptions {
      * @default undefined (latest)
      */
     readonly chartVersion?: string;
+    /**
+     * Version of the kube-httpcache Container Image to use.
+     * If not specified, the latest version from the repository will be used.
+     * @default undefined (chartVersion = with each chart release there is an image release too )
+     */
+    readonly appVersion?: string;
     /**
      * Number of Varnish pod replicas to run.
      * @default 2