Run It Locally

The docs site — and the Oracle that lives in the corner — is just an Astro app. You can run it three ways depending on what you have at hand.

Option A — Astro dev server, Ollama backend (fastest)

The Oracle calls your shared Ollama at https://your-ollama-host.example. No local GPU needed, no API keys to manage.

cd /home/stephan/PhpstormProjects/Nibiru/docs

# .env (copy from .env.example, defaults already point at your Ollama instance)
cp .env.example .env

npm install      # one-time
npm run dev      # http://localhost:4321

Open http://localhost:4321/. Click the amber Oracle launcher in the bottom-right and ask anything.

Pull the embedding model once on your Ollama host (build-time + runtime):

curl https://your-ollama-host.example/api/pull -d '{"name":"nomic-embed-text"}'

Without it, the Oracle still works — it just runs in chat-only (no-RAG) mode and answers from the model’s parametric knowledge. With it, answers are grounded in this documentation.

Build the embedding index

npm run build:oracle    # writes public/oracle-index.json

The dev server will pick it up on the next request. Or skip this step entirely — the runtime endpoint handles a missing/empty index gracefully.

Inspect the runtime config

The Oracle’s /api/oracle endpoint also responds to GET with its current config (no secrets):

curl http://localhost:4321/api/oracle
# {"status":"ok","llm":{"provider":"ollama","ollamaUrl":"https://your-ollama-host.example",
#  "model":"qwen2.5-coder:14b"},"embed":{...},"index":{...}}

Option B — Docker compose, locally

Closer to production. Builds the same image you’d ship.

cd /home/stephan/PhpstormProjects/Nibiru/docs
cp .env.example .env

docker compose -f docker-compose.yml -f docker-compose.local.yml up --build

The docker-compose.local.yml override:

• Publishes 4321:4321 so the app is reachable at http://localhost:4321/.
• Drops the VIRTUAL_HOST / LETSENCRYPT_HOST env vars.
• Doesn’t need an nginx-proxy network on your dev box.

The first build takes 1-2 minutes. Subsequent rebuilds are fast (Docker caches the dep layer).

Option C — Fully offline, local Ollama

For airgapped dev, demos on a plane, or burning your own GPU.

# 1) Run Ollama on your laptop
ollama serve &

# 2) Pull a chat model (any of these works)
ollama pull qwen2.5-coder:14b      # 8 GB, recommended
# ollama pull qwen2.5-coder:1.5b   # 1 GB, faster but less accurate
# ollama pull llama3.2:3b          # 2 GB, alternative

# 3) Pull an embedding model
ollama pull nomic-embed-text

# 4) Point the docs at it
cd /home/stephan/PhpstormProjects/Nibiru/docs
cat > .env <<EOF
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_CHAT_MODEL=qwen2.5-coder:14b
OLLAMA_EMBED_MODEL=nomic-embed-text
EOF

npm run build:oracle
npm run dev

Now http://localhost:4321/api/oracle calls your laptop’s Ollama. No internet required.

Switching to Anthropic / OpenAI (if you want to)

The Oracle supports paid APIs as a fallback. In .env:

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

EMBED_PROVIDER=openai
OPENAI_API_KEY=sk-...

Useful if your Ollama is down, or for comparing answer quality across providers.

Smoke-test cheat sheet

curl http://localhost:4321/                                    # 301 → /en/
curl -I http://localhost:4321/en/                              # 200
curl http://localhost:4321/api/oracle                          # GET = config
curl -X POST -H 'Content-Type: application/json' \
     -d '{"messages":[{"role":"user","content":"How do I create a module?"}]}' \
     http://localhost:4321/api/oracle | jq .answer

If the last call returns a real answer that mentions ./nibiru -m, your stack is wired up correctly.

Troubleshooting

Oracle returns “the Oracle could not answer”. The Ollama server is unreachable or the chat model isn’t pulled. Verify:

curl https://your-ollama-host.example/api/tags | jq '.models[].name'

Oracle answers without citations. The embedding index is empty. Re-run npm run build:oracle after pulling nomic-embed-text.

Ollama returns 404 model-not-found. Pull the model, e.g.:

curl https://your-ollama-host.example/api/pull -d '{"name":"qwen2.5-coder:14b"}'

ECONNREFUSED 127.0.0.1:11434 in option C. Local Ollama isn’t running. Start it with ollama serve & (or via your system service).