Development Setup

Prerequisites

Tool	Version	Purpose
Rust (stable)	1.77+	Backend server and all crates
Node.js	20+	Dashboard, SDKs, CLI, and tests
Docker Compose	v2+	Infrastructure containers (Postgres, Redis, NATS, Azurite, Nango)
Git	2.x	Source control

Clone and Bootstrap

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

The .env.example file contains defaults that work with the Docker Compose stack.

Start Infrastructure

Start the infrastructure containers (PostgreSQL, Redis, NATS, Azurite, Nango) without building the AtlasDB image:

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

Or use the bootstrap script:

# Linux / macOS
./scripts/bootstrap.sh --start-infra

# Windows
.\scripts\bootstrap.ps1 -StartInfra

Wait for all health checks to pass. PostgreSQL must be ready before the server can start.

Run the Server

cargo run -p atlas-server

The server starts on http://localhost:3000 (or the port in your .env). It compiles all 23 crates on first run, which takes several minutes. Subsequent rebuilds are incremental and much faster.

Run the Dashboard

In a separate terminal:

cd apps/dashboard
npm ci
npm run dev

The Vite dev server starts on http://localhost:5173 with hot module replacement. It proxies API requests to the Rust server at http://localhost:3000.

Running Tests

Rust Tests

# Full workspace test suite
cargo test --workspace

# Check formatting
cargo fmt --all -- --check

# Lint
cargo clippy --workspace -- -D warnings

Run all three before opening a pull request. CI will reject PRs that fail any of these checks.

Dashboard Tests

cd apps/dashboard
npm ci
npx tsc --noEmit    # type check
npm run build        # production build

SDK Tests

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

CLI Tests

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

Project Structure

altbase/
  crates/              # 23 Rust crates (atlas-server, atlas-auth, etc.)
  apps/
    dashboard/         # React admin dashboard
  sdk/
    js/                # JavaScript/TypeScript SDK
    workflows/         # Workflow SDK
  cli/                 # CLI tool
  docker/              # Docker Compose and Dockerfile
  config/              # Configuration files (provider presets)
  scripts/             # Bootstrap and utility scripts
  docs/                # Internal documentation
  tests/               # End-to-end test suites

Quality Bar

Run the checks relevant to your change before opening a PR:

Area	Commands
Rust	cargo fmt --all -- --check, cargo clippy --workspace -- -D warnings, cargo test --workspace
Dashboard	npx tsc --noEmit, npm run build
SDK	npx tsc --noEmit, npm test
CLI	npx tsc --noEmit, npm run build

Pull Request Process

1. Describe the user-visible change in the PR description
2. Call out implications -- schema, API, auth, or infra changes should be explicitly noted
3. Add or update tests when behavior changes
4. Note gaps if any remain, clearly in the PR description
5. Keep PRs small and reviewable -- prefer focused changes over sweeping refactors

Good First Contributions

These are well-scoped starting points for new contributors:

• Documentation and setup fixes
• Focused bug fixes with clear reproduction steps
• Test coverage for untested code paths
• Small UX improvements in the dashboard

When to Open a Discussion First

Open a discussion before starting work on:

• Large architectural refactors
• New public APIs
• Broad schema changes
• Release process changes

This ensures alignment before significant effort is invested.

Troubleshooting

Server fails to start

Verify that all infrastructure containers are healthy:

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

All services should show healthy status. If PostgreSQL is still initializing, wait for its health check to pass.

Port conflicts

The Docker Compose stack uses these ports:

Port	Service
5433	PostgreSQL (mapped from internal 5432)
6379	Redis
4222	NATS client
8222	NATS monitoring
10000	Azurite blob
10001	Azurite queue
3003	Nango
3000	AtlasDB server

If any port is in use, stop the conflicting service or edit the port mappings in docker/docker-compose.yml.

Slow first build

The initial cargo build downloads and compiles all dependencies. This is normal and can take 5-10 minutes depending on your machine. Subsequent builds use the incremental compiler and are much faster.