@bluedynamics/cdk8s-plone 0.1.35 → 0.1.37

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

@@ -1,8 +1,17 @@
-# Deploy Classic UI Example
+---
+myst:
+  html_meta:
+    "description": "Deploy the Classic UI example: server-side rendered Plone with PostgreSQL, Varnish caching, and ingress with TLS."
+    "property=og:description": "Deploy the Classic UI example: server-side rendered Plone with PostgreSQL, Varnish caching, and ingress with TLS."
+    "property=og:title": "Deploy Classic UI example"
+    "keywords": "Plone, cdk8s, Kubernetes, Classic UI, PostgreSQL, Varnish, ingress"
+---
+
+# Deploy Classic UI example
 
 This guide shows you how to deploy the Classic UI example to your Kubernetes cluster.
 
-## What You'll Deploy
+## 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:
 
@@ -27,7 +36,7 @@ Choose Classic UI if you're migrating from older Plone versions or need specific
 
 ## Prerequisites
 
-Same as the [Production Volto guide](deploy-production-volto.md#prerequisites), you need:
+Same as the {ref}`production-volto-prerequisites` in the Production Volto guide, you need:
 
 - Ingress controller (Traefik or Kong)
 - cert-manager
@@ -36,36 +45,36 @@ Same as the [Production Volto guide](deploy-production-volto.md#prerequisites),
 
 See [Setup Prerequisites](setup-prerequisites.md) for detailed instructions.
 
-## Step 1: Get the Example
+## Step 1: Get the example
 
-```bash
+```shell
 git clone https://github.com/bluedynamics/cdk8s-plone.git
 cd cdk8s-plone/examples/classic-ui
 ```
 
-## Step 2: Install Dependencies
+## Step 2: Install dependencies
 
-```bash
+```shell
 npm install
 ```
 
 ## Step 3: Import CRDs
 
-```bash
+```shell
 npm run import
 ```
 
-## Step 4: Configure Environment
+## Step 4: Configure environment
 
 Create `.env` from the example:
 
-```bash
+```shell
 cp .env.example .env
 ```
 
 Edit `.env`:
 
-```bash
+```shell
 # Your domains
 DOMAIN_CACHED=plone.example.com
 DOMAIN_UNCACHED=plone-test.example.com
@@ -85,17 +94,17 @@ DATABASE=cloudnativepg
 Classic UI only needs one image (backend). There's no frontend image configuration.
 :::
 
-## Step 5: Generate Manifests
+## Step 5: Generate manifests
 
-```bash
+```shell
 npm run synth
 ```
 
 Creates `dist/plone-classic.k8s.yaml` (~27 KB, smaller than Volto's 32 KB).
 
-## Step 6: Review Manifests
+## Step 6: Review manifests
 
-```bash
+```shell
 # Count resources
 grep "^kind:" dist/plone-classic.k8s.yaml | sort | uniq -c
 
@@ -105,19 +114,19 @@ kubectl apply --dry-run=client -f dist/plone-classic.k8s.yaml
 
 ## Step 7: Deploy
 
-```bash
+```shell
 kubectl apply -f dist/plone-classic.k8s.yaml
 ```
 
 Or to a specific namespace:
 
-```bash
+```shell
 kubectl apply -f dist/plone-classic.k8s.yaml -n plone
 ```
 
-## Step 8: Monitor Deployment
+## Step 8: Monitor deployment
 
-```bash
+```shell
 # Watch pods
 kubectl get pods -l app.kubernetes.io/part-of=plone -w
 
@@ -131,9 +140,9 @@ kubectl wait --for=condition=ready pod \
 Classic UI deploys fewer pods than Volto (no frontend pods).
 :::
 
-## Step 9: Verify Services
+## Step 9: Verify services
 
-```bash
+```shell
 kubectl get svc -l app.kubernetes.io/part-of=plone
 ```
 
@@ -142,14 +151,14 @@ You should see:
 - `plone-httpcache` (Varnish cache)
 - Database service
 
-## Step 10: Check Ingress
+## Step 10: Check ingress
 
-```bash
+```shell
 kubectl get ingress
 kubectl get certificate
 ```
 
-## Step 11: Access Your Site
+## Step 11: Access your site
 
 Once DNS and TLS are ready:
 
@@ -157,7 +166,7 @@ Once DNS and TLS are ready:
 - **Testing (uncached)**: https://plone-test.example.com
 - **Maintenance**: https://plone-admin.example.com
 
-### Create Plone Site
+### Create Plone site
 
 1. Access maintenance domain: https://plone-admin.example.com
 2. Click "Create a new Plone site"
@@ -168,7 +177,7 @@ Once DNS and TLS are ready:
    - **Add-ons**: Choose Classic UI add-ons
 4. Click "Create Plone Site"
 
-## Key Differences from Volto
+## Key differences from Volto
 
 ### Architecture
 
@@ -184,7 +193,7 @@ Compared to Volto:
 Traffic → Ingress → {Varnish → Frontend, Backend}
 ```
 
-### Ingress Routes
+### Ingress routes
 
 Classic UI uses virtual host rewriting for direct backend access:
 
@@ -192,7 +201,7 @@ Classic UI uses virtual host rewriting for direct backend access:
 - **Uncached**: Direct to backend with VirtualHostBase rewrite
 - **Maintenance**: Direct backend access with VirtualHostRoot
 
-### No Frontend Service
+### No frontend service
 
 The manifest doesn't include:
 - Frontend deployment
@@ -203,11 +212,11 @@ This makes the deployment ~15% smaller and simpler to manage.
 
 ## Troubleshooting
 
-### Backend Not Starting
+### Backend not starting
 
 Check backend logs:
 
-```bash
+```shell
 kubectl logs -l app.kubernetes.io/name=plone-backend -f
 ```
 
@@ -216,24 +225,24 @@ Common issues:
 - Memory limits too low
 - Image pull errors
 
-### Classic UI Interface Not Loading
+### Classic UI interface not loading
 
 1. Check if backend pods are running:
-   ```bash
+   ```shell
    kubectl get pods -l app.kubernetes.io/name=plone-backend
    ```
 
 2. Verify virtual host rewriting in ingress:
-   ```bash
+   ```shell
    kubectl describe ingress
    ```
 
 3. Check Varnish routing:
-   ```bash
+   ```shell
    kubectl logs -l app.kubernetes.io/name=plone-httpcache
    ```
 
-### Add-on Compatibility
+### Add-on compatibility
 
 Some add-ons are Volto-specific. For Classic UI:
 - Use Classic UI themes (not Volto themes)
@@ -253,7 +262,7 @@ See the [Production Volto deployment guide](deploy-production-volto.md) for deta
 
 ## Customization
 
-### Backend Configuration
+### Backend configuration
 
 Edit `main.ts` to customize:
 
@@ -270,7 +279,7 @@ const plone = new Plone(this, 'plone', {
 })
 ```
 
-### Varnish Caching
+### Varnish caching
 
 Edit `config/varnish.tpl.vcl` for caching rules specific to Classic UI.
 
@@ -287,7 +296,7 @@ backend: {
 ```
 
 Then:
-```bash
+```shell
 npm run synth
 kubectl apply -f dist/plone-classic.k8s.yaml
 ```
@@ -303,20 +312,19 @@ Classic UI performance characteristics:
 
 ## Cleanup
 
-```bash
+```shell
 kubectl delete -f dist/plone-classic.k8s.yaml
 ```
 
-## Next Steps
+## 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)
+- Follow {doc}`enable-prometheus-monitoring` to add Prometheus monitoring.
+- Configure [CloudNativePG backups](https://cloudnative-pg.io/documentation/).
+- Customize the Classic UI theme through [Plone 6 Classic UI documentation](https://6.docs.plone.org/classic-ui/).
 
-## See Also
+## 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/)
+- {doc}`deploy-production-volto` — For the modern React UI.
+- {doc}`setup-prerequisites` — Cluster requirements.
+- {doc}`/reference/configuration-options` — API reference.
+- [Plone 6 Classic UI documentation](https://6.docs.plone.org/classic-ui/)

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

@@ -1,8 +1,17 @@
-# Deploy Production Volto Example
+---
+myst:
+  html_meta:
+    "description": "Deploy the production-ready Volto example: React frontend, Plone REST API backend, PostgreSQL, Varnish caching, and ingress with TLS."
+    "property=og:description": "Deploy the production-ready Volto example: React frontend, Plone REST API backend, PostgreSQL, Varnish caching, and ingress with TLS."
+    "property=og:title": "Deploy production Volto example"
+    "keywords": "Plone, cdk8s, Kubernetes, Volto, production, PostgreSQL, Varnish, ingress, TLS"
+---
+
+# Deploy production Volto example
 
 This guide shows you how to deploy the production-ready Volto example to your Kubernetes cluster.
 
-## What You'll Deploy
+## What you'll deploy
 
 The [Production Volto example](https://github.com/bluedynamics/cdk8s-plone/tree/main/examples/production-volto) includes:
 
@@ -12,6 +21,8 @@ The [Production Volto example](https://github.com/bluedynamics/cdk8s-plone/tree/
 - **Ingress** with TLS (Traefik or Kong)
 - **Three access domains** (cached, uncached, maintenance)
 
+(production-volto-prerequisites)=
+
 ## Prerequisites
 
 ### Required
@@ -23,45 +34,45 @@ Ensure you have these installed on your cluster:
    - [Kong Gateway](https://docs.konghq.com/gateway/latest/install/kubernetes/)
 
 2. **cert-manager** - For TLS certificates:
-   ```bash
+   ```shell
    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
+   ```shell
    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
+   ```shell
    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
+   ```shell
    kubectl create namespace plone
    ```
 
-### Local Tools
+### Local tools
 
 - **Node.js 18+** and npm
 - **kubectl** configured for your cluster
 - **git** to clone the repository
 
-## Step 1: Get the Example
+## Step 1: Get the example
 
 Clone the repository and navigate to the example:
 
-```bash
+```shell
 git clone https://github.com/bluedynamics/cdk8s-plone.git
 cd cdk8s-plone/examples/production-volto
 ```
 
-## Step 2: Install Dependencies
+## Step 2: Install dependencies
 
-```bash
+```shell
 npm install
 ```
 
@@ -69,7 +80,7 @@ npm install
 
 Generate TypeScript bindings for Kubernetes CRDs:
 
-```bash
+```shell
 npm run import
 ```
 
@@ -78,17 +89,17 @@ This imports:
 - CloudNativePG Cluster CRDs
 - Traefik Middleware CRDs
 
-## Step 4: Configure Environment
+## Step 4: Configure environment
 
 Create a `.env` file from the example:
 
-```bash
+```shell
 cp .env.example .env
 ```
 
 Edit `.env` with your settings:
 
-```bash
+```shell
 # Your domains
 DOMAIN_CACHED=plone.example.com
 DOMAIN_UNCACHED=plone-test.example.com
@@ -109,21 +120,21 @@ DATABASE=cloudnativepg
 For production, use `cloudnativepg` for high availability. For testing, `bitnami` is simpler.
 :::
 
-## Step 5: Generate Manifests
+## Step 5: Generate manifests
 
 Synthesize Kubernetes YAML:
 
-```bash
+```shell
 npm run synth
 ```
 
 This creates `dist/plone-example.k8s.yaml` with all resources.
 
-## Step 6: Review Generated Manifests
+## Step 6: Review generated manifests
 
 Inspect what will be deployed:
 
-```bash
+```shell
 # Count resources
 grep "^kind:" dist/plone-example.k8s.yaml | sort | uniq -c
 
@@ -135,21 +146,21 @@ kubectl apply --dry-run=client -f dist/plone-example.k8s.yaml
 
 Deploy to your cluster:
 
-```bash
+```shell
 kubectl apply -f dist/plone-example.k8s.yaml
 ```
 
 Or deploy to a specific namespace:
 
-```bash
+```shell
 kubectl apply -f dist/plone-example.k8s.yaml -n plone
 ```
 
-## Step 8: Monitor Deployment
+## Step 8: Monitor deployment
 
 Watch pods starting:
 
-```bash
+```shell
 # Watch all pods
 kubectl get pods -l app.kubernetes.io/part-of=plone -w
 
@@ -161,15 +172,15 @@ kubectl get pods -l app.kubernetes.io/name=plone-httpcache
 
 Wait for all pods to be `Running`:
 
-```bash
+```shell
 kubectl wait --for=condition=ready pod -l app.kubernetes.io/part-of=plone --timeout=300s
 ```
 
-## Step 9: Verify Services
+## Step 9: Verify services
 
 Check that services are created:
 
-```bash
+```shell
 kubectl get svc -l app.kubernetes.io/part-of=plone
 ```
 
@@ -179,21 +190,21 @@ You should see:
 - `plone-httpcache` (Varnish cache)
 - Database service (Bitnami or CloudNativePG)
 
-## Step 10: Check Ingress
+## Step 10: Check ingress
 
 Verify ingress routes:
 
-```bash
+```shell
 kubectl get ingress
 ```
 
 Check TLS certificates:
 
-```bash
+```shell
 kubectl get certificate
 ```
 
-## Step 11: Access Your Site
+## Step 11: Access your site
 
 Once DNS is configured and TLS certificates are issued:
 
@@ -201,7 +212,7 @@ Once DNS is configured and TLS certificates are issued:
 - **Testing (uncached)**: https://plone-test.example.com
 - **Maintenance**: https://plone-admin.example.com
 
-### Create Plone Site
+### Create Plone site
 
 On first access to the maintenance domain:
 
@@ -215,11 +226,11 @@ On first access to the maintenance domain:
 
 ## Troubleshooting
 
-### Pods Not Starting
+### Pods not starting
 
 Check pod logs:
 
-```bash
+```shell
 # Backend logs
 kubectl logs -l app.kubernetes.io/name=plone-backend -f
 
@@ -230,11 +241,11 @@ kubectl logs -l app.kubernetes.io/name=plone-frontend -f
 kubectl logs -l postgresql=plone-postgresql -f
 ```
 
-### Database Connection Issues
+### Database connection issues
 
 **CloudNativePG:**
 
-```bash
+```shell
 # Check cluster status
 kubectl get cluster
 
@@ -244,7 +255,7 @@ kubectl get secret -l cnpg.io/cluster
 
 **Bitnami:**
 
-```bash
+```shell
 # Check service
 kubectl get svc -l app.kubernetes.io/name=postgresql
 
@@ -252,9 +263,9 @@ kubectl get svc -l app.kubernetes.io/name=postgresql
 kubectl describe secret <postgresql-secret-name>
 ```
 
-### TLS Certificate Issues
+### TLS certificate issues
 
-```bash
+```shell
 # Check certificate status
 kubectl describe certificate
 
@@ -262,9 +273,9 @@ kubectl describe certificate
 kubectl logs -n cert-manager deployment/cert-manager
 ```
 
-### Varnish Cache Not Working
+### Varnish cache not working
 
-```bash
+```shell
 # Check httpcache logs
 kubectl logs -l app.kubernetes.io/name=plone-httpcache
 
@@ -272,7 +283,7 @@ kubectl logs -l app.kubernetes.io/name=plone-httpcache
 kubectl get pods -n kube-httpcache-system
 ```
 
-## Updating Your Deployment
+## Updating your deployment
 
 After making changes to the example:
 
@@ -301,19 +312,18 @@ Then regenerate and reapply.
 
 Remove all resources:
 
-```bash
+```shell
 kubectl delete -f dist/plone-example.k8s.yaml
 ```
 
-## Next Steps
+## 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)
+- Configure monitoring and metrics through {doc}`enable-prometheus-monitoring`.
+- Customize [Varnish caching rules](https://github.com/bluedynamics/cdk8s-plone/blob/main/examples/production-volto/config/varnish.tpl.vcl).
+- Harden pods with {doc}`configure-security-context`.
 
-## See Also
+## 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
+- {doc}`deploy-classic-ui` — For the traditional Plone interface.
+- {doc}`setup-prerequisites` — Detailed cluster setup.
+- {doc}`/reference/configuration-options` — API reference.

package/documentation/sources/how-to/deploy-with-vinyl-cache.md

@@ -1,9 +1,18 @@
+---
+myst:
+  html_meta:
+    "description": "Add the cloud-vinyl VinylCache operator to your Plone deployment for operator-managed Varnish caching."
+    "property=og:description": "Add the cloud-vinyl VinylCache operator to your Plone deployment for operator-managed Varnish caching."
+    "property=og:title": "Deploy with cloud-vinyl cache"
+    "keywords": "Plone, cdk8s, Kubernetes, Varnish, cloud-vinyl, VinylCache, operator, caching"
+---
+
 ```{image} ../_static/kup6s-icon-howto.svg
 :align: center
 :class: section-icon-large
 ```
 
-# Deploy with Cloud-Vinyl Cache
+# Deploy with cloud-vinyl cache
 
 <div class="page-metadata">
   <div class="metadata-content">
@@ -21,7 +30,7 @@
 
 ## Steps
 
-### 1. Add PloneVinylCache to Your Deployment
+### 1. Add PloneVinylCache to your deployment
 
 ```typescript
 import { Plone, PloneVinylCache } from '@bluedynamics/cdk8s-plone';
@@ -37,7 +46,7 @@ const cache = new PloneVinylCache(chart, 'cache', {
 });
 ```
 
-### 2. Use the Cache Service in Your IngressRoute
+### 2. Use the cache service in your IngressRoute
 
 The cache exposes a service that should be used as the upstream in your IngressRoute:
 
@@ -46,9 +55,9 @@ The cache exposes a service that should be used as the upstream in your IngressR
 // instead of plone.frontendServiceName
 ```
 
-### 3. Build and Deploy
+### 3. Build and deploy
 
-```bash
+```shell
 npm run build
 # Review generated manifests
 # Deploy via ArgoCD or kubectl apply
@@ -56,7 +65,7 @@ npm run build
 
 ### 4. Verify
 
-```bash
+```shell
 # Check VinylCache status
 kubectl get vinylcache -n <namespace>
 
@@ -66,7 +75,7 @@ kubectl get pods -n <namespace> -l app.kubernetes.io/managed-by=cloud-vinyl
 
 ## Customization
 
-### Sizing the Cache Storage
+### Sizing the cache storage
 
 Without an explicit `storage` entry, the operator ships varnishd with its
 stock default (~100 MB malloc) — almost always too small. Set a malloc size
@@ -105,7 +114,7 @@ new PloneVinylCache(chart, 'cache', {
 });
 ```
 
-### Cache Invalidation
+### Cache invalidation
 
 Invalidation is enabled by default (PURGE, BAN, xkey). Configure `plone.cachepurging` to point to the VinylCache invalidation proxy endpoint.
 
@@ -123,7 +132,7 @@ new PloneVinylCache(chart, 'cache', {
 });
 ```
 
-### Shard Director Tuning
+### Shard director tuning
 
 For shard-based load distribution (the default), you can fine-tune the consistent-hash behavior. These options require **cloud-vinyl ≥ 0.4.2** to be honored by the generated VCL.