Quickstart

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:

1. Verify that git, cargo, node, npm, and docker are installed
2. Copy .env.example to .env if it does not exist
3. Install npm dependencies for the dashboard, SDK, and CLI
4. 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=logical and max_replication_slots=10 to support CDC (Change Data Capture) for realtime subscriptions
• Redis runs with appendonly yes for data persistence
• NATS runs with --jetstream for 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