Khoj mit Docker installieren: Selbstgehosteter KI-Assistent für eigene Notizen und Dokumente

Khoj ist ein quelloffener KI-Assistent (AGPL-3.0), der Ihre Dokumente, etwa PDFs, Markdown-, Word-, Notion- oder Org-Mode-Dateien, indiziert und per Chat durchsuchbar macht. Mit Ollama-Modellen läuft er vollständig lokal, ohne externen API-Schlüssel. Diese Anleitung zeigt die Einrichtung per Docker Compose auf einem Linux-Server, einer VM oder einem NAS.

Voraussetzungen

• Docker Engine >= 20.10 und Docker Compose Plugin v2 auf dem Host installiert; sonst hilft die Anleitung Docker und Docker Compose auf Linux installieren.
• Mindestens 8 GB RAM (16 GB empfohlen, wenn lokale LLMs über Ollama laufen sollen).
• Mindestens 10 GB freier Speicher für Images, Modell-Cache und Datenbank; lokale LLMs belegen zusätzlich 4 bis 10 GB je Modell.
• Internetzugang beim ersten Start (Image-Pull und Modell-Download); danach ist Offline-Betrieb mit Ollama möglich.
• Optional: Ollama auf dem Host für lokale Sprachmodelle (ollama.com).
• Optional: Reverse Proxy mit HTTPS für Zugriff von außen, etwa Traefik als Docker-Reverse-Proxy.
• curl für die Prüfschritte.

Eckdaten im Überblick

Schritt 1: Projektordner anlegen

Legen Sie einen eigenen Ordner für den Khoj-Stack an. Er enthält die Konfiguration, die Daten liegen in benannten Volumes.

$ mkdir -p /opt/khoj
$ cd /opt/khoj

Schritt 2: .env-Datei mit sicheren Werten anlegen

Die .env-Datei enthält alle sicherheitskritischen Werte. Die mit :? markierten Variablen sind in der compose.yaml Pflicht; fehlen sie, verweigert Docker den Start. Die Werte secret und password aus der offiziellen Beispieldatei dürfen Sie nicht übernehmen.

Einen Secret-Key erzeugen Sie so:

$ python3 -c "import secrets; print(secrets.token_urlsafe(50))"

# Alternativ:

$ openssl rand -base64 50

Legen Sie die .env-Datei an und passen Sie die Werte an:

# /opt/khoj/.env

# --- Pflichtfelder ---
KHOJ_DJANGO_SECRET_KEY=hier-erzeugten-schluessel-eintragen
KHOJ_ADMIN_EMAIL=admin@example.com
KHOJ_ADMIN_PASSWORD=sicheres-admin-passwort

# --- Datenbank ---
POSTGRES_DB=postgres
POSTGRES_USER=postgres
POSTGRES_PASSWORD=sicheres-db-passwort

# --- Optionale Cloud-APIs (auskommentiert lassen für Offline-Betrieb) ---
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=...
# GEMINI_API_KEY=...

# --- Lokale LLMs via Ollama auf dem Host (auskommentieren zum Aktivieren) ---
# OPENAI_BASE_URL=http://host.docker.internal:11434/v1/

# --- Öffentlicher Zugriff via Reverse Proxy (optional) ---
# KHOJ_DOMAIN=khoj.ihre-domain.de
# KHOJ_NO_HTTPS=True

Schützen Sie die Datei mit chmod 600 /opt/khoj/.env.

Schritt 3: compose.yaml anlegen

Die folgende Datei basiert auf der offiziellen Khoj-Konfiguration, ergänzt um Zugangsdaten aus der .env, feste Versionen und eine Portbindung nur an 127.0.0.1. Den optionalen Dienst computer (Computer-Use per VNC) lässt sie weg. Die Datenbank nutzt das Image pgvector/pgvector, da Standard-PostgreSQL die Erweiterung nicht enthält. extra_hosts macht den Host als host.docker.internal erreichbar, etwa für Ollama. Zu Healthchecks und weiteren Härtungsschritten siehe Docker Compose absichern: Secrets, Healthchecks und Non-Root.

# /opt/khoj/compose.yaml
services:
  database:
    image: pgvector/pgvector:0.8.6-pg15
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-postgres}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set}
      POSTGRES_DB: ${POSTGRES_DB:-postgres}
    volumes:
      - khoj_db:/var/lib/postgresql/data/
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 30s
      timeout: 10s
      retries: 5

  sandbox:
    image: ghcr.io/khoj-ai/terrarium:latest   # Projekt veroeffentlicht nur diesen Tag
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8080/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 2

  search:
    image: searxng/searxng:2026.9.29-4e2c1ea7f
    restart: unless-stopped
    volumes:
      - khoj_search:/etc/searxng
    environment:
      - SEARXNG_BASE_URL=http://localhost:8080/

  server:
    image: ghcr.io/khoj-ai/khoj:2.0.0-beta.28
    restart: unless-stopped
    depends_on:
      database:
        condition: service_healthy
    ports:
      # Anonymmodus ohne Login: nur lokal erreichbar
      - "127.0.0.1:42110:42110"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    working_dir: /app
    volumes:
      - khoj_config:/root/.khoj/
      - khoj_models:/root/.cache/torch/sentence_transformers
      - khoj_models:/root/.cache/huggingface
    environment:
      - POSTGRES_DB=${POSTGRES_DB:-postgres}
      - POSTGRES_USER=${POSTGRES_USER:-postgres}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set}
      - POSTGRES_HOST=database
      - POSTGRES_PORT=5432
      - KHOJ_DJANGO_SECRET_KEY=${KHOJ_DJANGO_SECRET_KEY:?KHOJ_DJANGO_SECRET_KEY must be set}
      - KHOJ_DEBUG=False
      - KHOJ_ADMIN_EMAIL=${KHOJ_ADMIN_EMAIL:?KHOJ_ADMIN_EMAIL must be set}
      - KHOJ_ADMIN_PASSWORD=${KHOJ_ADMIN_PASSWORD:?KHOJ_ADMIN_PASSWORD must be set}
      - KHOJ_TERRARIUM_URL=http://sandbox:8080
      - KHOJ_SEARXNG_URL=http://search:8080
      # Lokale LLMs via Ollama auf dem Host:
      # - OPENAI_BASE_URL=${OPENAI_BASE_URL}
      # Cloud-APIs (optional):
      # - OPENAI_API_KEY=${OPENAI_API_KEY}
      # - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      # - GEMINI_API_KEY=${GEMINI_API_KEY}
      # Öffentlicher Zugriff:
      # - KHOJ_DOMAIN=${KHOJ_DOMAIN}
      # - KHOJ_NO_HTTPS=True
    command: --host="0.0.0.0" --port=42110 -vv --anonymous-mode --non-interactive

volumes:
  khoj_config:
  khoj_db:
  khoj_models:
  khoj_search:

Schritt 4: Stack starten

Starten Sie alle vier Container im Hintergrund. Beim ersten Start lädt Docker die Images, das dauert einige Minuten.

$ cd /opt/khoj
$ docker compose up -d

Khoj lädt beim ersten Start außerdem Embedding-Modelle in das Volume khoj_models. Der Dienst server startet erst, wenn database als healthy gilt.

$ docker compose ps

Erwartete Ausgabe (alle Services running oder Up, database nach einigen Sekunden auch healthy):

NAME              IMAGE                              STATUS
khoj-database-1   pgvector/pgvector:0.8.6-pg15          Up (healthy)
khoj-sandbox-1    ghcr.io/khoj-ai/terrarium:latest      Up (healthy)
khoj-search-1     searxng/searxng:2026.9.29-4e2c1ea7f   Up
khoj-server-1     ghcr.io/khoj-ai/khoj:2.0.0-beta.28    Up

Prüfen Sie die Weboberfläche:

$ curl -I http://localhost:42110

Erwartete Antwort: HTTP/1.1 200 OK oder 302 Found. Startet der Server noch, warten Sie kurz. Logs: docker compose logs -f server.

Schritt 5: Erste Einrichtung im Browser

Öffnen Sie http://localhost:42110 im Browser; läuft Khoj auf einem Server, nutzen Sie einen SSH-Tunnel: ssh -L 42110:localhost:42110 benutzer@server. Im Anonymmodus (--anonymous-mode) erscheint ohne Login direkt der Chat. Für mehrere Benutzer oder Zugriff von außen schalten Sie den Modus ab (siehe Häufige Fragen).

Das Admin-Panel unter http://localhost:42110/server/admin öffnen Sie mit den Zugangsdaten aus der .env. Dort verwalten Sie KI-Modelle, Benutzer und Quellen.

Dokumente laden Sie über „Files“ oder „Sync“ hoch. Unterstützte Formate: PDF, Markdown, Word (.docx), Notion-Seiten (über Plugin), Org-Mode-Dateien. Für Obsidian und Emacs gibt es offizielle Plugins zur Synchronisation.

Schritt 6: Lokale LLMs mit Ollama einrichten (optional)

Für den Betrieb ohne Cloud-Dienst installieren Sie Ollama auf dem Host und binden es an Khoj an. Hintergrund zu Ollama und lokalen LLMs bietet eine eigene Anleitung.

# Ollama installieren (Linux):
curl -fsSL https://ollama.com/install.sh | sh

# Ein Modell herunterladen (Beispiel: Llama 3.1 8B, ~4.7 GB):
ollama pull llama3.1

Ollama lauscht standardmäßig nur auf 127.0.0.1 und ist dann aus dem Container nicht erreichbar. Setzen Sie mit sudo systemctl edit ollama unter [Service] die Zeile Environment="OLLAMA_HOST=0.0.0.0", starten Sie Ollama mit sudo systemctl restart ollama neu und sperren Sie Port 11434 in der Firewall nach außen.

Aktivieren Sie in der .env die Ollama-Zeile:

OPENAI_BASE_URL=http://host.docker.internal:11434/v1/

und in der compose.yaml die Zeile unter environment im Dienst server:

      - OPENAI_BASE_URL=${OPENAI_BASE_URL}

Container neu erstellen:

$ docker compose up -d

Ist OPENAI_BASE_URL schon beim ersten Start gesetzt, übernimmt Khoj die Ollama-Modelle automatisch. Andernfalls legen Sie sie im Admin-Panel an: unter „AI Model API“ einen Eintrag mit Name ollama, API Key beliebiger Text, API Base URL http://host.docker.internal:11434/v1/; danach unter „Chat Models“ ein Modell mit Typ openai, dem exakten Ollama-Modellnamen (etwa llama3.1) und der eben angelegten AI Model API.

Schritt 7: Updates und Backup

Sichern Sie vor jedem Update die Datenbank und lesen Sie die Release Notes; Khoj 2.0 ist noch als Beta gekennzeichnet. Tragen Sie dann den neuen Tag in der compose.yaml ein und führen Sie aus:

$ cd /opt/khoj
$ docker compose pull
$ docker compose up -d

Eine vollständige Backup-Strategie beschreibt die Anleitung 3-2-1-Backup-Strategie umsetzen. Die Datenbank enthält Konten, Einstellungen, Indizes und Embeddings. Sichern Sie sie im laufenden Betrieb per pg_dump:

$ cd /opt/khoj
$ sudo mkdir -p /backup
$ docker compose exec -T database sh -c 'pg_dump -U "$POSTGRES_USER" -Fc "$POSTGRES_DB"' | sudo tee /backup/khoj_db_$(date +%Y%m%d).dump > /dev/null

Ein tar des laufenden Datenbank-Volumes ist nicht konsistent. Beachten Sie außerdem, dass Docker Compose Volume-Namen mit dem Projektnamen versieht (khoj_khoj_db).

Troubleshooting / Typische Fehler

„POSTGRES_PASSWORD must be set“ / Start schlägt fehl

Die :?-Syntax in der compose.yaml erzwingt gesetzte Variablen. Ursache: .env fehlt, liegt im falschen Verzeichnis oder enthält einen Tippfehler. Lösung: in /opt/khoj/ prüfen, ob .env alle Pflichtfelder enthält.

Server startet nicht, obwohl Datenbank läuft

Der server-Service wartet auf den Healthcheck der Datenbank (condition: service_healthy). Auf langsamen Systemen reichen 5 Versuche im Abstand von 30 s nicht. Lösung: In der compose.yaml unter database.healthcheck den Wert retries auf 10 erhöhen und start_period: 60s ergänzen.

Ollama nicht erreichbar (Verbindungsfehler im Log)

Ursache ist meist localhost statt host.docker.internal in OPENAI_BASE_URL oder ein Ollama, das nur auf 127.0.0.1 lauscht. Lösung: http://host.docker.internal:11434/v1/ eintragen und OLLAMA_HOST=0.0.0.0 setzen (Schritt 6).

Port 42110 belegt („bind: address already in use“)

Ein anderer Dienst nutzt den Port. Lösung: den Host-Port ändern, etwa 127.0.0.1:42111:42110, und http://localhost:42111 aufrufen.

„docker pull khoj/khoj“ schlägt fehl

Khoj veröffentlicht nur über die GitHub Container Registry: ghcr.io/khoj-ai/khoj.

„extension vector is not available“

Es läuft das Standard-PostgreSQL-Image. Lösung: Image auf pgvector/pgvector:0.8.6-pg15 ändern (gleiche PostgreSQL-Hauptversion wie bisher) und docker compose up -d ausführen; das Volume bleibt erhalten.

Modelle werden bei jedem Neustart neu heruntergeladen

Das Volume khoj_models wurde versehentlich gelöscht oder nicht korrekt gemountet. Lösung: docker volume ls | grep khoj zeigt alle vier Volumes.

Häufige Fragen

Kann Khoj vollständig offline ohne Cloud-APIs betrieben werden?

Ja, mit Ollama wie in Schritt 6. Nach dem Download von Images und Modellen braucht Khoj für den Chat mit eigenen Dokumenten kein Internet; die Websuche über SearxNG entfällt dann.

Welche Dokumente kann Khoj indizieren?

PDF, Markdown, Word (.docx), Org-Mode, Notion-Seiten und Webseiten. Für Obsidian und Emacs gibt es Plugins, Notion binden Sie über die Integration im Khoj-Web an.

Wie aktiviere ich Multi-User-Betrieb mit Login-Pflicht?

Entfernen Sie --anonymous-mode aus command in der compose.yaml. Die Anmeldung erfolgt dann per Magic Link (Versand über Resend mit RESEND_API_KEY und RESEND_EMAIL, sonst Links manuell weitergeben) oder per Google OAuth, das laut Doku das Image ghcr.io/khoj-ai/khoj-cloud voraussetzt.

Was macht der Terrarium-Service und kann ich ihn weglassen?

Terrarium ist eine isolierte Python-Sandbox, in der Khoj Code für Analysen und Berechnungen ausführt. Ohne den Dienst entfällt die Code-Ausführung, Khoj läuft weiter. Entfernen Sie dann den Dienst und KHOJ_TERRARIUM_URL.

Wie aktualisiere ich Khoj auf die neueste Version?

Wie in Schritt 7: Datenbank mit pg_dump sichern, neuen Tag eintragen, docker compose pull und docker compose up -d. Die Daten in den Volumes bleiben erhalten.

Wie erreiche ich Khoj von außen sicher?

Für den Zugriff aus der Ferne eignet sich Tailscale oder Headscale als selbstgehostetes Mesh-VPN. Für einen öffentlichen Zugang setzen Sie KHOJ_DOMAIN, schalten die Authentifizierung ein und stellen einen Reverse Proxy mit Let's Encrypt davor. Port 42110 darf im Anonymmodus nie aus dem Internet erreichbar sein.

Fazit

Khoj macht eigene Dokumente per Chat durchsuchbar und läuft mit PostgreSQL und pgvector, SearxNG und Terrarium in rund 30 Minuten. Mit Ollama verlassen weder Dokumente noch Anfragen das eigene Netz, was den Datenschutz im Unternehmen vereinfacht.

Wer tiefer in RAG-Systeme einsteigen möchte, findet in der Anleitung Lokales RAG-System mit Qdrant und Embeddings die zugrunde liegenden Konzepte.

Weiterführende Anleitungen und Quellen

1. Ollama und Open WebUI mit Docker: eigenes lokales KI-Sprachmodell ohne Cloud betreiben
2. Lokales RAG-System mit Qdrant und Embeddings selbst bauen
3. AnythingLLM installieren (Docker): Lokale KI-Zentrale mit RAG-Workspaces und Ollama
4. Docker und Docker Compose auf Linux installieren: die Self-Hosting-Grundlage
5. Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten

Offizielle Quellen: Khoj Self-Host Setup Dokumentation | Khoj GitHub Repository | Khoj Ollama-Integration