@bluedynamics/cdk8s-plone 0.1.43 → 0.1.44

package/documentation/sources/reference/index.md

@@ -1,68 +1,41 @@
 ---
 myst:
   html_meta:
-    "description": "Information-oriented technical reference for cdk8s-plone constructs, configuration options, and APIs."
-    "property=og:description": "Information-oriented technical reference for cdk8s-plone constructs, configuration options, and APIs."
+    "description": "Information-oriented technical reference for cdk8s-plone: the generated API reference and a task-oriented configuration guide."
+    "property=og:description": "Information-oriented technical reference for cdk8s-plone: the generated API reference and a task-oriented configuration guide."
     "property=og:title": "Reference"
     "keywords": "Plone, cdk8s, Kubernetes, reference, API, configuration"
 ---
 
-```{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.
+**Information-oriented technical specifications for cdk8s-plone.**
 
-## API reference
+The reference has two parts that play different roles:
 
-*This section will contain auto-generated or detailed documentation for:*
-- Main chart classes
-- Configuration interfaces
-- Individual construct classes
-- Utility functions and validators
+{doc}`API reference <api/index>`
+:   The complete, authoritative list of every construct, interface, option, type, default value, and enum.
+    It is generated from the TypeScript source with `npx projen docgen`, so it never drifts from the code.
+    Use it to look up exactly what an option does, its type, and whether it is required.
 
-## Configuration reference
+{doc}`Configuration guide <configuration-options>`
+:   A hand-written, task-oriented tour of the most common configuration, with copy-pasteable examples.
+    It links into the API reference rather than repeating it.
+    Use it to see how options fit together for a real deployment.
 
 ```{toctree}
 ---
 maxdepth: 1
 titlesonly: true
 ---
+api/index
 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.
+**Getting started?** Begin with the {doc}`/tutorials/index` for hands-on learning.
 
-**Solving a specific problem?** Check the [How-To Guides](../how-to/index.md) for task-oriented solutions.
+**Solving a specific problem?** Check the {doc}`/how-to/index` for task-oriented solutions.
 
-**Understanding concepts?** Read the [Explanation](../explanation/index.md) section for architecture and design.
+**Understanding concepts?** Read the {doc}`/explanation/index` for architecture and design.

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

@@ -15,7 +15,7 @@ This tutorial will guide you through deploying your first Plone instance using c
 
 Before you start, ensure you have:
 
-- **Node.js 16+** and npm installed
+- **Node.js 18+** and npm installed
 - **kubectl** configured to access your Kubernetes cluster
 - Basic familiarity with Kubernetes and TypeScript
 - A Kubernetes cluster (local or remote)

package/documentation/sources/tutorials/index.md

@@ -7,11 +7,6 @@ myst:
     "keywords": "Plone, cdk8s, Kubernetes, tutorials, getting started"
 ---
 
-```{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.**
@@ -20,12 +15,13 @@ Tutorials are lessons that help you gain practical skills and familiarity with c
 
 ## What you'll learn
 
-These tutorials will teach you how to:
+The quick start teaches you how to:
+
+- Define a Plone deployment with the `Plone` construct
+- Synthesize Kubernetes manifests with `cdk8s synth`
+- Apply the manifests and reach the running site
 
-- Deploy a basic Plone instance using cdk8s-plone
-- Configure PostgreSQL backend
-- Customize component resources and settings
-- Test your deployment
+For tasks beyond the first deployment, such as configuring a database, caching, or scaling, see the {doc}`/how-to/index`.
 
 ## Available tutorials
 
@@ -41,7 +37,7 @@ titlesonly: true
 
 These tutorials assume you have:
 - Basic familiarity with Kubernetes concepts
-- Node.js 16+ and npm installed
+- Node.js 18+ and npm installed
 - A Kubernetes cluster (local or remote)
 - kubectl configured to access your cluster
 - Basic TypeScript knowledge

package/examples/blicca/.env.example

@@ -15,5 +15,6 @@ CLUSTER_ISSUER=letsencrypt-prod
 #PLONE_BACKEND_IMAGE=plone/plone-backend:6.1.3
 
 # Configure database backend
-# Options: 'bitnami' (default, simple) or 'cloudnativepg' (production-ready)
-DATABASE=cloudnativepg
+# Options: 'plain' (default, operator-free single instance) or
+#          'cloudnativepg' (production HA, requires the CloudNativePG operator)
+DATABASE=plain

package/examples/blicca/README.md

@@ -17,7 +17,7 @@ Blicca is the server-side rendered UI of Plone CMS: the Plone backend renders th
 - Migration from older Plone versions (keeping the familiar server-rendered UX)
 - Projects requiring Blicca-specific add-ons
 
-**When to use Volto instead:** See the [production-volto](../production-volto/) example for the React single-page frontend approach.
+**When to use Volto instead:** See the [volto](../volto/) example for the React single-page frontend approach.
 
 ## Features
 
@@ -25,8 +25,8 @@ This example includes:
 
 - **Plone 6.1 with Blicca** (server-side rendering)
 - **PostgreSQL with RelStorage** - Choose between:
+  - Plain single-instance PostgreSQL using the official `postgres` image (default, operator-free, for dev and small setups)
   - [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**:
@@ -52,13 +52,12 @@ npm install
 
 Your cluster needs:
 
-1. **PostgreSQL Operator** (choose one):
-   - **CloudNativePG** (recommended for production):
+1. **PostgreSQL** (choose one):
+   - **Plain** (default, no operator needed): the example deploys a single-instance PostgreSQL StatefulSet using the official `postgres` image, so there is nothing to install.
+   - **CloudNativePG** (recommended for production HA): install the operator
      ```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
@@ -105,8 +104,8 @@ CLUSTER_ISSUER=letsencrypt-prod
 # Plone backend image (defaults to official image if not set)
 PLONE_BACKEND_IMAGE=plone/plone-backend:6.1.3
 
-# Database backend: 'bitnami' (default) or 'cloudnativepg'
-DATABASE=cloudnativepg
+# Database backend: 'plain' (default) or 'cloudnativepg'
+DATABASE=plain
 ```
 
 ### 3. Generate Kubernetes Manifests
@@ -185,24 +184,24 @@ kubectl apply -f dist/plone-blicca.k8s.yaml -n plone
 DATABASE=cloudnativepg
 ```
 
-### Bitnami PostgreSQL (Development/Testing)
+### Plain PostgreSQL (default, operator-free)
 
 **Pros:**
-- No operator required
-- Simple setup
-- Good for development and testing
-- Helm-based deployment
+- No operator and no third-party Helm chart required
+- Uses the official `postgres` image, which is actively maintained
+- Single-instance StatefulSet with a PersistentVolumeClaim
+- Good for development and small production setups
 
 **Cons:**
-- Requires namespace `plone` to be pre-created
-- No built-in HA features
-- Less suitable for production
+- No built-in high availability, failover, or automated backups
 
 **Configuration:**
 ```bash
-DATABASE=bitnami
+DATABASE=plain
 ```
 
+**Secrets:** the example creates a Secret with `username`, `password`, and `database` keys.
+
 ## Development
 
 ### Build and Test
@@ -302,13 +301,11 @@ kubectl get cluster
 kubectl get secret -l cnpg.io/cluster
 ```
 
-**Bitnami:**
+**Plain PostgreSQL:**
 ```bash
-# Check service
-kubectl get svc -l app.kubernetes.io/part-of=plone
-
-# Check secret
-kubectl get secret -l app.kubernetes.io/part-of=plone
+# Check the StatefulSet and pod
+kubectl get statefulset -l app.kubernetes.io/name=plone-postgresql
+kubectl get pods -l app.kubernetes.io/name=plone-postgresql
 ```
 
 ### Access Logs
@@ -322,7 +319,7 @@ kubectl get all -l app.kubernetes.io/part-of=plone
 
 If you later want to migrate to Volto:
 
-1. See the [production-volto](../production-volto/) example
+1. See the [volto](../volto/) example
 2. Keep the same backend configuration (database, caching)
 3. Add Volto frontend deployment
 4. Update ingress to route to frontend