Quick Start

Quick Start

Get CellState running locally for development.

Prerequisites

• Rust 1.75+ (install via rustup)
• PostgreSQL 18 with the pgvector extension
• Bun (for TypeScript SDK and tests)
• Make (GNU Make)

1. Clone and Install

git clone https://github.com/TheFreeBatteryFactory/CellState.git
cd cellstate

# Install Rust tools (cargo-nextest, cargo-pgrx, etc.) and Node deps
make setup

2. Database Setup

# Start PostgreSQL (if not already running)
make db-start

# Install the pgrx extension and apply schema
make db-setup

# Or just apply schema without rebuilding the extension:
make db-migrate

This creates a cellstate database with all tables, RLS policies, triggers, and the cellstate_pg extension.

3. Start the API Server

make dev-api

The server starts on http://localhost:3000. If you use Doppler for secrets, it will automatically inject environment variables. Otherwise, create a .env file in the project root (see Environment Variables).

4. Verify

# Liveness
curl http://localhost:3000/health/ping
# → {"status":"ok"}

# Readiness (checks database connectivity)
curl http://localhost:3000/health/ready
# → {"status":"ok","database":"ok"}

5. Run Tests

# Core unit + property tests (no database required)
make test

# Rust unit tests only
make test-rust-core

# Database-backed API tests (requires running PostgreSQL)
make test-api-db

# Full CI-equivalent chain
make test-ci-local

# Lint
make lint

6. Build for Release

# Optimized release binary
make build

# With OpenAPI docs generation
make build-openapi

The release binary is at target/release/cellstate-api.

Development Workflow

make dev-watch     # Auto-reload on code changes
make fmt           # Auto-fix formatting (rustfmt + biome)
make lint          # Check formatting + clippy + biome
make bench         # Run Criterion benchmarks
make coverage      # Generate test coverage report

Run make help for the full list of targets.

Next Steps

• Architecture — how the system fits together
• Mental Model — core concepts (cells, events, mutations)
• Operations — environment variables, deployment, monitoring
• Contributing guidance in the CellState source repository — code style and PR conventions