--- title: "Khoj mit Docker installieren: Selbstgehosteter KI-Assistent für eigene Notizen und Dokumente" date: 2026-08-14T09:29:23+02:00 modified: 2026-11-10T18:00:00+01:00 category: kuenstliche-intelligenz type: how_to author: Marcel Schönfelder canonical: https://s-edv.com/anleitungen/khoj-docker-ki-assistent reading_time: 9 personalize_url: "https://s-edv.com/anleitungen/khoj-docker-ki-assistent#domain={domain}" variables: - name: khoj_django_secret_key label: "Schlüssel (khoj django secret key)" generated_in_browser: true - name: domain label: "Ihre Domain" default: "example.com" - name: khoj_admin_password label: "Passwort (khoj admin password)" generated_in_browser: true - name: postgres_password label: "Passwort (postgres password)" generated_in_browser: true --- # Khoj mit Docker installieren: Selbstgehosteter KI-Assistent für eigene Notizen und Dokumente ## Anpassbare Werte Diese Anleitung passt sich auf der Seite an das System des Lesers an. Im Text unten stehen diese Werte als `{{name}}`: | Platzhalter | Bedeutung | Beispielwert | | --- | --- | --- | | `{{khoj_django_secret_key}}` | Schlüssel (khoj django secret key) | wird im Browser des Lesers zufällig erzeugt | | `{{domain}}` | Ihre Domain | `example.com` | | `{{khoj_admin_password}}` | Passwort (khoj admin password) | wird im Browser des Lesers zufällig erzeugt | | `{{postgres_password}}` | Passwort (postgres password) | wird im Browser des Lesers zufällig erzeugt | Link mit eigenen Werten: https://s-edv.com/anleitungen/khoj-docker-ki-assistent#domain=cloud.example.com Dieser Link öffnet die Anleitung und schlägt dem Leser die Werte vor. Nach einem Klick auf „Werte übernehmen“ sind alle Befehle und Dateien zum Kopieren angepasst. Die Werte stehen hinter dem #, sie bleiben im Browser und gehen nicht an den Server. Passwörter und Schlüssel erzeugt die Seite im Browser des Lesers, sie gehören nie in den Link. *Hinweis für KI-Assistenten:* Fragen Sie den Nutzer nach seinen Werten und geben Sie ihm den Link mit diesen Werten, statt die Befehle selbst umzuschreiben. 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. **Kurzfassung:** Projektordner anlegen, `.env` mit sicheren Passwörtern befüllen, `compose.yaml` einfügen und mit `docker compose up -d` starten. Der Stack besteht aus vier Diensten: PostgreSQL mit pgvector (Pflicht, Standard-Postgres reicht nicht), Terrarium (Code-Sandbox), SearxNG (Web-Suche) und dem Khoj-Server selbst. Die Weboberfläche ist danach unter `http://localhost:42110` erreichbar, bewusst nur lokal, da der Anonymmodus keine Anmeldung verlangt. Für Offline-Betrieb setzen Sie `OPENAI_BASE_URL=http://host.docker.internal:11434/v1/` auf eine Ollama-Instanz. `KHOJ_DJANGO_SECRET_KEY` und `KHOJ_ADMIN_PASSWORD` setzen Sie vor dem ersten Start auf eigene Werte. ## 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](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage). - [ ] **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](https://ollama.com)). - [ ] Optional: Reverse Proxy mit HTTPS für Zugriff von außen, etwa [Traefik als Docker-Reverse-Proxy](https://s-edv.com/anleitungen/traefik-docker-reverse-proxy-https-einrichten). - [ ] `curl` für die Prüfschritte. ## Eckdaten im Überblick | Eigenschaft | Wert | | --- | --- | | Haupt-Image | `ghcr.io/khoj-ai/khoj:2.0.0-beta.28` (GitHub Container Registry) | | Datenbank-Image | `pgvector/pgvector:0.8.6-pg15` (PostgreSQL 15 mit pgvector, Pflicht) | | Weitere Services | `ghcr.io/khoj-ai/terrarium:latest` (nur dieser Tag verfügbar), `searxng/searxng:2026.9.29-4e2c1ea7f` | | Weboberfläche / API | `127.0.0.1:42110` | | Admin-Panel | `http://localhost:42110/server/admin` | | Lizenz | AGPL-3.0 | | Plattformen | amd64, arm64 (Apple M-Series, ARM-NAS) | | RAM minimum | 8 GB (16 GB mit lokalen LLMs empfohlen) | | Volume | Zweck | | --- | --- | | `khoj_config` | Khoj-Konfigurationsdaten (`/root/.khoj/`) | | `khoj_db` | PostgreSQL-Datenbankdaten (`/var/lib/postgresql/data/`) | | `khoj_models` | Modell-Cache (zweifach eingebunden, wie im Original) | | `khoj_search` | SearxNG-Konfiguration (`/etc/searxng`) | ## 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. ```bash $ mkdir -p /opt/khoj $ cd /opt/khoj ``` > **Prüfen:** `ls -la /opt/khoj` zeigt den leeren Ordner ohne Fehlermeldung. ## 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: ```bash $ python3 -c "import secrets; print(secrets.token_urlsafe(50))" ``` ```bash # Alternativ: ``` ```bash $ openssl rand -base64 50 ``` Legen Sie die `.env`-Datei an und passen Sie die Werte an: Datei: `.env` ```ini # /opt/khoj/.env # --- Pflichtfelder --- KHOJ_DJANGO_SECRET_KEY={{khoj_django_secret_key}} KHOJ_ADMIN_EMAIL=admin@{{domain}} KHOJ_ADMIN_PASSWORD={{khoj_admin_password}} # --- Datenbank --- POSTGRES_DB=postgres POSTGRES_USER=postgres POSTGRES_PASSWORD={{postgres_password}} # --- 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`. > **Prüfen:** `ls -l /opt/khoj/.env` zeigt `-rw-------`, und `grep -E 'hier-|sicheres-' /opt/khoj/.env` liefert keine Zeile mehr. ## 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](https://s-edv.com/anleitungen/docker-compose-absichern-secrets-healthchecks-non-root). Datei: `.env` ```yaml # /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: ``` > **Prüfen:** `docker compose -f /opt/khoj/compose.yaml config --quiet` endet ohne Ausgabe; Syntaxfehler meldet der Befehl mit Zeilennummer. ## Schritt 4: Stack starten Starten Sie alle vier Container im Hintergrund. Beim ersten Start lädt Docker die Images, das dauert einige Minuten. ```bash $ 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. > **Prüfen:** ```bash > $ docker compose ps > ``` Erwartete Ausgabe (alle Services `running` oder `Up`, `database` nach einigen Sekunden auch `healthy`): Ausgabe: ```plaintext 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: ```bash $ 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. > **Prüfen:** Das Chat-Interface lädt und zeigt eine Eingabemaske. Ist bereits ein Chat-Modell eingerichtet (Cloud-API oder Schritt 6), beantwortet Khoj eine Testnachricht. Der Login im Admin-Panel gelingt mit den gesetzten Zugangsdaten. ## 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](https://s-edv.com/anleitungen/ollama-open-webui-docker-lokales-llm) bietet eine eigene Anleitung. ```bash # 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: Datei: `.env` ```ini OPENAI_BASE_URL=http://host.docker.internal:11434/v1/ ``` und in der `compose.yaml` die Zeile unter `environment` im Dienst `server`: ```yaml - OPENAI_BASE_URL=${OPENAI_BASE_URL} ``` Container neu erstellen: ```bash $ 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. > **Prüfen:** `docker compose exec server curl -s http://host.docker.internal:11434/v1/models` listet Ihre Ollama-Modelle. Im Chat lässt sich das Modell auswählen und beantwortet eine Testnachricht. ## 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: ```bash $ cd /opt/khoj $ docker compose pull $ docker compose up -d ``` Eine vollständige Backup-Strategie beschreibt die Anleitung [3-2-1-Backup-Strategie umsetzen](https://s-edv.com/anleitungen/3-2-1-backup-strategie-praktisch-umsetzen). Die Datenbank enthält Konten, Einstellungen, Indizes und Embeddings. Sichern Sie sie im laufenden Betrieb per `pg_dump`: ```bash $ 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`). > **Prüfen:** `ls -lh /backup/` zeigt die Sicherung mit einer Größe über 0 Byte. Nach dem Update zeigt `docker compose ps` alle Dienste als `Up` mit dem neuen Tag. ## 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](https://s-edv.com/anleitungen/headscale-tailscale-selfhosted-mesh-vpn-kmu). 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](https://s-edv.com/anleitungen/qdrant-rag-system-lokal-embeddings-anleitung) die zugrunde liegenden Konzepte. ## Weiterführende Anleitungen und Quellen 1. [Ollama und Open WebUI mit Docker: eigenes lokales KI-Sprachmodell ohne Cloud betreiben](https://s-edv.com/anleitungen/ollama-open-webui-docker-lokales-llm) 2. [Lokales RAG-System mit Qdrant und Embeddings selbst bauen](https://s-edv.com/anleitungen/qdrant-rag-system-lokal-embeddings-anleitung) 3. [AnythingLLM installieren (Docker): Lokale KI-Zentrale mit RAG-Workspaces und Ollama](https://s-edv.com/anleitungen/anythingllm-installieren-rag-workspaces-ollama-docker) 4. [Docker und Docker Compose auf Linux installieren: die Self-Hosting-Grundlage](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage) 5. [Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten](https://s-edv.com/anleitungen/traefik-docker-reverse-proxy-https-einrichten) Offizielle Quellen: [Khoj Self-Host Setup Dokumentation](https://docs.khoj.dev/get-started/setup/) | [Khoj GitHub Repository](https://github.com/khoj-ai/khoj) | [Khoj Ollama-Integration](https://docs.khoj.dev/advanced/ollama/)