Development Setup

This guide walks you through setting up a local development environment for ChaosPlane.

Prerequisites

• Go 1.22+
• Node.js 22+
• pnpm 9+
• Docker
• kind or k3d for a local cluster
• kubebuilder (for CRD generation)
• buf (for protobuf generation)
• kubectl
• helm

Clone the repo

git clone https://github.com/chaosplane-hq/chaosplane.git
cd chaosplane

Repository structure

chaosplane/
├── api/v1alpha1/          # CRD type definitions
├── cmd/
│   ├── operator/          # Operator main
│   ├── daemon/            # Daemon main
│   ├── api/               # Platform API main
│   └── chaosctl/          # CLI main
├── internal/
│   ├── controller/        # Reconcilers
│   ├── executor/          # Chaos executors
│   │   ├── pod/
│   │   ├── network/
│   │   └── node/
│   ├── webhook/           # Admission webhook
│   └── probe/             # Probe runner
├── gen/daemon/v1/         # Generated gRPC code
├── proto/                 # Protobuf definitions
├── config/                # Kustomize manifests
├── charts/                # Helm chart
└── web/                   # Next.js web UI

Start a local cluster

# Using kind
kind create cluster --name chaosplane-dev

# Or k3d
k3d cluster create chaosplane-dev

Install CRDs

make install
# This runs: kubectl apply -f config/crd/bases/

Run the operator locally

# Run against your current kubeconfig context
make run
# This runs: go run ./cmd/operator/main.go

The operator will use your local kubeconfig and watch all namespaces.

Run the daemon locally

The daemon needs to run on a node. For local development, you can run it in a kind node:

# Build and load the daemon image
make docker-build-daemon
kind load docker-image chaosplane-daemon:dev --name chaosplane-dev

# Deploy the DaemonSet
kubectl apply -f config/daemon/

Run the platform API

make run-api
# This runs: go run ./cmd/api/main.go

The API listens on :8080 by default.

Run the web UI

cd web
pnpm install
pnpm dev

The web UI runs on http://localhost:3000.

Run tests

# Unit tests
make test

# Integration tests (requires a running cluster)
make test-integration

# All tests
make test-all

Generate code

After modifying CRD types in api/v1alpha1/:

# Regenerate deepcopy, CRD manifests, RBAC
make generate
make manifests

After modifying protobuf definitions in proto/:

# Regenerate gRPC code
make proto
# This runs: buf generate

Linting

make lint
# Runs golangci-lint

Building

# Build all binaries
make build

# Build Docker images
make docker-build

# Build and push
make docker-push IMG=your-registry/chaosplane:dev

Running a full local stack

# 1. Create cluster
kind create cluster --name chaosplane-dev

# 2. Install CRDs
make install

# 3. Build and load images
make docker-build
kind load docker-image chaosplane-operator:dev --name chaosplane-dev
kind load docker-image chaosplane-daemon:dev --name chaosplane-dev
kind load docker-image chaosplane-api:dev --name chaosplane-dev

# 4. Deploy with Helm
helm install chaosplane ./charts/chaosplane \
  --namespace chaosplane \
  --create-namespace \
  --set operator.image.tag=dev \
  --set daemon.image.tag=dev \
  --set api.image.tag=dev

# 5. Run the web UI locally
cd web && pnpm dev

Makefile targets

Target	Description
make generate	Run code generation
make manifests	Generate CRD manifests
make install	Install CRDs into cluster
make run	Run operator locally
make test	Run unit tests
make lint	Run linter
make build	Build all binaries
make docker-build	Build Docker images
make proto	Regenerate protobuf code

Pre-commit hooks

The repo uses pre-commit hooks for formatting and linting:

# Install hooks
pre-commit install

# Run manually
pre-commit run --all-files

Submitting a PR

1. Fork the repo
2. Create a branch: git checkout -b feat/my-feature
3. Make your changes
4. Run tests: make test
5. Run lint: make lint
6. Push and open a PR against main

PRs require:

• All tests passing
• Lint clean
• At least one reviewer approval
• Signed commits (git commit -s)