Installation

Docker Compose is the quickest way to run the full platform. Kubernetes deployment support is available through Kustomize overlays under infra/k8s.

Runtime installation

Clone the repository and use either compose.dev.yaml, compose.prod.yaml, or the Kubernetes setup workflow. The development Compose profile builds local images and exposes debugging ports. The production Compose profile uses GHCR images, internal networking, resource constraints, worker replicas, and Nginx as the public entry point.

scripts/k8s/setup.sh --mode local --create-kind

The setup script prepares required Secrets and certificates before applying the local Kustomize overlay. Direct kubectl apply -k is supported only after those prerequisites exist; see Kubernetes deployment.

Development toolchain

• Go 1.27.3
• Node.js 26.12.0 for both the static-site CI path and dashboard container builds
• Buf matching the buf-version default in .github/actions/setup-go-env/action.yaml for protobuf generation
• Docker for integration tests and container execution tests
• Python 3 for the integration-test launcher; match the CRAP job in .github/workflows/ci.yaml when reproducing coverage reports

make tools
make dependencies
make mockgen # after changing generated-mock interfaces
make test/short
make lint
make build/all

The go directive in go.mod, Dockerfile base images, and CI toolchain settings define the build requirements. Check these files when updating a local toolchain rather than assuming an older installed version is compatible.

Frontend workspaces

The application dashboard and public static site are separate Next.js applications:

cd dashboard && npm ci
cd ../static && npm ci

Both workspaces commit their lockfiles and pin direct dependencies exactly. Use npm ci so local and CI installs reproduce the reviewed dependency graph.

ESLint and TypeScript upgrades must also satisfy the dependencies of eslint-config-next. A deprecation warning from ESLint does not mean npm ci failed: the committed version currently preserves the React lint plugin's supported peer range. Do not use --force or --legacy-peer-deps to hide a conflict. Recheck the upstream peer ranges before upgrading the linter.

The static site exports plain HTML into static/out and is deployed to GitHub Pages.

Production preparation

Replace development credentials, generated local certificate assumptions, public hostnames, allowed origins, and cookie policy before exposing the stack. Continue with production deployment and certificates and security.