Development Setup
Prerequisites, local bootstrap, running the server, executing tests, and the pull request process for AltBase contributors.
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
- Describe the user-visible change in the PR description
- Call out implications -- schema, API, auth, or infra changes should be explicitly noted
- Add or update tests when behavior changes
- Note gaps if any remain, clearly in the PR description
- 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.
Environment Variables
Complete reference for every environment variable used by AltBase, grouped by subsystem with defaults and descriptions.
Architecture Deep Dive
Crate-by-crate breakdown of all 23 AltBase crates, the gateway middleware chain, dual-context database design, CDC pipeline, and NATS subject conventions.