Development Setup

Prerequisites

No local Gradle builds. Java services are built inside Docker images. Compile DSL with the causet CLI (causet build compile), not ./gradlew.

Get the source

Causet source is private. Team members receive repository access from engineering — there is no public clone URL.

# After access is granted:
git clone <your-internal-remote>
cd Causet

Start the Local Stack

The local stack runs PostgreSQL, Kafka, Redis, and MinIO (S3-compatible) via Docker Compose.

docker compose up -d

Verify all containers are healthy:

docker compose ps

Wait for all services to show Up (healthy) before starting the application services.

Build All Services

docker compose build

This builds all service images. To skip a service:

docker compose build causet-runtime-service

Build Individual Services

Use the rebuild scripts in shell_files/:

# Runtime service
./shell_files/rebuild-runtime.sh
 
# Projection worker
./shell_files/rebuild-projection-worker.sh
 
# Query service
./shell_files/rebuild-query-service.sh
 
# SaaS cloud
./shell_files/rebuild-saas.sh

Run Services Locally

Use the rebuild scripts or Docker Compose:

# Start all services
docker compose up -d
 
# Restart a specific service after code changes
./shell_files/rebuild-runtime.sh

Check shell_files/ for rebuild scripts for each service.

Build and Run the Compiler

The compiler is bundled in the Causet CLI. Compile a sample app:

causet build compile --runtime ./examples/concert-app --out ./build/concert-app-out

Control Plane (Next.js)

cd apps/causet-cloud-control-plane
npm install
npm run dev

The control plane starts on port 3000. Configure Clerk keys in apps/causet-cloud-control-plane/.env.local:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
CAUSET_SAAS_URL=http://localhost:8085
CAUSET_QUERY_URL=http://localhost:8082

Build the CLI

Install a released binary:

curl -fsSL https://raw.githubusercontent.com/Causet-Inc/causet-cli/main/install.sh | sh

When developing changes to apps/causet-cli itself:

cd apps/causet-cli
go build -o causet .
# Optional: add to PATH
export PATH="$PATH:$(pwd)"

Run tests:

go test ./...

Run All Tests

# All service tests
docker compose run --rm test-runner
 
# Integration tests (requires Docker Compose running)
docker compose run --rm integration-tests

Development Workflow

The typical loop for a platform change:

1. Edit source (.causet fixtures, service code, or compiler logic)
2. Build in Docker: docker compose build <service> (or ./shell_files/rebuild-*.sh)
3. Run locally: docker compose up -d and verify end-to-end
4. Commit your changes
5. Publish: push to main — CI builds container images and tags them; cut a release tag to publish CLI binaries

For a DSL or compiler change:

1. Edit .causet fixtures or compiler source
2. Run compiler tests: docker compose run --rm test-runner causet-compiler
3. Compile a sample app: causet build compile --runtime ./examples/concert-app --out ./build/out
4. Rebuild affected service images and restart: ./shell_files/rebuild-runtime.sh
5. Submit an intent and verify the result end-to-end

For a projection worker change:

1. Edit projection worker source
2. Rebuild: ./shell_files/rebuild-projection-worker.sh
3. Submit an intent that produces the relevant event
4. Verify the projection table is updated correctly

Service Ports (Local)

Common Issues

Compiler fails with Java version error: Java builds happen inside Docker — rebuild the image (docker compose build causet-compiler) rather than running Gradle locally.

Docker Compose containers not starting: Check for port conflicts. Run lsof -i :5432 to identify what is using the default PostgreSQL port.

Integration tests failing: Verify all Docker Compose services are healthy before running integration tests. The tests do not wait for services to be ready.

Control plane not connecting to backend: Check .env.local in the control plane directory. Ensure CAUSET_SAAS_URL matches the running SaaS service port.