Install the local lab

Outcome: run the backend in a terminal on localhost. This is a manual lab procedure, not a production deployment. The commands have been checked against source; a fresh-host installation has not been exercised as part of this documentation update.

Prerequisites: complete environment checks. Run the following commands in WSL Ubuntu. Do not use this procedure to overwrite an existing deployment.

1. Get the source

mkdir -p ~/projects
cd ~/projects
git clone git@gitlab.com:debiansurferboy-group/training/ai_training_model.git
cd ai_training_model

Your WSL Git environment needs its own working authentication. Successful SSH from Windows does not prove WSL has the same key. HTTPS cloning is an alternative if configured through your Git client.

2. Create the Python environment

python3.11 -m venv .venv
.venv/bin/python -m pip install -r backend/requirements.txt
mkdir -p logs data vector-store

The log directory must exist before the application imports. Keep the pinned ChromaDB version with this store; mixing system Python and the project environment can change its schema.

3. Configure the API

cp .env.example .env
chmod 600 .env
nano .env

Set API_KEY to a long, unique secret you generated locally. Do not use the template value. For the first lab, set ENABLE_CONVERSATION_MEMORY=false to avoid the current credential-as-user-ID and shared-memory behavior. Set OLLAMA_HOST=http://localhost:11434 if Ollama runs here.

Generate a key with .venv/bin/python -c 'import secrets; print(secrets.token_urlsafe(32))', then paste it into the API_KEY setting in .env. The command displays the key in your terminal; do not include it in screenshots, logs shared with others, or Git commits.

Do not use scripts/create-env.sh as a random-key generator: the current script writes a placeholder and can print the configured key. See configuration for settings actually consumed by the backend.

4. Prepare Ollama

Check whether Ollama is already running:

curl --fail-with-body http://localhost:11434/api/tags

If Ollama is installed but no server is listening, run ollama serve in a separate WSL terminal and leave it open. Do not start a second server if an existing Ollama service already owns that port. Then download both configured routing models:

ollama pull qwen3.5:2b
ollama pull qwen2.5-coder:3b
ollama list

Both names should appear. Downloading does not mean both models remain resident in GPU memory.

5. Start the API

From the repository root:

PYTHONPATH="$PWD/backend" .venv/bin/uvicorn app:app --app-dir backend --host 127.0.0.1 --port 8000

This explicitly supplies the backend import directory while keeping logs and the vector store relative to the project root. Leave the terminal open. Stop the process with Ctrl+C when finished.

Existing deployment scripts

The automated WSL installer changes packages, services, and firewall rules. Its service import configuration needs verification. Compose has a build-context/requirements mismatch and a mount/import mismatch. Do not run these as interchangeable shortcuts to the manual walkthrough. Track those issues in project status.

Next: Verify the installation, then send your first query.