A self-hosted, source-configurable, multi-disciplinary engineering platform — gen-AI, ML, and data — composable from a single Docker Compose stack.

The Textual TUI wizard mid-launch: ASCII brand banner pinned at the top, stack overview + cloud-API status, filter + log-source chips, and the live docker compose log stream below. Captured during a normal ./start.sh run.

Topologically ordered architecture: external clients enter through Kong, which routes to Apps and Agents; those services call the LLM Core (LiteLLM to Ollama and cloud providers) and the Media and Data tiers. Per-service diagrams under services/<name>/architecture.svg derive their relationships from each manifest's data_flow.calls.

# 1. Clone the repository
git clone https://github.com/thekaveh/atlas && cd atlas

# 2. Start with the interactive setup wizard (no configuration needed)
./start.sh

# 3. Wait ~5 minutes for AI models to download, then access:
# Atlas Dashboard:       http://localhost:63000
# Open WebUI (Chat):     http://localhost:63096
# n8n (Workflows):       http://localhost:63075
# Supabase Studio:       http://localhost:63019
# SearxNG (Search):      http://localhost:63056
# ComfyUI:               http://localhost:63054
# JupyterHub (IDE):      http://localhost:63094
# MinIO Console:         http://localhost:63021
#
# Optional Kong host routes after ./start.sh --setup-hosts:
# Chat:                  http://chat.localhost:63000
# n8n:                   http://n8n.localhost:63000
# Supabase Studio:       http://supabase-studio.localhost:63000
# ComfyUI:               http://comfyui.localhost:63000
# LiteLLM Dashboard:     http://litellm.localhost:63000/ui/
# MinIO Console:         http://minio.localhost:63000

# Default credentials:
# Supabase Studio: kong_admin / DASHBOARD_PASSWORD (auto-generated into .env on first launch)
# n8n:             owner account created in the web UI on first visit

The default configuration runs a CPU starter stack: chat UI, workflow automation, vector database, and privacy search. Additional services such as Ray, Airflow, Spark, Zeppelin, LightRAG, and observability are opt-in through tracks, CLI flags, or the wizard.

# Local AI services (faster, less memory)
./start.sh --llm-provider-source ollama-localhost --comfyui-source localhost

# GPU acceleration
./start.sh --llm-provider-source ollama-container-gpu --comfyui-source container-gpu --stt-provider-source speaches-container-gpu

# Custom project namespace (container family) — isolate from a base Atlas stack,
# e.g. when running Atlas as a submodule. Persists to PROJECT_NAME in .env, so a
# later bare ./stop.sh tears down exactly this stack (start & stop both honor it).
./start.sh --project myproject     # or -p myproject
./stop.sh                          # reads PROJECT_NAME=myproject from .env

# Pick a different STT engine (Speaches is the default)
./start.sh --stt-provider-source parakeet-container-gpu   # SOTA NVIDIA (CC-BY-4.0)
./start.sh --stt-provider-source whisper-cpp-localhost    # Best on macOS — Metal + Core ML
./start.sh --stt-provider-source parakeet-localhost       # Parakeet-MLX (macOS) or native Linux

# Pick a different TTS engine (Speaches is the default)
./start.sh --tts-provider-source chatterbox-container-gpu  # Voice cloning, NVIDIA
./start.sh --tts-provider-source chatterbox-localhost      # Voice cloning, macOS MPS / Linux

# Minimal setup (chat only)
./start.sh --n8n-source disabled --searxng-source disabled --weaviate-source disabled

# Cloud-only LLMs (no local Ollama; LiteLLM gateway routes to cloud providers)
# The bootstrapper auto-disables a cloud provider whose API key is empty,
# so pass --openai-api-key on the command line OR set OPENAI_API_KEY in .env first.
./start.sh --llm-provider-source none --cloud-openai-source enabled --openai-api-key sk-... --comfyui-source disabled

# Observability bundle (Prometheus + Grafana + node-exporter + cAdvisor + per-service exporters)
# Off by default; opt in to scrape Kong, LiteLLM, Weaviate, n8n, MinIO, Backend,
# Postgres, and Redis. 7 starter dashboards in the "Atlas" Grafana folder.
# Grafana admin password is auto-generated on first run (see .env after launch).
./start.sh --prometheus-source container --grafana-source container
./start.sh --prometheus-source container --grafana-source container --prometheus-retention-days 30

• Don't prefix with sudo. The launcher and stopper run as your user; --setup-hosts and --clean-hosts request elevation internally for only the hosts-file mutation. Running the whole script under sudo creates root-owned files that block future non-sudo runs. See docs/TROUBLESHOOTING.md for recovery.
• Port conflicts? → ./start.sh --base-port 64000
• Out of memory? → Increase Docker memory to 10GB+
• *Can't access .localhost? → Run ./start.sh --setup-hosts
• Want fresh start? → ./stop.sh --cold && ./start.sh --cold
• Other startup errors? → See docs/TROUBLESHOOTING.md

Running ./start.sh with no arguments launches an interactive setup wizard that walks through configuring every service step by step:

• Step-by-step service configuration with descriptions and contextual hints (GPU requirements, localhost options, etc.)
• LLM cluster spliced immediately after the LLM Engine step: single unified Ollama models multiselect (source-aware — localhost rows are badged [pulled] / [library]) + a free-text "additional models to pull" step → OpenAI / Anthropic / OpenRouter key + multiselect pairs (live /v1/models fetch), keeping engine + local + cloud adjacent in the wizard flow
• Live ollama.com/library scrape (a few hundred entries; exact count depends on the upstream catalog at fetch time) for both container and host-side Ollama sources
• Real-time command preview showing the equivalent CLI command as you make selections
• Dependency validation that warns if you enable a service without its required dependencies
• Pre-launch summary table with all endpoints and access URLs before starting
• Color-coded streaming logs once the stack launches, with the full session (wizard warnings + launch phase) tee'd to /tmp/atlas-launch-<YYYYMMDDTHHMMSS>.log
• Keyboard shortcuts: Esc returns to the previous step, Space toggles multiselect rows, Ctrl+Q quits

The wizard covers all configurable services, base port selection, cold start option, and hosts file setup. After reviewing the configuration summary, confirm to launch the stack.

For users who prefer CLI flags, all options remain available. See Command Line Interface or the Interactive Setup Wizard Guide.

For RAG-focused work:

./start.sh --track gen-ai-rag

For agentic-app engineering:

./start.sh --track gen-ai-eng

Other tracks: gen-ai-creative, ml-eng, data-eng, trading. Run ./start.sh --list-tracks to see service membership for each.

Omit --track entirely to get the full interactive wizard (with the track picker as step 1). Pass --track all to skip the picker and prompt for every configurable service.

• Quick Start
• Overview
• Getting Started
• Core Services
• Usage Guide
• Advanced Configuration
• Development
• Troubleshooting
• Documentation

Atlas is a self-hosted engineering platform — designed for the breadth of modern generative AI, ML, and data work. It bundles 30+ integrated services (LLM gateway + inference, vector + graph DBs, workflow + DAG automation, distributed compute, object storage, notebooks, observability) wired together via a Kong gateway and an adaptive FastAPI backend. Each service is independently switchable between container, localhost, or disabled (the LLM provider adds a cloud-API path via LiteLLM); the tracks system picks sensible defaults for the work you're doing:

• gen-ai-rag — retrieval-augmented generation (vectors, graph, reranker, doc ingest, web search, workflow automation)
• gen-ai-eng — agentic apps + workflows with voice, vision, and search
• gen-ai-creative — multimodal generation (image, voice, vision, doc)
• ml-eng — distributed training/inference + notebooks + experiment storage
• data-eng — batch + lakehouse + graph + vector with orchestration
• trading — read-only financial research and paper portfolios in notebooks
• all — every configurable service, full wizard, no filtering

Key technical traits:

• Dynamic service configuration: SOURCE-based deployment with CLI overrides
• Kong gateway: auto-generated routes based on active services
• Cross-platform support: runs natively on Linux and macOS (Intel/Apple Silicon); on Windows via WSL2 or Git Bash (start.sh/stop.sh are POSIX shell — there is no native PowerShell/cmd wrapper)
• Flexible deployment: mix containerized and localhost-installed services (with cloud LLM providers wired through LiteLLM)
• GPU support: container variants with NVIDIA GPU access for inference services
• Always-on core: Supabase ecosystem, Redis, LiteLLM gateway (fronts Ollama + cloud LLM providers), FastAPI backend, Kong Gateway
• Opt-in: Ray, OpenClaw, Airflow, Spark, Zeppelin, LightRAG, TEI Reranker, the observability bundle (Prometheus + Grafana), the Cloudflare Tunnel public edge (cloudflared), and the on-demand backup runner (backup) ship disabled; everything is switchable per service via SOURCE flags or the interactive wizard

• API gateway (Kong): centralized API management with dynamic routing
• Real-time data sync: live database notifications via Supabase Realtime
• Flexible service sources: switch between container and localhost variants per service, plus cloud LLM providers via LiteLLM
• Modular architecture: choose service combinations via SOURCE variables
• Environment-based config: configuration through environment variables
• Cross-platform Python core: the bootstrapper is OS-aware; Linux and macOS run natively, Windows runs under WSL2 / Git Bash

The canonical architecture diagram is embedded at the top of this README; its source lives at docs/diagrams/architecture.svg. See docs/diagrams/README.md for update instructions.

The diagram summarizes the full Atlas topology around Kong, Open WebUI, the always-on Backend API, the always-on LiteLLM gateway (fronting Ollama and any enabled cloud LLM providers), Supabase/PostgreSQL, Redis, Neo4j, Weaviate, n8n, ComfyUI, JupyterHub, SearxNG, Ray, and optional Hermes Agent / OpenClaw / STT/TTS/document-processing / LightRAG + TEI Reranker / Airflow + Spark + Zeppelin / Prometheus + Grafana services. Per-service diagrams (auto-regenerated from each manifest's data_flow.calls) live next to each service folder at services/<name>/architecture.{svg,html}.

• New to the stack? → Use containers with ./start.sh for the easiest experience
• Have local Ollama? → Use ./start.sh --llm-provider-source ollama-localhost for better performance (LiteLLM still fronts the upstream)
• Have NVIDIA GPU? → Use ./start.sh --comfyui-source container-gpu for image generation acceleration
• Need cloud APIs? → Use ./start.sh --llm-provider-source none --cloud-openai-source enabled (or the matching --cloud-anthropic-source / --cloud-openrouter-source flag) — LiteLLM routes to whichever providers are enabled
• Limited resources? → Disable services with --n8n-source disabled --searxng-source disabled

The SOURCE-based configuration system controls how each service is deployed.

• Docker & Docker Compose — container orchestration
• Python 3.10+ — for start/stop scripts
• 8GB+ RAM allocated to Docker (12GB recommended)
• 10GB+ disk space for Docker volumes

Install UV (recommended) for Python dependency management:

pip install uv

git clone https://github.com/thekaveh/atlas.git
cd atlas
./start.sh

# Edit configuration before starting
cp .env.example .env
# Edit .env to customize SOURCE variables
./start.sh

The stack uses SOURCE variables to control how services are deployed.

LLM access (always through LiteLLM):

• LiteLLM gateway — always-on; every consumer reads LITELLM_BASE_URL + LITELLM_API_KEY
• Ollama upstream (LLM_PROVIDER_SOURCE=ollama-container-cpu|ollama-container-gpu|ollama-localhost|none) — what LiteLLM forwards to for local inference
• Cloud upstreams (CLOUD_OPENAI_SOURCE, CLOUD_ANTHROPIC_SOURCE, CLOUD_OPENROUTER_SOURCE) — independent enabled/disabled toggles; each requires the matching API key

Other services that support localhost:

• ComfyUI (COMFYUI_SOURCE=localhost) — use local ComfyUI; the bootstrapper resolves host.docker.internal:${COMFYUI_LOCALHOST_PORT} (default 8000; override to 8188 or whatever port your host install uses)
• Weaviate (WEAVIATE_SOURCE=localhost) — use local Weaviate instance
• OpenClaw (OPENCLAW_SOURCE=localhost) — use local OpenClaw installation
• Hermes Agent (HERMES_SOURCE=localhost) — use a host-installed Hermes; the bootstrapper resolves host.docker.internal:${HERMES_LOCALHOST_PORT} (default 8642) for the API and host.docker.internal:${HERMES_LOCALHOST_DASHBOARD_PORT} (default 9119) for the dashboard; useful when Hermes should drive your real shell, browser, or microphone
• LightRAG (LIGHTRAG_SOURCE=localhost) — use a host-installed LightRAG; the bootstrapper resolves host.docker.internal:${LIGHTRAG_LOCALHOST_PORT} (default 63068)
• TEI Reranker (TEI_RERANKER_SOURCE=localhost) — use a host-installed TEI Reranker; the bootstrapper resolves host.docker.internal:${TEI_RERANKER_LOCALHOST_PORT} (default 63049)

Container-only services:

• n8n (N8N_SOURCE=container|disabled) — workflow automation
• SearxNG (SEARXNG_SOURCE=container|disabled) — privacy search
• Open WebUI (OPEN_WEB_UI_SOURCE=container|disabled) — chat interface
• Backend API (BACKEND_SOURCE=container) — always-on adaptive FastAPI backend
• JupyterHub (JUPYTERHUB_SOURCE=container|disabled) — data science IDE

Observability bundle (opt-in, disabled by default):

• Prometheus (PROMETHEUS_SOURCE=container|disabled) — metrics scraper + TSDB bundled with node-exporter and cAdvisor. When enabled, 15 scrape jobs cover Kong, LiteLLM, Weaviate, n8n (web + worker), MinIO, Backend, Asset Worker, Asset Baker, Postgres (via postgres-exporter sidecar in the Supabase family), and Redis (via redis-exporter sidecar in the Redis family), plus four self / infrastructure targets (Prometheus, Grafana, node-exporter, cAdvisor). JupyterHub and Hermes are deferred — see services/prometheus/README.md §4. Retention is user-configurable via --prometheus-retention-days (default 7).
• Grafana (GRAFANA_SOURCE=container|disabled) — dashboards + unified alerting UI on top of Prometheus. Pre-provisions the Prometheus datasource and 7 starter dashboards (stack overview, LiteLLM, Kong, Postgres+Redis, Containers+Host, n8n, app-tier). Admin login is auto-generated on first bootstrap (GRAFANA_ADMIN_USERNAME / GRAFANA_ADMIN_PASSWORD in .env).

Engine-only manifests (speaches, chatterbox) are not listed — they're selected as source variants of their parent (STT Provider / TTS Provider) rather than as standalone services.

• PostgreSQL (Supabase) — primary database with auth, storage, realtime
• Neo4j — graph database for relationships and graph queries
• Weaviate — vector database for embeddings and semantic search
• MinIO — S3-compatible artifact-tier object storage (ComfyUI outputs, Backend blobs, n8n files, JupyterHub datasets, Doc Processor output). Complements Supabase Storage rather than replacing it.
• Redis — cache and message queue

• LiteLLM Gateway — always-on OpenAI-compatible front door for every LLM provider in the stack (one URL, one key)
• Ollama — local LLM inference engine behind LiteLLM (supports CPU/GPU/localhost/none)
• ComfyUI — image generation with workflows
• STT layer — pluggable speech-to-text: Speaches (default, Faster-Whisper inside, CPU-friendly), NVIDIA Parakeet-TDT (SOTA EN/EU), whisper.cpp localhost (best on Apple Silicon)
• TTS layer — pluggable text-to-speech: Speaches (default, Kokoro + Piper voices), Chatterbox (voice cloning, MIT-licensed)
• Docling — document processing with table extraction (IBM Docling, GPU-accelerated)
• OpenClaw — AI agent for messaging platforms (WhatsApp, Telegram, Discord), file management, and task automation
• Hermes Agent — programmable AI agent runtime (Nous Research) with skills, memory, voice, and tool use; routes reasoning through LiteLLM and appears as the hermes-agent model to every consumer
• Deep Researcher — research assistant
• LangMem — persistent conversation memory with automated fact extraction, semantic recall, and consolidation (embedded in Backend)
• Ray — distributed-compute substrate (head + workers) for parallelizing Python workloads (data prep, fine-tuning, batch inference). Disabled by default; enable via --ray-source ray-container-cpu (or ray-container-gpu). Consumed by Backend / JupyterHub via RAY_ADDRESS.
• LightRAG — graph-augmented RAG server. KG + vector + multimodal ingestion. Default disabled.
• TEI Reranker — Cross-encoder reranker (default mixedbread-ai/mxbai-rerank-base-v1) for RAG quality lift. Default disabled.

# Interactive wizard (recommended for first-time setup)
./start.sh                    # Launches step-by-step configuration wizard

# Direct commands (skip wizard)
./start.sh --llm-provider-source ollama-localhost  # Any configuration flag skips the wizard
./start.sh --help            # Show all options
./stop.sh                    # Stop services, keep data
./stop.sh --cold             # Stop this Atlas project and remove its data volumes

# Port and network
./start.sh --base-port 64000  # Custom port range
./start.sh --setup-hosts      # Configure *.localhost domains
./start.sh --skip-hosts       # Skip hosts file checks and setup
./start.sh --no-splash        # Skip the opening splash (also: set ATLAS_NO_SPLASH=1)
                              # Note: Atlas startup artwork is OFF by default; set ATLAS_SPLASH=1 to enable
./start.sh --no-port-migrate  # Skip the chained .env migrations for this run (sentinels not stamped)
./start.sh --profile prod     # Production hardening: localhost-only port binding (HOST_BIND_IP),
                              # json-file log rotation, observability defaulted on, localhost sources
                              # hidden. (Per-service resource limits are always-on .env defaults, not
                              # gated by this flag.) Does not bypass the wizard.

# SOURCE overrides (temporary)
./start.sh --llm-provider-source ollama-localhost
./start.sh --comfyui-source container-gpu
./start.sh --stt-provider-source whisper-cpp-localhost  # Best on Apple Silicon
./start.sh --tts-provider-source chatterbox-localhost   # Voice cloning, native
./start.sh --doc-processor-source docling-container-gpu # Enable document processing
./start.sh --openclaw-source container                 # Enable OpenClaw agent
./start.sh --hermes-source localhost                   # Use a host-installed Hermes
./start.sh --hermes-source disabled                    # Skip Hermes entirely
./start.sh --n8n-source disabled

# Enable LightRAG with default backends (uses Supabase + Neo4j + Redis)
./start.sh --lightrag-source=container --tei-reranker-source=container-cpu

# Combined examples
./start.sh --cold --base-port 55666 --llm-provider-source ollama-localhost

# Cloud provider keys + models (skip the wizard for cloud config)
./start.sh \
  --cloud-openai-source enabled --openai-api-key sk-... \
  --openai-models "gpt-5,gpt-5-mini,text-embedding-3-large"

# Multi-provider cloud setup
./start.sh \
  --cloud-openai-source enabled --openai-api-key sk-... --openai-models gpt-5 \
  --cloud-anthropic-source enabled --anthropic-api-key sk-ant-... --anthropic-models "claude-opus-4-7,claude-sonnet-4-6" \
  --cloud-openrouter-source enabled --openrouter-api-key sk-or-... --openrouter-models openrouter/auto

# Ollama model selection (CLI parity with the wizard's multiselects)
./start.sh \
  --llm-provider-source ollama-container-cpu \
  --ollama-models "qwen3.6:latest,nomic-embed-text" \
  --ollama-custom-models "mistral:7b,phi4:latest"

*_USER_MODELS env vars persist across runs, so you only need to pass the model flags once unless you want to change the active set. Cloud-provider key/source flags also imply --cloud-X-source enabled when paired with --X-api-key.

# Basic stop commands
./stop.sh                    # Stop services, keep data
./stop.sh --cold             # Stop and remove this Atlas project's containers, orphans, and data volumes
./stop.sh --clean-hosts      # Remove *.localhost entries from hosts file
./stop.sh --help             # Show all options

# The --cold option removes this Atlas Compose project's named volumes.
# It does not prune images, networks, containers, or volumes owned by other
# Docker projects. Atlas database and application data is permanently deleted.

Direct access:

• Most services accessible directly via http://localhost:PORT
• Suitable for development and debugging

Kong gateway routing:

• Services with *.localhost URLs route through Kong
• Provides centralized authentication and rate limiting
• Requires hosts file setup: ./start.sh --setup-hosts

See docs/deployment/source-configuration.md for detailed SOURCE configuration guides.

For NVIDIA GPU acceleration, set the relevant SOURCE variables to a *-container-gpu variant (e.g., LLM_PROVIDER_SOURCE=ollama-container-gpu, COMFYUI_SOURCE=container-gpu, STT_PROVIDER_SOURCE=speaches-container-gpu or parakeet-container-gpu, TTS_PROVIDER_SOURCE=speaches-container-gpu or chatterbox-container-gpu). See docs/deployment/source-configuration.md for the full list of GPU variants per service.

Atlas is designed to back other projects (e.g. a RAG-showcase app) as shared infrastructure. The two ready-today paths are standalone + shared network (your project is a separate repo that joins ${PROJECT_NAME}-network) and Git submodule (vendor Atlas into your repo). For the full decision guide — which method, what's ready, how to wire and customize it — see Reusing Atlas as Infrastructure. New submodule consumers can follow its ordered, example-rich from-scratch walkthrough (§4.1) end to end.

The submodule path in brief:

# Add as submodule in your project (swap in your fork URL if you vendored one)
git submodule add https://github.com/thekaveh/atlas.git infra

# Configure and start
cd infra
cp .env.example .env
# Edit .env: Set PROJECT_NAME=myproject
./start.sh

# Access from your application
# - Docker network: myproject-network
# - Kong gateway: http://localhost:63000
# - Direct ports: derived from BASE_PORT, default http://localhost:63000+

Capabilities:

• Infrastructure code separated from application code
• Upstream updates can be pulled while maintaining local settings
• Project-specific environment configurations
• Standard git workflow for contributing changes upstream
• Multiple isolated instances with separate Docker resources

Integration patterns:

1. Docker network — connect your services to ${PROJECT_NAME}-network
2. Kong gateway — use Kong as single entry point (port 63000)
3. Direct access — access services via exposed ports

See docs/deployment/submodule-usage.md for the complete guide including:

• Detailed setup instructions
• Integration patterns with code examples
• Contributing back to atlas
• Troubleshooting submodule issues

atlas/
├── bootstrapper/              # Python startup, SOURCE parsing, port/Kong generation, wizard
│   ├── services/              # Manifest loader, validator, env_assembler, hooks, sc_synthesizer
│   ├── schemas/               # JSON Schemas for service.yml manifests
│   ├── tests/                 # 2,800+ tests (loader, validator, byte-equiv, source-permutation, hooks)
│   ├── tools/                 # validate_fragments CLI lint
│   └── start.py / stop.py     # Entry points
├── services/                  # 56 service.yml manifests + 3 doc-only folders (representative subset shown below; see services/ for the full list)
│   ├── globals/               # Project-wide vars (PROJECT_NAME, BASE_PORT, BRAND_*, tier ordering)
│   ├── supabase/              # supabase-db, db-init, meta, storage, auth, api, realtime, studio
│   │   ├── service.yml        # Manifest: env vars, source variants, deps, runtime_sc slice
│   │   ├── compose.yml        # Compose fragment for the family
│   │   └── db/                # SQL init scripts + snapshots (bind-mounted into supabase-db-init)
│   ├── litellm/               # LiteLLM gateway + init
│   │   ├── service.yml
│   │   ├── compose.yml
│   │   ├── init/              # litellm-init Dockerfile + scripts (config.yaml renderer)
│   │   └── models.yaml        # Curated cloud-provider model catalog (per-service SoT)
│   ├── ollama/                # ollama + ollama-pull (pull/ scripts); models.yaml = Ollama catalog SoT
│   ├── redis/                 # Redis cache/queue substrate (AOF persistence, shared by n8n/Kong/LiteLLM/owui/LightRAG)
│   ├── weaviate/              # weaviate + multi2vec-clip + weaviate-init
│   ├── comfyui/               # comfyui + comfyui-init (init/ scripts); models.yaml + custom-models.yaml = ComfyUI catalog SoT
│   ├── n8n/                   # n8n + n8n-worker + n8n-init (with init/ assets, workflows-stage/)
│   ├── open-webui/            # open-web-ui + open-webui-init (with extras/ tools+functions)
│   ├── hermes/                # hermes + hermes-init (with init/ scripts & templates)
│   ├── minio/                 # minio + minio-init (with init/ bucket provisioning scripts)
│   ├── backend/               # FastAPI backend (with app/ source code)
│   ├── jupyterhub/            # JupyterHub (with build/ Dockerfile + notebooks)
│   ├── neo4j/                 # Neo4j (with build/ Dockerfile + scripts)
│   ├── parakeet/              # STT engine (parakeet-gpu, with provider/ source code)
│   ├── speaches/              # Unified TTS+STT engine (CPU/GPU)
│   ├── chatterbox/            # TTS engine (GPU, voice cloning)
│   ├── tts-provider/          # Virtual manifest — TTS source selector (with provider/ host notes)
│   ├── docling/               # Document processor (with provider/ source code)
│   ├── searxng/               # SearXNG (with config/ settings.yml)
│   ├── local-deep-researcher/ # Research agent (with build/ Dockerfile)
│   ├── lightrag/              # LightRAG graph-RAG server + init (opt-in via LIGHTRAG_SOURCE)
│   ├── tei-reranker/          # TEI reranker (opt-in via TEI_RERANKER_SOURCE)
│   ├── openclaw/              # OpenClaw agent gateway + init
│   ├── kong/                  # Kong API gateway
│   ├── ray/                   # Ray distributed-compute substrate (head + workers)
│   ├── prometheus/            # Metrics scraper + TSDB (with config/ scrape jobs, opt-in via PROMETHEUS_SOURCE)
│   ├── grafana/               # Observability dashboards + unified alerting (with config/ provisioning, opt-in via GRAFANA_SOURCE)
│   ├── spark/                 # Apache Spark standalone cluster — master + worker + history + init (opt-in via SPARK_SOURCE)
│   ├── zeppelin/              # Apache Zeppelin Spark-first notebook UI (opt-in via ZEPPELIN_SOURCE; gated on Spark)
│   ├── airflow/               # Apache Airflow 3.x DAG orchestrator (with build/ Dockerfile + dags/, opt-in via AIRFLOW_SOURCE)
│   ├── cloud-providers/       # Virtual manifest — OpenAI/Anthropic/OpenRouter toggles
│   ├── stt-provider/          # Doc-only — aggregate STT provider documentation
│   ├── doc-processor/         # Doc-only — aggregate doc-processor documentation
│   ├── multi2vec-clip/        # Doc-only — aggregate multi2vec-clip documentation (container ships inside weaviate/)
│   └── _user/                 # (Gitignored) downstream submodule consumers' overlay slot
├── docs/                      # User, service, deployment, diagram, and planning docs
│   ├── CONTRIBUTING-services.md  # How to add a new service to the modular layout
│   └── …
├── scripts/                   # Top-level utility scripts (e.g. migration helpers)
├── docker-compose.yml         # ~90-line thin shell — include: list pulling each fragment
├── .env.example               # Configuration template (auto-generated from manifests via env_assembler; byte-equivalence enforced by tests)
├── start.sh / stop.sh         # Entry points
└── .github/workflows/         # CI: services-lint (manifest lint+tests, compose byte-equiv+source-permutation, docs-drift+audits, build-validation)

Top-level is intentionally minimal: bootstrapper/, docs/, scripts/, services/. Every service lives entirely under its services/<name>/ folder — init scripts, source code, build context, config files — so opening a service folder shows everything that defines it.

New services are declared by creating services/<name>/{service.yml, compose.yml} and adding the fragment to the include: list in docker-compose.yml. The manifest's runtime_sc: block declares per-source scale/environment/deploy/extra_hosts; bootstrapper/services/sc_synthesizer.py concatenates these slices into the dict that the bootstrapper consumes at startup. See docs/CONTRIBUTING-services.md for the full walkthrough.

Port conflicts:

./start.sh --base-port 64000  # Use different port range
lsof -i :63000               # Check what's using port

Memory issues:

# Increase Docker memory in Docker Desktop
# Settings → Resources → Memory (set to 10-12GB)

Service health:

docker compose ps              # Check service status
docker logs ${PROJECT_NAME}-litellm -f   # Check LLM gateway logs
docker logs ${PROJECT_NAME}-ollama -f    # Check Ollama upstream logs (if enabled)

For longer-form troubleshooting guides, see docs/quick-start/troubleshooting.md.

The documentation index is the top-level navigation hub. Key entry points by audience:

• Interactive setup wizard — step-by-step guided configuration on first ./start.sh
• Quick Start guides — installation and first-run
• Troubleshooting — common issues and known-benign warnings
• Expected startup warnings — log lines that look scary but aren't

• SOURCE configuration — every service's container / localhost / disabled modes (and GPU variants for the LLM/embedding engines)
• Ports and routes — canonical port offsets, direct URLs, and Kong routes
• Reusing Atlas as infrastructure — overview + decision guide for backing another project with Atlas
• Using as a submodule — deep-dive for the Git-submodule reuse method
• Service documentation — per-service READMEs (each owns its manifest, compose fragment, and architecture diagram)

• CONTRIBUTING-services.md — adding a new service to the stack (manifest schema, compose fragment, docs regen)
• SECURITY.md — threat model, supported versions, responsible-disclosure address
• Cross-service integration matrix — Phase B research index linking every service to its candidate integrations
• Research rows and candidates — per-service / per-candidate integration design notes

• ROADMAP.md — future development plans and tier-status of every service
• CHANGELOG.md — release history and the [Unreleased] known-follow-ups block
• Releasing & version tags — semver tag convention for pinning a vendored Atlas

Contributions welcome. Open a PR or an issue to propose changes.

Apache License 2.0

• Check the documentation
• Report issues on GitHub Issues
• Ask questions in GitHub Discussions