@bluedynamics/cdk8s-plone 0.1.10 → 0.1.11

package/documentation/sources/how-to/deploy-production-volto.md

@@ -0,0 +1,319 @@
+# Deploy Production Volto Example
+
+This guide shows you how to deploy the production-ready Volto example to your Kubernetes cluster.
+
+## What You'll Deploy
+
+The [Production Volto example](https://github.com/bluedynamics/cdk8s-plone/tree/main/examples/production-volto) includes:
+
+- **Plone 6.1 with Volto** (React frontend + REST API backend)
+- **PostgreSQL** with RelStorage (CloudNativePG or Bitnami)
+- **Varnish HTTP caching** with kube-httpcache
+- **Ingress** with TLS (Traefik or Kong)
+- **Three access domains** (cached, uncached, maintenance)
+
+## Prerequisites
+
+### Required
+
+Ensure you have these installed on your cluster:
+
+1. **Ingress Controller** - Either:
+   - [Traefik v3](https://doc.traefik.io/traefik/getting-started/install-traefik/) with CRDs
+   - [Kong Gateway](https://docs.konghq.com/gateway/latest/install/kubernetes/)
+
+2. **cert-manager** - For TLS certificates:
+   ```bash
+   kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.0/cert-manager.yaml
+   ```
+
+3. **kube-httpcache Operator** - For Varnish caching:
+   ```bash
+   kubectl apply -f https://github.com/mittwald/kube-httpcache/releases/latest/download/kube-httpcache.yaml
+   ```
+
+4. **PostgreSQL Operator** - Choose one:
+
+   **Option A: 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
+   ```
+
+   **Option B: Bitnami** (simpler for testing):
+   ```bash
+   kubectl create namespace plone
+   ```
+
+### Local Tools
+
+- **Node.js 18+** and npm
+- **kubectl** configured for your cluster
+- **git** to clone the repository
+
+## Step 1: Get the Example
+
+Clone the repository and navigate to the example:
+
+```bash
+git clone https://github.com/bluedynamics/cdk8s-plone.git
+cd cdk8s-plone/examples/production-volto
+```
+
+## Step 2: Install Dependencies
+
+```bash
+npm install
+```
+
+## Step 3: Import CRDs
+
+Generate TypeScript bindings for Kubernetes CRDs:
+
+```bash
+npm run import
+```
+
+This imports:
+- Kubernetes core API
+- CloudNativePG Cluster CRDs
+- Traefik Middleware CRDs
+
+## Step 4: Configure Environment
+
+Create a `.env` file from the example:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your settings:
+
+```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 images
+#PLONE_BACKEND_IMAGE=plone/plone-backend:6.1.3
+#PLONE_FRONTEND_IMAGE=plone/plone-frontend:latest
+
+# Database: 'bitnami' or 'cloudnativepg'
+DATABASE=cloudnativepg
+```
+
+:::{tip}
+For production, use `cloudnativepg` for high availability. For testing, `bitnami` is simpler.
+:::
+
+## Step 5: Generate Manifests
+
+Synthesize Kubernetes YAML:
+
+```bash
+npm run synth
+```
+
+This creates `dist/plone-example.k8s.yaml` with all resources.
+
+## Step 6: Review Generated Manifests
+
+Inspect what will be deployed:
+
+```bash
+# Count resources
+grep "^kind:" dist/plone-example.k8s.yaml | sort | uniq -c
+
+# View specific resources
+kubectl apply --dry-run=client -f dist/plone-example.k8s.yaml
+```
+
+## Step 7: Deploy to Kubernetes
+
+Deploy to your cluster:
+
+```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
+```
+
+## Step 8: Monitor Deployment
+
+Watch pods starting:
+
+```bash
+# Watch all pods
+kubectl get pods -l app.kubernetes.io/part-of=plone -w
+
+# Check specific components
+kubectl get pods -l app.kubernetes.io/name=plone-backend
+kubectl get pods -l app.kubernetes.io/name=plone-frontend
+kubectl get pods -l app.kubernetes.io/name=plone-httpcache
+```
+
+Wait for all pods to be `Running`:
+
+```bash
+kubectl wait --for=condition=ready pod -l app.kubernetes.io/part-of=plone --timeout=300s
+```
+
+## Step 9: Verify Services
+
+Check that services are created:
+
+```bash
+kubectl get svc -l app.kubernetes.io/part-of=plone
+```
+
+You should see:
+- `plone-backend` (backend service)
+- `plone-frontend` (frontend service)
+- `plone-httpcache` (Varnish cache)
+- Database service (Bitnami or CloudNativePG)
+
+## Step 10: Check Ingress
+
+Verify ingress routes:
+
+```bash
+kubectl get ingress
+```
+
+Check TLS certificates:
+
+```bash
+kubectl get certificate
+```
+
+## Step 11: Access Your Site
+
+Once DNS is configured and TLS certificates are issued:
+
+- **Public site (cached)**: https://plone.example.com
+- **Testing (uncached)**: https://plone-test.example.com
+- **Maintenance**: https://plone-admin.example.com
+
+### Create Plone Site
+
+On first access to the maintenance domain:
+
+1. Go to: https://plone-admin.example.com
+2. Click "Create a new Plone site"
+3. Fill in:
+   - **Site ID**: `Plone`
+   - **Title**: Your site title
+   - **Language**: Choose language
+4. Click "Create Plone Site"
+
+## Troubleshooting
+
+### Pods Not Starting
+
+Check pod 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
+
+# Database logs (CloudNativePG)
+kubectl logs -l postgresql=plone-postgresql -f
+```
+
+### Database Connection Issues
+
+**CloudNativePG:**
+
+```bash
+# Check cluster status
+kubectl get cluster
+
+# Check secret
+kubectl get secret -l cnpg.io/cluster
+```
+
+**Bitnami:**
+
+```bash
+# Check service
+kubectl get svc -l app.kubernetes.io/name=postgresql
+
+# Check secret
+kubectl describe secret <postgresql-secret-name>
+```
+
+### TLS Certificate Issues
+
+```bash
+# Check certificate status
+kubectl describe certificate
+
+# Check cert-manager logs
+kubectl logs -n cert-manager deployment/cert-manager
+```
+
+### Varnish Cache Not Working
+
+```bash
+# Check httpcache logs
+kubectl logs -l app.kubernetes.io/name=plone-httpcache
+
+# Check if kube-httpcache operator is running
+kubectl get pods -n kube-httpcache-system
+```
+
+## Updating Your Deployment
+
+After making changes to the example:
+
+1. Edit configuration files
+2. Regenerate manifests: `npm run synth`
+3. Apply changes: `kubectl apply -f dist/plone-example.k8s.yaml`
+
+## Scaling
+
+Scale replicas by editing `main.ts`:
+
+```typescript
+const plone = new Plone(this, 'plone', {
+  backend: {
+    replicas: 3,  // Scale backend
+  },
+  frontend: {
+    replicas: 3,  // Scale frontend
+  },
+})
+```
+
+Then regenerate and reapply.
+
+## Cleanup
+
+Remove all resources:
+
+```bash
+kubectl delete -f dist/plone-example.k8s.yaml
+```
+
+## Next Steps
+
+- Configure [monitoring and metrics](../reference/configuration-options.md#monitoring)
+- Set up [backups](../explanation/features.md#database-integration) for CloudNativePG
+- Customize [Varnish caching rules](https://github.com/bluedynamics/cdk8s-plone/blob/main/examples/production-volto/config/varnish.tpl.vcl)
+- Review [security best practices](../explanation/architecture.md#security)
+
+## See Also
+
+- [Deploy Classic UI Example](deploy-classic-ui.md) - For traditional Plone interface
+- [Setup Prerequisites](setup-prerequisites.md) - Detailed cluster setup
+- [Configuration Options](../reference/configuration-options.md) - API reference

package/documentation/sources/how-to/index.md

@@ -21,6 +21,19 @@ titlesonly: true
 setup-prerequisites
 ```
 
+## Deployment
+
+**Deploy complete Plone examples to your Kubernetes cluster:**
+
+```{toctree}
+---
+maxdepth: 1
+titlesonly: true
+---
+deploy-production-volto
+deploy-classic-ui
+```
+
 ## Configuration
 
 ```{toctree}

package/documentation/sources/reference/api/index.md

@@ -0,0 +1,29 @@
+# API Reference
+
+Complete API reference for cdk8s-plone constructs, generated from TypeScript source code.
+
+## Overview
+
+The cdk8s-plone library provides the following main constructs:
+
+- **Plone**: Main construct for deploying Plone CMS with support for both Volto (React frontend) and Classic UI variants
+- **PloneHttpcache**: HTTP caching layer using Varnish for improved performance
+
+## Language Support
+
+This API documentation shows TypeScript usage examples. The library is also available for Python via JSII transpilation:
+
+- **TypeScript/JavaScript**: [`@bluedynamics/cdk8s-plone`](https://www.npmjs.com/package/@bluedynamics/cdk8s-plone) on npm
+- **Python**: [`cdk8s-plone`](https://pypi.org/project/cdk8s-plone/) on PyPI
+
+For Python-specific usage, the API remains the same but follows Python naming conventions (snake_case instead of camelCase).
+
+---
+
+```{include} ../../../../API.md
+:relative-docs: ../../../../
+:relative-images:
+:start-line: 2
+```
+
+*This API reference is automatically generated from the TypeScript source code. For the latest version, run `npx projen docgen` in the project root.*

package/examples/classic-ui/.env.example

@@ -0,0 +1,19 @@
+# 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 backend image
+# Leave commented to use default (official Plone image)
+#PLONE_BACKEND_IMAGE=plone/plone-backend:6.1.3
+
+# Configure database backend
+# Options: 'bitnami' (default, simple) or 'cloudnativepg' (production-ready)
+DATABASE=cloudnativepg