Running Alan — Docker

Docker Compose is the recommended way to run Alan. It starts TuringDB, the FastAPI server, Streamlit, Ollama, and Valkey in one command, with networking and volume mounts handled automatically.

Prerequisites: Docker with the Compose plugin, and at least 4 GB of RAM (sentence-transformers loads a model into memory).

Step 1 — Clone and configure

git clone https://github.com/turing-db/askalan.git
cd askalan
cp .env.example .env

The defaults in .env.example work out of the box for local use. Edit .env only if you want to change ports, switch to Mistral, or point at a different TuringDB graph.

Step 2 — Provide the knowledge graph

TuringDB needs the graph files on disk before it can start. Create the turing-dir directory at the project root — Docker mounts it into the TuringDB container:

mkdir -p turing-dir

Then import a graph into it. To use the default Reactome graph, follow the import instructions in turing-bench. For a custom graph, import it into TuringDB and save it under turing-dir/.

The data/ and vector/ subdirectories are created automatically by the app — you do not need to create them.

Step 3 — Start all services

docker compose up --build

This starts five services:

The first build takes several minutes because it installs Python dependencies including sentence-transformers (which pulls PyTorch). Subsequent builds are fast thanks to Docker layer caching.

Step 4 — Pull an Ollama model

Once ollama is running, pull a model for chat generation. In a separate terminal:

docker compose exec ollama ollama pull llama3.2

The default models in .env.example are qwen2.5:3b (router) and qwen2.5:7b (agent). Pull whichever models match your configuration.

The embedding model (minishlab/potion-base-32M) is a sentence-transformers model that downloads automatically from Hugging Face the first time you build the vector index — no manual pull needed.

Step 5 — Build the vector index (first time only)

curl -X POST http://localhost:8000/dev/build_vector_index \
  -H "Content-Type: application/json" \
  -d '{"graph_name": "reactome", "model": "minishlab/potion-base-32M"}'

This embeds all graph nodes that have a text property and loads the vectors into TuringDB. The process is idempotent — already-computed batches are skipped on re-runs. The index persists in the turingdb-data Docker volume; you do not need to rebuild it on subsequent runs.

See Server → Endpoints for the full response schema.

Step 6 — Open the chat UI

Navigate to http://localhost:8501.

If Docker is running on a remote server, your browser cannot reach its ports directly. Forward both ports over SSH from your laptop:

ssh -NL 8501:localhost:8501 -L 8000:localhost:8000 <user@server-address>

Then open http://localhost:8501 in your browser as normal. The -N flag keeps the tunnel open without opening a shell — run it in a dedicated terminal tab for as long as you need the UI.

Stopping

docker compose down          # stop containers, keep volumes
docker compose down -v       # stop containers and delete all data volumes

GPU support (optional)

To run Ollama with an NVIDIA GPU, install the NVIDIA Container Toolkit, then uncomment the deploy block in the ollama service in docker-compose.yml.

Useful commands

# Follow logs for a specific service
docker compose logs -f server

# Check service health
curl http://localhost:8000/health

# Rebuild after code changes (only affected services)
docker compose up --build server streamlit

Configuration

Several variables have different values depending on whether the stack runs inside Docker (services reach each other by service name) or locally (everything is on localhost). The table below covers only the variables that differ between the two contexts — all others in .env.example are the same in both.

PUBLIC_SERVER_URL and TURINGDB_STREAMLIT_URL are browser-facing and always use localhost unless Alan is hosted on a remote server, in which case replace localhost with the server's address.