Quickstart
Get AltBase running locally in five minutes with Docker Compose — infrastructure, server, health checks, and your first SDK query.
Overview
This guide gets you from zero to a running AltBase instance in about five minutes. You will start the full Docker Compose stack (Postgres, Redis, NATS, Azurite, Nango, and the Atlas server), verify health endpoints, run your first SDK query, and log into the dashboard.
Prerequisites
Before you begin, make sure you have the following installed:
| Tool | Minimum Version | Purpose |
|---|---|---|
| Rust | Stable (latest) | Compiles the Atlas server binary |
| Node.js | 20+ | Dashboard, SDK, and CLI |
| Docker | Desktop or Engine with Compose | Runs infrastructure services |
Verify your installations:
rustc --version
node --version
docker --version
docker compose version
Step 1: Clone the Repository
git clone https://github.com/AltbaseDB/AltBaseDb.git
cd altbase
Step 2: Set Up Environment Variables
Copy the example environment file to create your local .env:
cp .env.example .env
The default .env contains everything needed for local development:
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
You do not need to change any values for the quickstart path.
Step 3: Start the Full Stack with Docker Compose
The fastest path is to let Docker Compose build and run everything:
docker compose -f docker/docker-compose.yml up --build
This starts six services:
| Service | Port | Description |
|---|---|---|
| PostgreSQL 16 | 5433 | Control plane database + tenant database (WAL level set to logical for CDC) |
| Redis 7 | 6379 | Cache, sessions, rate limiting, TUS upload state |
| NATS | 4222 (client), 8222 (monitoring) | JetStream messaging for CDC, events, jobs, workflows |
| Azurite | 10000 (blob), 10001 (queue) | S3-compatible local object storage |
| Nango | 3003 | Integration platform for 500+ SaaS connectors |
| Atlas | 3000 | The AltBase server (single Rust binary) |
PostgreSQL automatically initializes two databases on first boot:
atlas_control_plane— platform metadata (orgs, projects, API keys)atlas_tenants— application data with per-project schemas
Wait until you see health check passes in the Docker logs. The Atlas service depends on Postgres, Redis, and Nango being healthy before it starts.
Step 4: Verify Health Endpoints
Once the stack is running, check the two health endpoints:
# Liveness — is the process running?
curl http://localhost:3000/health/live
# Readiness — are all dependencies connected?
curl http://localhost:3000/health/ready
Both should return a 200 OK response. If /health/ready fails, the server is still waiting for a dependency. Check the Docker logs for connection errors.
Step 5: Your First SDK Query
Install the JavaScript SDK in any Node.js project:
npm install @altbasedb/sdk
Then create a client and make your first query:
import { createClient } from "@altbasedb/sdk";
const altbase = createClient(
"http://localhost:3000",
"your-api-key-here"
);
// Query a table via the auto-generated REST API
const { data, error } = await altbase
.from("your_table")
.select("*");
console.log(data);
To get an API key, you need to create an organization and project first. You can do this through the dashboard (next step) or via the platform API:
# Create a platform user
curl -X POST http://localhost:3000/v1/platform/signup \
-H "Content-Type: application/json" \
-d '{"email": "admin@example.com", "password": "your-password"}'
# After login, create an org and project through the API
# The response will include your API keys
Step 6: Access the Dashboard
The dashboard is the operator UI for managing organizations, projects, API keys, auth settings, storage buckets, and more.
If you are running via Docker Compose: The server serves the dashboard statically when apps/dashboard/dist exists in the container. The Docker build includes this step.
If you want the dashboard dev server (for UI development or if the static build is not available):
cd apps/dashboard
npm ci
npm run dev
The dashboard dev server typically runs on http://localhost:5173.
Alternative: Bootstrap Script + Manual Server
If you prefer to run the server outside Docker (for faster Rust iteration), use the bootstrap script instead:
Windows (PowerShell):
.\scripts\bootstrap.ps1 -StartInfra
macOS / Linux:
./scripts/bootstrap.sh --start-infra
The bootstrap script will:
- Verify that
git,cargo,node,npm, anddockerare installed - Copy
.env.exampleto.envif it does not exist - Install npm dependencies for the dashboard, SDK, and CLI
- Start infrastructure services (Postgres, Redis, NATS, Azurite, Nango) in detached mode
Then start the server manually with cargo:
cargo run -p atlas-server
The server listens on http://localhost:3000 by default.
Infrastructure Ports Reference
| Service | Port | Protocol | URL |
|---|---|---|---|
| Atlas server | 3000 | HTTP | http://localhost:3000 |
| PostgreSQL | 5433 | TCP | postgres://atlas:atlas_dev@localhost:5433/atlas_control_plane |
| Redis | 6379 | TCP | redis://localhost:6379 |
| NATS client | 4222 | TCP | nats://localhost:4222 |
| NATS monitoring | 8222 | HTTP | http://localhost:8222 |
| Azurite blob | 10000 | HTTP | http://localhost:10000 |
| Nango | 3003 | HTTP | http://localhost:3003 |
Docker Compose Configuration
The Compose file is at docker/docker-compose.yml. Key configuration details:
- PostgreSQL runs with
wal_level=logicalandmax_replication_slots=10to support CDC (Change Data Capture) for realtime subscriptions - Redis runs with
appendonly yesfor data persistence - NATS runs with
--jetstreamfor durable message delivery - Azurite runs the blob service only (
azurite-blob) - All data is persisted in named Docker volumes (
postgres_data,redis_data,azurite_data,search_data)
Troubleshooting
Server fails to start with database connection error:
PostgreSQL takes a few seconds to initialize on first boot. The Docker Compose healthcheck handles this automatically, but if running the server manually, wait until pg_isready succeeds.
Port 5433 already in use:
The Compose file maps Postgres to port 5433 (not the default 5432) to avoid conflicts with a local Postgres installation. If 5433 is also taken, change the port mapping in docker/docker-compose.yml.
Dashboard shows a blank page:
The dashboard is only served statically when apps/dashboard/dist exists. Build it with cd apps/dashboard && npm ci && npm run build, or run the dev server instead.
Next Steps
- Local Development Setup — full contributor workflow with Rust toolchain, linting, and test commands
- Architecture Overview — understand the 23-crate structure, dual-context database, and event-driven architecture
Introduction to AltBase
AltBase is a backend platform built in Rust — REST APIs, auth, storage, realtime, workflows, vector search, GraphQL, and more in a single binary.
Local Development Setup
Full contributor setup for AltBase — Rust toolchain, Node.js, Docker infrastructure, bootstrap scripts, running the server, dashboard, and tests.