@bluedynamics/cdk8s-plone 0.1.5 → 0.1.7

package/CLAUDE.md

@@ -0,0 +1,352 @@
+# Claude Code Project Guide
+
+This document provides context and guidelines for Claude Code when working on this project.
+
+## Project Overview
+
+**cdk8s-plone** is a TypeScript/Python library for deploying Plone CMS to Kubernetes using CDK8S constructs. It provides type-safe infrastructure as code with support for Volto (React frontend) and Classic UI deployments.
+
+## Git Workflow
+
+**IMPORTANT: Never merge directly to `main`**
+
+This project uses a Pull Request workflow:
+
+1. **Create a feature branch** from `main`:
+   ```bash
+   git checkout -b feature/description
+   # or
+   git checkout -b docs/description
+   # or
+   git checkout -b fix/description
+   ```
+
+2. **Make commits** on the feature branch with descriptive messages
+
+3. **Create a Pull Request** to merge into `main`:
+   - Use GitHub UI or `gh` CLI
+   - PRs are required for code review
+   - Never push directly to `main`
+   - Never merge locally to `main`
+
+4. **PR will be reviewed and merged** by maintainers
+
+### Branch Naming Conventions
+
+- `feat/` or `feature/` - New features
+- `fix/` - Bug fixes
+- `docs/` - Documentation changes
+- `chore/` - Maintenance tasks
+- `refactor/` - Code refactoring
+- `test/` - Test additions or changes
+
+## Working with Worktrees
+
+**Recommended for parallel development and multi-instance work**
+
+Git worktrees allow you to work on multiple branches simultaneously without switching contexts. This is especially useful when:
+- Multiple Claude Code instances are working on different features
+- You need to switch between features frequently
+- You want to keep branches completely isolated
+
+### Setting Up Worktrees
+
+**Create a worktree for each feature branch:**
+
+```bash
+# From the main repository
+git worktree add ../cdk8s-plone-feature-name feature/feature-name
+
+# For existing branches
+git worktree add ../cdk8s-plone-docs docs/diataxis-sphinx-skeleton
+
+# For new branches
+git worktree add -b feat/new-feature ../cdk8s-plone-new-feature
+```
+
+**Directory structure with worktrees:**
+```
+~/ws/cdev/
+├── cdk8s-plone/              # Main repository (usually on main branch)
+├── cdk8s-plone-docs/         # Worktree for documentation work
+├── cdk8s-plone-frontend/     # Worktree for frontend features
+└── cdk8s-plone-monitoring/   # Worktree for monitoring features
+```
+
+### Working with Worktrees
+
+**List all worktrees:**
+```bash
+git worktree list
+```
+
+**Remove a worktree when done:**
+```bash
+# Delete the worktree directory first
+rm -rf ../cdk8s-plone-feature-name
+
+# Then prune the worktree reference
+git worktree prune
+```
+
+**Switch between worktrees:**
+```bash
+# Simply cd to the worktree directory
+cd ../cdk8s-plone-docs
+
+# Each worktree is an independent working directory
+# with its own checked out branch
+```
+
+### Worktree Best Practices
+
+1. **One feature per worktree**: Keep each worktree focused on a single feature or task
+2. **Clean up after merge**: Remove worktrees once their branches are merged
+3. **Use descriptive directory names**: Name worktrees after their branch or feature
+4. **Regular git fetch**: Run `git fetch` in any worktree to update all branch references
+5. **Avoid nested worktrees**: Don't create worktrees inside other worktrees
+
+### Example Workflow with Worktrees
+
+```bash
+# Setup: Create worktree for documentation work
+cd ~/ws/cdev/cdk8s-plone
+git worktree add -b docs/add-tutorial ../cdk8s-plone-docs
+
+# Work: Make changes in the worktree
+cd ../cdk8s-plone-docs
+# ... make documentation changes ...
+git add . && git commit -m "docs: add new tutorial"
+git push -u origin docs/add-tutorial
+
+# Create PR using gh CLI
+gh pr create --title "Add new tutorial" --body "..."
+
+# Cleanup: After PR is merged
+cd ~/ws/cdev/cdk8s-plone
+git fetch
+git pull  # Update main branch
+rm -rf ../cdk8s-plone-docs
+git worktree prune
+```
+
+### Benefits of Worktrees
+
+- ✅ **No branch switching**: Keep different features in separate directories
+- ✅ **Parallel work**: Multiple Claude instances can work independently
+- ✅ **Clean state**: Each worktree maintains its own working directory state
+- ✅ **Fast context switching**: Just `cd` between directories
+- ✅ **No uncommitted changes conflicts**: Each worktree is isolated
+
+## Project Structure
+
+```
+.
+├── src/               # TypeScript source code
+│   ├── plone.ts      # Main Plone construct
+│   ├── service.ts    # Service utilities
+│   └── ...
+├── test/             # Jest tests
+├── documentation/    # Sphinx documentation (Diataxis framework)
+│   ├── sources/      # Documentation source files
+│   ├── Makefile      # Build automation (mxmake)
+│   └── README.md     # Documentation contributor guide
+├── .projenrc.ts      # Projen project configuration
+├── API.md            # Auto-generated API documentation
+└── README.md         # Main project README
+```
+
+## Build System
+
+This project uses **Projen** for project management.
+
+**⚠️ DO NOT edit generated files directly**
+
+Generated files include:
+- `package.json`
+- `tsconfig.json`
+- `.gitignore`
+- GitHub Actions workflows (except custom ones)
+- And more...
+
+### Making Changes
+
+1. **Edit `.projenrc.ts`** for project configuration changes
+2. **Run `npx projen`** to regenerate files
+3. **Make code changes** in `src/`
+4. **Run tests**: `npx projen test`
+5. **Update snapshots if needed**: `npx projen test -- -u`
+
+### Common Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npx projen test
+
+# Run tests in watch mode
+npx projen test:watch
+
+# Build (compile + generate bindings)
+npx projen build
+
+# Lint
+npx projen eslint
+
+# Generate API docs
+npx projen docgen
+
+# Package for distribution
+npx projen package-all
+
+# Update project files after .projenrc.ts changes
+npx projen
+```
+
+## Documentation
+
+Documentation uses **Sphinx** with the **Diataxis framework**:
+
+- **Tutorials**: Learning-oriented, step-by-step guides
+- **How-To Guides**: Goal-oriented, problem-solving recipes
+- **Reference**: Information-oriented, technical specifications
+- **Explanation**: Understanding-oriented, concepts and design
+
+### Building Documentation
+
+```bash
+cd documentation
+
+# Build HTML
+make docs
+
+# Live-reload development server
+make docs-live
+
+# Clean and rebuild
+make clean && make docs
+```
+
+### Documentation Deployment
+
+- Documentation auto-deploys to GitHub Pages on push to `main`
+- Workflow: `.github/workflows/documentation.yml`
+- Published at: `https://bluedynamics.github.io/cdk8s-plone/`
+
+## Testing
+
+- **Framework**: Jest
+- **Test location**: `test/` directory
+- **Snapshots**: Used for testing generated Kubernetes manifests
+- **Update snapshots**: `npx projen test -- -u`
+
+## Multi-Language Support
+
+The library is published in multiple languages via JSII:
+
+- **TypeScript/JavaScript**: `@bluedynamics/cdk8s-plone` on npm
+- **Python**: `cdk8s-plone` on PyPI
+
+JSII configuration is in `package.json` under the `jsii` field.
+
+## Code Style
+
+- **Linter**: ESLint with TypeScript support
+- **Style**: Configured via `.projenrc.ts`
+- **Run linter**: `npx projen eslint`
+
+## Commit Messages
+
+Follow conventional commit format:
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `chore`: Maintenance tasks
+- `refactor`: Code refactoring
+- `test`: Test additions or changes
+- `ci`: CI/CD changes
+
+**Example:**
+```
+feat(plone): add support for custom environment variables
+
+Allow passing custom environment variables to backend and frontend
+containers using the cdk8s-plus-30 Env API.
+
+Closes #123
+```
+
+All commits from Claude Code include:
+```
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+## CI/CD
+
+GitHub Actions workflows:
+
+- **build.yml**: Build, test, and package
+- **release.yml**: Create releases and publish to npm/PyPI
+- **upgrade-main.yml**: Dependency upgrades
+- **pull-request-lint.yml**: PR validation
+- **documentation.yml**: Build and deploy docs to GitHub Pages
+
+## Dependencies
+
+### Runtime Dependencies
+
+- `cdk8s` - CDK8S framework
+- `cdk8s-plus-30` - CDK8S plus constructs
+- `constructs` - Construct base classes
+
+### Development Dependencies
+
+- `projen` - Project management
+- `jsii` - Multi-language support
+- `jest` - Testing
+- `typescript` - Language
+- `eslint` - Linting
+
+## Publishing
+
+**Do not manually publish packages**
+
+Publishing is automated via GitHub Actions on release:
+1. Create and push a git tag (via `npx projen release`)
+2. GitHub Actions builds and publishes to npm and PyPI
+3. Release notes are auto-generated
+
+## Important Notes
+
+- **Never merge to main**: Always create PRs
+- **Don't edit generated files**: Use `.projenrc.ts` and run `npx projen`
+- **Update snapshots after changes**: Run `npx projen test -- -u`
+- **Follow Diataxis**: When adding docs, use the correct category
+- **Documentation builds required**: Run `make docs` to verify doc changes
+
+## Resources
+
+- [CDK8S Documentation](https://cdk8s.io/)
+- [Projen Documentation](https://projen.io/)
+- [Diataxis Framework](https://diataxis.fr/)
+- [JSII Documentation](https://aws.github.io/jsii/)
+- [Example Project](https://github.com/bluedynamics/cdk8s-plone-example)
+
+## Maintainer Contact
+
+**Author:** Jens W. Klein (jk@kleinundpartner.at)
+**Organization:** [Blue Dynamics Alliance](https://github.com/bluedynamics)

package/README.md

@@ -1,56 +1,38 @@
 # CDK8S Plone
 
-A CDK8S library for deploying Plone CMS to Kubernetes.
+> TypeScript and Python library for deploying Plone CMS to Kubernetes using CDK8S
 
-This library provides constructs to bootstrap a Plone deployment on a Kubernetes cluster using the [CDK8S](https://cdk8s.io) framework.
+[![npm version](https://badge.fury.io/js/%40bluedynamics%2Fcdk8s-plone.svg)](https://www.npmjs.com/package/@bluedynamics/cdk8s-plone)
+[![PyPI version](https://badge.fury.io/py/cdk8s-plone.svg)](https://pypi.org/project/cdk8s-plone/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 
-## Features
+## Overview
 
-- **Backend**: Plone backend (API with `plone.volto` or Classic-UI)
-- **Frontend**: Plone Volto (modern React-based user interface)
-- **Varnish Caching**: Optional HTTP caching layer using [kube-httpcache](https://github.com/mittwald/kube-httpcache) with cluster-wide cache invalidation
-- **High Availability**: Configurable replicas with PodDisruptionBudgets
-- **Multi-language Support**: Published to npm (TypeScript/JavaScript) and PyPI (Python)
+cdk8s-plone provides CDK8S constructs for deploying [Plone CMS](https://plone.org/) on Kubernetes. Define your infrastructure using TypeScript or Python and generate Kubernetes manifests automatically.
 
+**Key Features:**
+- 🚀 Supports Volto (modern React frontend) and Classic UI
+- 📦 High availability with configurable replicas
+- ⚡ Optional Varnish HTTP caching layer
+- 🔧 Fine-grained resource and probe configuration
+- 🌍 Multi-language support (TypeScript/JavaScript and Python)
+- ✅ Type-safe infrastructure as code
 
-## Installation
-
-### TypeScript/JavaScript
-
-Create a new CDK8S project (or use an existing one):
-
-```bash
-cdk8s init typescript-app
-```
+## Quick Start
 
-Install the library:
+### Installation
 
+**TypeScript/JavaScript:**
 ```bash
 npm install @bluedynamics/cdk8s-plone
 ```
 
-Package: [@bluedynamics/cdk8s-plone](https://www.npmjs.com/package/@bluedynamics/cdk8s-plone)
-
-### Python
-
-Create a new CDK8S project:
-
-```bash
-cdk8s init python-app
-```
-
-Install the library:
-
+**Python:**
 ```bash
 pip install cdk8s-plone
 ```
 
-Package: [cdk8s-plone](https://pypi.org/project/cdk8s-plone/)
-
-
-## Quick Start
-
-### Basic Plone Deployment
+### Basic Example
 
 ```typescript
 import { App, Chart } from 'cdk8s';
@@ -62,7 +44,7 @@ const chart = new Chart(app, 'PloneDeployment');
 new Plone(chart, 'my-plone', {
   variant: PloneVariant.VOLTO,
   backend: {
-    image: 'plone/plone-backend:6.0.10',
+    image: 'plone/plone-backend:6.1.3',
     replicas: 3,
   },
   frontend: {
@@ -74,174 +56,86 @@ new Plone(chart, 'my-plone', {
 app.synth();
 ```
 
-### With Varnish HTTP Cache
-
-```typescript
-import { PloneHttpcache } from '@bluedynamics/cdk8s-plone';
-
-const plone = new Plone(chart, 'my-plone', {
-  variant: PloneVariant.VOLTO,
-  backend: { image: 'plone/plone-backend:6.0.10' },
-  frontend: { image: 'plone/plone-frontend:16.0.0' },
-});
-
-new PloneHttpcache(chart, 'cache', {
-  plone: plone,
-  existingSecret: 'varnish-secret',
-  replicas: 2,
-});
-```
-
-### Generate Kubernetes Manifests
-
+Generate Kubernetes manifests:
 ```bash
 cdk8s synth
+kubectl apply -f dist/
 ```
 
-The manifests are stored in the `dist/` directory.
-
-For a complete example, see the [example project](https://github.com/bluedynamics/cdk8s-plone-example).
-
-## Prerequisites
-
-- **kubectl** - Command-line tool for deploying Kubernetes manifests. [Install kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
-- **Helm** (optional) - Only needed if generating Helm charts. [Install Helm](https://helm.sh/docs/intro/install/)
-- **Node.js** - For TypeScript/JavaScript development
-- **Python 3.8+** - For Python development
-
-
-## API Documentation
-
-For complete API documentation, see [API.md](./API.md).
+## Documentation
 
-### Key Constructs
+**📚 Full documentation:** https://bluedynamics.github.io/cdk8s-plone/
 
-#### `Plone`
+- [Quick Start Tutorial](https://bluedynamics.github.io/cdk8s-plone/tutorials/01-quick-start.html)
+- [Configuration Reference](https://bluedynamics.github.io/cdk8s-plone/reference/configuration-options.html)
+- [Architecture Overview](https://bluedynamics.github.io/cdk8s-plone/explanation/architecture.html)
+- [Complete API Documentation](./API.md)
 
-Main construct for deploying Plone CMS. Supports two variants:
-- **VOLTO**: Modern React frontend with REST API backend (default)
-- **CLASSICUI**: Traditional server-side rendered Plone
+## Examples
 
-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')
+See the [cdk8s-plone-example](https://github.com/bluedynamics/cdk8s-plone-example) repository for complete working examples.
 
-#### `PloneHttpcache`
+### Prometheus Metrics
 
-Varnish HTTP caching layer using the [kube-httpcache](https://github.com/mittwald/kube-httpcache) Helm chart.
+Enable Prometheus ServiceMonitor for metrics collection (requires Prometheus Operator):
 
-Properties:
-- `httpcacheServiceName` - Name of the Varnish service
-
-### Configuration Options
-
-#### `PloneOptions`
-
-- `version` - Version of your project
-- `siteId` - Plone site ID (default: 'Plone')
-- `variant` - PloneVariant.VOLTO or PloneVariant.CLASSICUI (default: VOLTO)
-- `backend` - Backend configuration (PloneBaseOptions)
-- `frontend` - Frontend configuration (PloneBaseOptions, required for VOLTO)
-- `imagePullSecrets` - Image pull secrets for private registries
-
-#### `PloneBaseOptions`
-
-Configuration for backend or frontend:
-
-**Container:**
-- `image` - Container image (e.g., 'plone/plone-backend:6.0.10')
-- `imagePullPolicy` - Pull policy (default: 'IfNotPresent')
-- `replicas` - Number of replicas (default: 2)
-- `environment` - Environment variables (cdk8s-plus-30.Env)
-
-**Resources:**
-- `requestCpu` / `limitCpu` - CPU requests/limits
-- `requestMemory` / `limitMemory` - Memory requests/limits
-
-**High Availability:**
-- `minAvailable` - Min pods during updates (for PodDisruptionBudget)
-- `maxUnavailable` - Max unavailable pods during updates
-
-**Health Probes:**
-- `readinessEnabled` - Enable readiness probe (default: true)
-- `readinessInitialDelaySeconds` / `readinessTimeoutSeconds` / `readinessPeriodSeconds`
-- `readinessSuccessThreshold` / `readinessFailureThreshold`
-- `livenessEnabled` - Enable liveness probe (default: false, recommended true for frontend)
-- `livenessInitialDelaySeconds` / `livenessTimeoutSeconds` / `livenessPeriodSeconds`
-- `livenessSuccessThreshold` / `livenessFailureThreshold`
-
-**Annotations:**
-- `annotations` - Deployment metadata annotations
-- `podAnnotations` - Pod template annotations (e.g., for Prometheus)
-- `serviceAnnotations` - Service annotations (e.g., for external-dns)
+```typescript
+new Plone(chart, 'my-plone', {
+  backend: {
+    servicemonitor: true,
+    metricsPath: '/metrics',  // optional, defaults to '/metrics'
+  },
+  frontend: {
+    servicemonitor: true,
+    metricsPort: 9090,  // optional, defaults to service port
+  },
+});
+```
 
-#### `PloneHttpcacheOptions`
+**Note:** You must instrument your Plone backend/frontend to expose metrics at the configured endpoint. For Volto/Node.js frontends, consider using [prom-client](https://www.npmjs.com/package/prom-client) or [express-prometheus-middleware](https://www.npmjs.com/package/express-prometheus-middleware).
 
-- `plone` - Plone construct to attach cache to (required)
-- `varnishVcl` - VCL configuration as string
-- `varnishVclFile` - Path to VCL configuration file
-- `existingSecret` - Kubernetes secret for Varnish admin credentials
-- `replicas` - Number of Varnish replicas (default: 2)
-- `requestCpu` / `limitCpu` - CPU resources
-- `requestMemory` / `limitMemory` - Memory resources
-- `servicemonitor` - Enable Prometheus ServiceMonitor (default: false)
-- `exporterEnabled` - Enable Prometheus exporter sidecar (default: true)
-- `chartVersion` - kube-httpcache Helm chart version (default: latest)
-- `appVersion` - kube-httpcache container image version (default: chartVersion or chart default)
+## Requirements
+- **kubectl** - [Install kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)
+- **Node.js 16+** (for TypeScript/JavaScript) - [Install Node.js](https://nodejs.org/)
+- **Python 3.8+** (for Python) - [Install Python](https://www.python.org/)
+- **Kubernetes cluster** (local or cloud)
 
+For detailed setup instructions, see [Setup Prerequisites](https://bluedynamics.github.io/cdk8s-plone/how-to/setup-prerequisites.html).
 
 ## Development
 
-This project uses [Projen](https://projen.io/) to manage project configuration. **Do not edit generated files directly.**
-
-### Setup
-
-Clone the repository and install dependencies:
+This project uses [Projen](https://projen.io/) for project management.
 
 ```bash
-nvm use lts/*
-corepack enable
-npx projen
-```
+# Install dependencies
+npm install
 
-### Common Commands
-
-```bash
 # Run tests
-npx projen test
+npm test
 
-# Run tests in watch mode
-npx projen test:watch
+# Build
+npm run build
 
-# Build (compile TypeScript + generate JSII bindings)
-npx projen build
-
-# Lint
-npx projen eslint
-
-# Generate API documentation
-npx projen docgen
-
-# Package for distribution
-npx projen package-all
+# Update project configuration
+# Edit .projenrc.ts, then run:
+npx projen
 ```
 
-### Making Changes
+For detailed development instructions, see [CONTRIBUTING.md](./CONTRIBUTING.md) (if available).
 
-1. Edit `.projenrc.ts` for project configuration changes
-2. Run `npx projen` to regenerate project files
-3. Make code changes in `src/`
-4. Run tests and update snapshots if needed: `npx projen test -- -u`
-
-## References
+## Resources
 
 - [CDK8S Documentation](https://cdk8s.io/)
-- [Kubernetes Probes Documentation](https://kubernetes.io/docs/concepts/configuration/liveness-readiness-startup-probes/)
-- [kube-httpcache Helm Chart](https://github.com/mittwald/kube-httpcache)
+- [Plone CMS](https://plone.org/)
+- [kube-httpcache](https://github.com/mittwald/kube-httpcache) (for HTTP caching)
 - [Example Project](https://github.com/bluedynamics/cdk8s-plone-example)
 
 ## License
 
-See [LICENSE](./LICENSE) file.
+[Apache 2.0](LICENSE)
+
+## Maintainers
+
+Maintained by [Blue Dynamics Alliance](https://github.com/bluedynamics)
+
+**Author:** Jens W. Klein (jk@kleinundpartner.at)