Local Development Setup

Overview

This guide walks through the complete local development setup for AltBase. By the end, you will have the Rust server compiling and running, infrastructure services up in Docker, and the dashboard app running in dev mode.

For day-to-day development, you typically start the infrastructure once and then iterate on the Rust server and React apps separately.

---

Prerequisites

You need the following tools installed before running the bootstrap script:

Tool	Version	Install
Git	Any recent	git-scm.com
Rust	Stable (latest)	rustup.rs
Node.js	20+	nodejs.org
npm	Bundled with Node.js	Comes with Node.js
Docker	Desktop or Engine with Compose	docker.com

Verify everything is available:

git --version
rustc --version
cargo --version
node --version
npm --version
docker --version
docker compose version

The bootstrap script checks for these commands and will exit with a clear error if any are missing.

---

Step 1: Clone and Enter the Repository

git clone https://github.com/AltbaseDB/AltBaseDb.git
cd altbase

---

Step 2: Run the Bootstrap Script

The bootstrap script automates environment setup, dependency installation, and optionally starts infrastructure services.

Windows (PowerShell):

.\scripts\bootstrap.ps1 -StartInfra

macOS / Linux (Bash):

./scripts/bootstrap.sh --start-infra

What the Bootstrap Script Does

1. Checks prerequisites — verifies git, cargo, node, npm, and docker are on the PATH
2. Creates .env — copies .env.example to .env if it does not already exist
3. Installs npm dependencies for three packages:
   • apps/dashboard (platform admin UI)
   • sdk/js (JavaScript/TypeScript SDK)
   • cli (command-line interface)
4. Starts infrastructure (with -StartInfra / --start-infra) — runs Docker Compose in detached mode for Postgres, Redis, NATS, Azurite, and Nango

Bootstrap Script Options

PowerShell (bootstrap.ps1):

Flag	Effect
-StartInfra	Start Docker infrastructure after setup
-SkipInstall	Skip all npm installs
-IncludeE2E	Also install dependencies in tests/e2e
-Help	Show usage information

Bash (bootstrap.sh):

Flag	Effect
--start-infra	Start Docker infrastructure after setup
--skip-install	Skip all npm installs
--include-e2e	Also install dependencies in tests/e2e
-h, --help	Show usage information

---

Step 3: Environment Configuration

The .env file is created from .env.example by the bootstrap script. The defaults work for local development without modification:

ATLAS_HOST=0.0.0.0
ATLAS_PORT=3000
ATLAS_CONTROL_PLANE_DATABASE_URL=postgres://atlas:atlas_dev@localhost:5433/atlas_control_plane
ATLAS_TENANT_DATABASE_URL=postgres://atlas:atlas_dev@localhost:5433/atlas_tenants
ATLAS_REDIS_URL=redis://localhost:6379
ATLAS_DB_POOL_SIZE=20

Note that the Postgres port is 5433 (not the default 5432) to avoid conflicts with any local Postgres installation.

---

Step 4: Start Infrastructure Services

If you did not use the -StartInfra flag, start infrastructure manually:

docker compose -f docker/docker-compose.yml up -d postgres redis nats azurite nango

This starts five services in detached mode:

Service	Port	Purpose
PostgreSQL 16	5433	Control plane + tenant databases (WAL level set to logical for CDC)
Redis 7	6379	Cache, sessions, rate limits, TUS upload state
NATS	4222, 8222	JetStream messaging for CDC, events, jobs, workflows
Azurite	10000, 10001	Local S3-compatible blob storage
Nango	3003	Integration platform for OAuth connectors

Check that everything is healthy:

docker compose -f docker/docker-compose.yml ps

All services should show a "healthy" or "running" status.

---

Step 5: Run the Rust Server

With infrastructure running, start the Atlas server:

cargo run -p atlas-server

The first build compiles all 23 workspace crates and their dependencies. This takes several minutes. Subsequent builds are incremental and much faster.

Once the server starts, verify it:

curl http://localhost:3000/health/live
curl http://localhost:3000/health/ready

Both should return 200 OK.

---

Step 6: Run the Dashboard (Dev Mode)

The dashboard is a React 19 + Vite + TypeScript application:

cd apps/dashboard
npm ci
npm run dev

The Vite dev server starts on http://localhost:5173 with hot module replacement. Changes to dashboard code are reflected immediately in the browser.

---

Running SDK and CLI in Development

JavaScript SDK

cd sdk/js
npm install
npm run build
npm test

CLI

cd cli
npm install
npm run build

---

Quality Checks

Run these checks before opening a pull request. Focus on the checks relevant to the code you changed.

Rust Checks

# Format check
cargo fmt --all -- --check

# Lint (all warnings are errors)
cargo clippy --workspace -- -D warnings

# Test suite
cargo test --workspace

Dashboard Checks

cd apps/dashboard
npm ci
npx tsc --noEmit
npm run build

SDK Checks

cd sdk/js
npm install
npx tsc --noEmit
npm test

CLI Checks

cd cli
npm install
npx tsc --noEmit
npm run build

End-to-End Tests

To run the API end-to-end tests, first install dependencies (or use --include-e2e during bootstrap):

cd tests/e2e
npm install

The E2E tests require the server and infrastructure to be running.

---

Common Workspace Commands

# Check all crates compile
cargo check --workspace

# Run all Rust tests
cargo test --workspace

# Build the dashboard for static serving
cd apps/dashboard && npm run build

# Run dashboard E2E tests
cd apps/dashboard && npm run test:e2e

# Build the SDK
cd sdk/js && npm run build

# Build the CLI
cd cli && npm run build

---

Stopping Infrastructure

To stop all Docker services:

docker compose -f docker/docker-compose.yml down

To stop and remove all data volumes (full reset):

docker compose -f docker/docker-compose.yml down -v

---

Project Structure Reference

altbase/
  crates/
    atlas-server/          # Binary entry point, router assembly
    atlas-common/          # Config, errors, telemetry
    atlas-db/              # Connection pools, migrations
    atlas-gateway/         # API key auth, rate limiting, tenant context
    atlas-control-plane/   # Orgs, projects, API keys, provisioning
    atlas-api-engine/      # REST CRUD, SQL, schema, vector search
    atlas-auth/            # Auth, OAuth, OIDC, SAML, SSO, B2B
    atlas-storage/         # Buckets, objects, TUS, signed URLs
    atlas-realtime/        # WebSocket, CDC, broadcast, presence, cron
    atlas-cdc-fanout/      # Postgres WAL to NATS JetStream
    atlas-events/          # NATS pub/sub, JetStream streams
    atlas-jobs/            # Background job queue, worker
    atlas-search/          # Tantivy full-text indexing
    atlas-analytics/       # Materialized views
    atlas-billing/         # Stripe checkout, subscriptions, usage
    atlas-integrations/    # Nango OAuth, webhooks, circuit breaker
    atlas-functions/       # QuickJS + Wasmtime runtimes
    atlas-triggers/        # Unified event trigger system
    atlas-workflows/       # DAG workflow engine
    atlas-vector/          # Embeddings, vector search, RAG, LLM
    atlas-graphql/         # Auto-generated GraphQL schema
    atlas-mcp/             # Model Context Protocol server
    atlas-replication/     # Data replication
  apps/dashboard/          # React 19 + Vite operator UI
  sdk/js/                  # TypeScript SDK (@altbasedb/sdk)
  sdk/react/               # React hooks (@altbase/react)
  sdk/python/              # Python SDK (altbasedb)
  sdk/dart/                # Dart/Flutter SDK (altbasedb)
  sdk/workflows/           # Workflow SDK (@altbase/workflows)
  cli/                     # CLI (@altbasedb/cli)
  docker/                  # Docker Compose + Dockerfile
  tests/e2e/               # API end-to-end tests
  scripts/                 # Bootstrap scripts (PS1, Bash)
  docs/                    # Internal design docs and test catalogs

---

Troubleshooting

cargo run fails with linker errors: Make sure the Rust stable toolchain is installed via rustup. On Linux, you may need build-essential or equivalent C toolchain packages.

PostgreSQL connection refused: Check that Docker is running and the Postgres container is healthy. The local .env connects to port 5433, not the default 5432.

npm ci fails in dashboard: Delete node_modules and package-lock.json in the affected package directory and run npm install again.

Slow first Rust compile: The workspace has 23 crates plus dependencies. The first full build can take 5-10 minutes depending on hardware. Use cargo check --workspace for faster feedback during development (skips code generation).

---

Next Steps

• Read the Architecture Overview to understand how the 23 crates fit together
• Check CONTRIBUTING.md in the repository root for pull request guidelines
• Browse docs/testing/ for the feature inventory and test catalogs