Skip to content

Quick Start

The whole showcase runs on Atlas (vendored as a Git submodule at infra/) and comes up with one command.

1. Prerequisites

Atlas's requirements apply:

  • Docker + Docker Compose v2, installed and running.
  • The vendored infra/ submodule initialized: 
    git submodule update --init --recursive
  • Host tools uv and python3 (Atlas's bootstrapper and the host-side corpus fetch use them).
  • An Atlas-supported LLM backend. The default local path uses Atlas's Ollama provider; set LLM_PROVIDER_SOURCE=ollama-localhost in infra/.env to use an existing host Ollama instead of the containerized one.
  • Disk / RAM / headroom for the gen-ai-rag stack plus your chosen local models. The default local run activates mistral-small3.2:24b for LightRAG's graph roles — see Hardware Sizing for minimum and recommended profiles.

2. Bring It Up

./scripts/start-all.sh

This single script:

  1. Runs the overlay setup (and brands the vendored Atlas as rag-showcase — rag-showcase-* containers/network and a startup banner).
  2. Starts the Atlas gen-ai-rag stack — LightRAG, TEI reranker, Weaviate, Neo4j, Open WebUI, LiteLLM (Docling is off by default; ingestion falls back to naive text chunking) — plus n8n via an explicit --n8n-source container flag.
  3. Waits for the backend, LightRAG, and Weaviate, then assembles the corpus on the host (corpus/fetch_corpus.py).
  4. Waits for model readiness (embed + chat), ingests the corpus into the backend, and registers the canonical models plus any configured flavor aliases.
  5. Prints the Open WebUI URL.

First run downloads models

With local models, the first run may pull several GB, so it takes a while. start-all.sh gates on model readiness — let it finish.

Then open the printed URL, start a multi-model chat, and select: vanilla-rag, hybrid-rag, contextual-rag, graph-rag, agentic-rag, n8n-adaptive-rag. One prompt fans out to all of them.

Stop everything with:

./scripts/stop-all.sh

3. Corpus Note

For the full corpus (MultiHop-RAG + keyword docs), install the datasets library on the host before running:

python3 -m pip install datasets

Without it, ingestion uses only the bundled keyword docs, so the thematic / multi-hop demo queries have little to work with. See the Corpus Overview.

4. The n8n Workflow

The n8n-adaptive-rag workflow is checked in and imported automatically by start-all.sh, which preserves its active state and restarts n8n so the production webhook is registered. See the n8n Adaptive Workflow page for the workflow shape and tuning knobs.

5. Development and Testing

uv run pytest                 # unit suite (mocked I/O) + integration tests (skip without the stack)
uv run pytest backend_plugins # unit tests only

The unit tests mock all external I/O and run without the stack. The tests/test_demo_matrix.py integration tests exercise the live stack and self-skip when LiteLLM is unreachable. With a started stack they derive the published gateway and master key from infra/.env automatically, so a plain uv run pytest tests works; export LITELLM_BASE_URL / LITELLM_MASTER_KEY only to target a non-default gateway:

LITELLM_BASE_URL="http://other-host:4000" LITELLM_MASTER_KEY="sk-yourkey" \
  uv run pytest tests

Build these docs locally with:

uv run --group docs mkdocs serve

Full environment-variable reference and troubleshooting live in the project README.