From f3750733f30c2bb87170ab502a640d64dc1474ed Mon Sep 17 00:00:00 2001 From: Zhiqiang ZHOU Date: Sat, 17 Jan 2026 15:25:45 -0800 Subject: [PATCH] docs: update CLAUDE.md with essential development commands and architecture --- CLAUDE.md | 138 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 92 insertions(+), 46 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a266633..73a20f4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,48 +1,94 @@ -# Claude Code Context: Supabase Operator +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview -Building a Kubernetes operator for deploying and managing self-hosted Supabase instances using Kubebuilder framework. - -## Current Technologies -- **Language**: Go 1.22+ -- **Framework**: Kubebuilder v4.0+ -- **Testing**: Ginkgo/Gomega with envtest -- **Container Runtime**: Kubernetes 1.25+ -- **Key Dependencies**: controller-runtime v0.22.1, k8s.io/client-go v0.34.0 - -## Architecture Patterns -- **Controller Pattern**: Idempotent reconciliation loops -- **Status Management**: Granular conditions inspired by Rook operator -- **Component Deployment**: Ordered deployment with health checks -- **External Dependencies**: PostgreSQL and S3 (user-provided only) - -## Key Components -1. **CRD**: SupabaseProject (namespace-scoped) -2. **Managed Services**: Kong, Auth/GoTrue, PostgREST, Realtime, Storage API, Meta -3. **Status Tracking**: Per-component phases and conditions -4. **Secret Management**: JWT generation and API key management - -## Development Guidelines -- Follow Kubebuilder project structure -- Use TDD with envtest for controller testing -- Implement comprehensive status reporting -- Use structured logging with controller-runtime -- Follow Kubernetes API conventions - -## Recent Changes -- 002-helm-chart-release: Added Go 1.22+ (operator code), YAML (Helm charts/workflows) + GitHub Actions, helm-gh-pages action, Helm 3.x -- Initialized Kubebuilder project with domain strrl.dev -- Created SupabaseProject API scaffold - -## Testing Requirements -- Unit tests for reconciliation logic -- Integration tests with envtest -- Contract tests for CRD validation -- E2E tests for deployment scenarios - -## Current Focus -Implementing the SupabaseProject controller with granular status management and component deployment logic. - -## Active Technologies -- Go 1.22+ (operator code), YAML (Helm charts/workflows) + GitHub Actions, helm-gh-pages action, Helm 3.x (002-helm-chart-release) -- GitHub Pages repository for chart hosting (002-helm-chart-release) + +Kubernetes operator for deploying self-hosted Supabase instances using Kubebuilder. A single `SupabaseProject` CRD deploys and manages Kong, Auth/GoTrue, PostgREST, Realtime, Storage API, Meta, and Studio components. + +## Build & Development Commands + +```bash +make build # Compile binary to bin/supabase-operator +make run # Run controller locally (requires k8s cluster) +make check # Run all code generation, formatting, vetting, and linting +make manifests # Generate CRDs into helm/supabase-operator/crds/ +make generate # Generate DeepCopy code for API types +make image # Build Docker image (ghcr.io/strrl/supabase-operator:) +``` + +## Testing + +```bash +make test # Unit tests with envtest (uses Ginkgo/Gomega) +make test-e2e # E2E tests on Minikube with Chrome screenshot capture +``` + +Run a single test file: +```bash +go test ./internal/controller/... -v -run TestReconcile +``` + +Run specific Ginkgo specs: +```bash +ginkgo -v --focus="should create kong" ./internal/controller/... +``` + +## Linting + +```bash +make lint # Run golangci-lint +make lint-fix # Auto-fix linting issues +``` + +## Code Architecture + +### CRD and API Types +- `api/v1alpha1/supabaseproject_types.go` - SupabaseProject spec and status definitions +- Spec requires `projectId`, `database.secretRef`, and `storage.secretRef` +- Status tracks phase (Pending → ValidatingDependencies → DeployingSecrets → DeployingComponents → Running → Failed) and per-component status + +### Controller Logic +- `internal/controller/supabaseproject_controller.go` - Main reconciler +- `internal/controller/reconciler/component.go` - Component reconciliation logic +- Controller watches SupabaseProject and manages Deployments, Services, Secrets, ConfigMaps, Jobs + +### Component Builders +Each Supabase component has a dedicated builder in `internal/component/`: +- `kong.go`, `auth.go`, `postgrest.go`, `realtime.go`, `storage_api.go`, `meta.go`, `studio.go` +- `database_init.go` - Creates Job for PostgreSQL initialization + +### Database Migrations +- `internal/database/migrations/sql/` - Embedded SQL scripts (00-initial-schema through 06-pooler) +- Files embedded in binary via `//go:embed` +- Sync with upstream Supabase: `./hack/sync-migrations.sh [tag]` + +### Secrets Management +- `internal/secrets/` - JWT and API key generation +- Operator generates `-jwt` secret with anon-key, service-role-key + +## Key Patterns + +- **Idempotent reconciliation**: Controllers repeatedly reconcile desired vs actual state +- **Finalizers**: Clean up resources when SupabaseProject is deleted +- **Component builder pattern**: Modular resource creation per component file +- **Status conditions**: Kubernetes-standard conditions for granular status tracking + +## External Dependencies + +User must provide: +- PostgreSQL database (referenced via secret with host, port, database, username, password) +- S3-compatible storage (referenced via secret with endpoint, region, bucket, accessKeyId, secretAccessKey) + +## Helm Chart + +Located in `helm/supabase-operator/`. Install: +```bash +helm upgrade --install supabase-operator ./helm/supabase-operator \ + --namespace supabase-operator-system --create-namespace +``` + +## Code Style + +- No end-of-line comments +- No Chinese in code comments