lordraw/llmwiki repository overview

⁠Wiki-LLM — Docker Guide

This document explains how to build, run, and publish Wiki-LLM as a container. Wiki-LLM is a multi-format knowledge base that exposes a REST API and an MCP server over two transports (stdio and HTTP/SSE) from a single process.

• Source: https://github.com/lordraw77/llmwiki⁠
• Docker Hub image: lordraw/llmwiki

⁠Overview

The image runs python run_http.py by default, serving:

• REST API on http://<host>:8000
• MCP HTTP/SSE at http://<host>:8000/mcp/sse

Persistent vector-store data lives on the /data volume.

⁠Embeddings: image size matters

The default embedding provider in .env.example is local (sentence-transformers), which pulls in torch and produces a multi-GB image. The Docker image therefore omits local embeddings by default and is intended to be used with a remote EMBEDDING_PROVIDER (mistral, openrouter, groq, gemini, cloudflare, cerebras, nvidia, puter, or any openai_compatible endpoint).

Two ways to proceed:

1. Remote embeddings (recommended for containers). In your .env set, e.g.:

   EMBEDDING_PROVIDER=mistral
   EMBEDDING_MODEL=mistral-embed
   EMBEDDING_API_KEY=your-key
   

   Copy
2. Bake in local embeddings. Build with the optional extra:

   docker build --build-arg WITH_LOCAL_EMBEDDINGS=true -t wikillm:local .
   # or: make build WITH_LOCAL_EMBEDDINGS=true
   

   Copy

⁠Quick start

⁠1. Configure

cp .env.example .env
# edit .env — at minimum pick an embedding provider (see above)

⁠2. Run with Docker Compose (easiest)

docker compose up -d --build        # or: make up
docker compose logs -f wikillm      # or: make logs

The server is now on http://localhost:8000⁠ — try http://localhost:8000/health⁠ and the interactive docs at http://localhost:8000/docs⁠.

To include a standalone Qdrant server (then set VECTOR_BACKEND=qdrant and QDRANT_URL=http://qdrant:6333 in .env):

docker compose --profile qdrant up -d --build   # or: make up-qdrant

⁠3. Or run the image directly

make build                                       # builds lordraw/llmwiki:<version> and :latest
docker run --rm -it \
  -p 8000:8000 \
  --env-file .env \
  -v wikillm-data:/data \
  lordraw/llmwiki:latest                          # or: make run

⁠Using the MCP stdio transport from the container

The default command runs the HTTP server. For an MCP stdio client (e.g. Claude Desktop) that launches the server as a subprocess, override the command:

docker run --rm -i \
  --env-file .env \
  -v wikillm-data:/data \
  lordraw/llmwiki:latest python run_stdio.py

Example claude_desktop_config.json entry:

{
  "mcpServers": {
    "wikillm": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/absolute/path/to/.env",
        "-v", "wikillm-data:/data",
        "lordraw/llmwiki:latest",
        "python", "run_stdio.py"
      ]
    }
  }
}

stdout is reserved for JSON-RPC framing (logs go to stderr), so the stdio transport works cleanly through the container.

⁠Verify a running container

With the server up, run the integration test scripts from the host:

python3.12 test_http.py --base-url http://localhost:8000
# add --api-key <key> if API_KEY is set in .env

⁠Publishing to Docker Hub

scripts/publish.sh builds a multi-arch image (linux/amd64,linux/arm64) and pushes it to lordraw/llmwiki, tagging both the version (from the latest git tag, e.g. v0.1.0 → 0.1.0, falling back to pyproject.toml) and latest.

# Interactive login first (or set DOCKERHUB_TOKEN for non-interactive login):
docker login

# Publish to lordraw/llmwiki using the defaults:
make publish
# equivalently:
./scripts/publish.sh

Useful overrides:

Example — single arch, pinned version, no latest:

VERSION=0.1.0 PLATFORMS=linux/amd64 PUSH_LATEST=false \
  ./scripts/publish.sh

⁠Configuration reference

All runtime configuration is via environment variables (see .env.example⁠ for the full list). The image sets container- friendly defaults:

⁠Troubleshooting

• Image is huge / slow to build: you built with WITH_LOCAL_EMBEDDINGS=true. Use a remote embedding provider and rebuild without the flag.
• /health is failing / container unhealthy: check docker compose logs -f wikillm. A misconfigured embedding provider (missing API key) surfaces at startup because the knowledge base is initialised eagerly.
• Switched embedding provider and search misbehaves: changing the provider usually changes the vector dimension, which requires a fresh collection. Remove the volume (docker volume rm wikillm-data) or change COLLECTION_NAME.
• 401 responses: API_KEY is set; send Authorization: Bearer <key> or X-API-Key: <key>.