atlas-starter-docker

A text-to-SQL data analyst agent powered by Atlas.

This project is configured for PostgreSQL. Ask natural-language questions, and the agent explores a semantic layer, writes validated SQL, and returns interpreted results.

Quick Start

1. Install dependencies:

   bun install

2. Configure environment: Edit .env with your API key and database URL.

3. Generate semantic layer:

   bun run atlas -- init          # From your database
   bun run atlas -- init --demo   # Or load demo data

4. Run locally:

   bun run dev

   API at http://localhost:3000.

Deploy with Docker

1. Build the image (includes nsjail for explore isolation):

   docker build -t atlas-starter-docker .

2. Run:

   docker run -p 3000:3000 \
     -e ATLAS_PROVIDER=anthropic \
     -e ANTHROPIC_API_KEY=sk-ant-... \
     -e ATLAS_DATASOURCE_URL=postgresql://... \
     atlas-starter-docker

3. To build without nsjail (smaller image, dev only):

   docker build --build-arg INSTALL_NSJAIL=false -t atlas-starter-docker .

Project Structure

atlas-starter-docker/
├── src/                # Application source (API + UI)
├── bin/                # CLI tools (atlas init, enrich, eval)
├── data/               # Demo datasets (SQL seed files)
├── semantic/           # Semantic layer (YAML — entities, metrics, glossary)
├── .env                # Environment configuration
└── docs/deploy.md      # Full deployment guide

Commands

Command	Description
bun run dev	Start dev server
bun run build	Production build
bun run start	Start production server
bun run atlas -- init	Generate semantic layer from database
bun run atlas -- init --demo	Load the canonical demo dataset (NovaMart ecommerce, 13 entities)
bun run atlas -- diff	Compare DB schema vs semantic layer
bun run atlas -- query "question"	Headless query (table output)
bun run test	Run tests

Environment Variables

Variable	Required	Description
ATLAS_PROVIDER	Yes	LLM provider (anthropic, openai, bedrock, ollama, openai-compatible, gateway)
Provider API key	Yes	e.g. ANTHROPIC_API_KEY=sk-ant-...
ATLAS_DATASOURCE_URL	Yes	Analytics database connection string
DATABASE_URL	No	Atlas internal Postgres (auth, audit). Auto-set on most platforms
ATLAS_MODEL	No	Override the default LLM model
ATLAS_ROW_LIMIT	No	Max rows per query (default: 1000)

See docs/deploy.md for the full variable reference.

Learn More

• Atlas Documentation
• GitHub