DeepTutor 1.7.0 selbst hosten: Docker Compose mit lokalem Ollama-Modell

DeepTutor vom Data Intelligence Lab der Universität Hongkong (HKUDS) ist ein KI-Lernassistent mit Chat, Wissensbasen, Lernnotizbuch und Übungsfragen. Das Projekt hat auf GitHub inzwischen über 50.000 Sterne gesammelt und steht in den GitHub-Trends. Am 28.10.2026 erschien Version 1.7.0 mit modularer Installation, überarbeitetem Lern-Workspace, Notizbuch mit Blöcken und Videolektionen. Diese Anleitung zeigt, wie Sie DeepTutor 1.7.0 mit Docker Compose betreiben und dabei kein Cloud-Modell brauchen: Ein Ollama-Container im selben Stack liefert Sprachmodell und Embeddings. Alle Schritte stammen aus einem Praxistest auf einem Linux-Testserver, inklusive Wissensbasis, Backup mit echter Wiederherstellung, Update von 1.6.15 auf 1.7.0 und provozierten Fehlern.

Voraussetzungen

• Linux-Server oder VM mit x86_64-Prozessor, mindestens 4 CPU-Kernen und 8 GB RAM. Im Test belegte DeepTutor rund 190 MB RAM, Ollama mit geladenem Modell rund 1,4 GB. Größere Modelle brauchen entsprechend mehr.
• Etwa 15 GB freier Speicher: Das DeepTutor-Image ist 3,5 GB groß, das Ollama-Image 8,5 GB, die beiden Modelle zusammen rund 1,3 GB.
• Docker Engine mit Docker Compose Plugin (docker compose version muss funktionieren). Fehlt Docker noch, zeigt unsere Docker- und Compose-Grundlage die Installation auf Debian und Ubuntu.
• Optional eine GPU mit mindestens 8 GB VRAM, wenn Sie größere Modelle flüssig nutzen wollen. Für den Einstieg reicht die CPU.
• Für den Zugriff aus dem Netz ein Reverse Proxy mit HTTPS, da DeepTutor selbst kein TLS mitbringt.

Schritt 1: Projektordner und Compose-Datei anlegen

Das Repository liefert mit docker-compose.ghcr.yml eine Vorlage für das fertige Image ghcr.io/hkuds/deeptutor plus Redis. Die folgende Datei baut darauf auf, ändert aber vier Dinge: Die Versionen sind über die .env fest eingetragen statt :latest, es gibt keine festen container_name, die Ports hören nur auf 127.0.0.1, und ein Ollama-Dienst kommt hinzu. Den Wrapper scripts/docker_compose.py aus dem Repository brauchen Sie damit nicht, weil die Ports direkt in der Compose-Datei stehen.

mkdir -p ~/deeptutor/data/user/workspace/outputs ~/deeptutor/ollama
cd ~/deeptutor

Legen Sie compose.yaml an:

services:
  redis:
    image: redis:7.4-alpine
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes", "--appendfsync", "everysec"]
    volumes:
      - ./data/redis:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 10

  ollama:
    image: ollama/ollama:${OLLAMA_TAG}
    restart: unless-stopped
    volumes:
      - ./ollama:/root/.ollama

  deeptutor:
    image: ghcr.io/hkuds/deeptutor:${DEEPTUTOR_TAG}
    restart: unless-stopped
    ports:
      - "127.0.0.1:3782:3782"
      - "127.0.0.1:8001:8001"
    volumes:
      - ./data:/app/data
      - ./data/user/workspace:/workspace
    environment:
      - TZ=${TZ}
      - DEEPTUTOR_WORKSPACE_ROOT=/workspace
      - DEEPTUTOR_WORKSPACE_ALLOWED_ROOTS=/workspace
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8001/health/ready"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
    depends_on:
      redis:
        condition: service_healthy
      ollama:
        condition: service_started

Dazu die .env im selben Ordner:

DEEPTUTOR_TAG=1.7.0
OLLAMA_TAG=0.40.13
TZ=Europe/Berlin

Port 3782 ist die Weboberfläche. Laut Projektdoku leitet deren Next.js-Server alle Aufrufe von /api und /ws intern an das Backend weiter, Port 8001 brauchen Sie also nur für curl, Skripte und den Healthcheck von außen. Mehr zu Healthchecks und weiteren Härtungsoptionen finden Sie in der Anleitung Docker Compose absichern.

Eckdaten	Wert
Image	ghcr.io/hkuds/deeptutor:1.7.0 (identischer Digest wie latest am 30.10.2026)
Weitere Dienste	redis:7.4-alpine, ollama/ollama:0.40.13
Ports	3782 Oberfläche, 8001 API (beide nur auf 127.0.0.1)
Volumes	./data nach /app/data (alle App-Daten), ./data/user/workspace nach /workspace, ./ollama für Modelle
Env	TZ, DEEPTUTOR_WORKSPACE_ROOT, DEEPTUTOR_WORKSPACE_ALLOWED_ROOTS; Ports, Anmeldung und Modelle stehen in JSON-Dateien unter data/user/settings
Lizenz	Apache-2.0

Verifizieren: docker compose config --images listet ghcr.io/hkuds/deeptutor:1.7.0, redis:7.4-alpine und ollama/ollama:0.40.13.

Schritt 2: Stack starten und Version prüfen

docker compose up -d --pull always
docker compose ps
curl -s http://127.0.0.1:8001/health/ready
docker inspect $(docker compose ps -q deeptutor) \
  --format '{{index .Config.Labels "org.opencontainers.image.version"}}'

Beim ersten Start legt der Container die Einstellungsdateien unter data/user/settings an. Das Backend war im Test nach etwa zehn Sekunden bereit. Im Log steht zunächst eine Warnung, die Sie ignorieren können, bis Schritt 3 erledigt ist:

WARNING deeptutor.api.main - Failed to initialize LLM client at startup: No active LLM model is configured. Please set it in Settings > Catalog.

Ein Befehl deeptutor existiert im Image nicht im Suchpfad (exec: "deeptutor": executable file not found in $PATH). Die Kommandozeile erreichen Sie stattdessen über python -m deeptutor_cli, am besten als Benutzer deeptutor, damit neue Dateien die richtigen Rechte bekommen.

Verifizieren: docker compose ps zeigt deeptutor und redis als healthy, /health/ready liefert {"status":"ready"} und das Label meldet 1.7.0.

Schritt 3: Lokale Modelle laden und eintragen

Laden Sie ein kleines Chat-Modell und ein Embedding-Modell in den Ollama-Container. qwen2.5:1.5b (986 MB) läuft auch ohne GPU brauchbar, nomic-embed-text (274 MB) erzeugt die Vektoren für die Wissensbasis.

docker compose exec ollama ollama pull qwen2.5:1.5b
docker compose exec ollama ollama pull nomic-embed-text

Die Modelle tragen Sie mit einer JSON-Datei ein, die DeepTutors Befehl config apply versteht. Entscheidend ist der Hostname ollama: Im Container zeigt localhost auf DeepTutor selbst.

{
  "llm": {
    "provider": "ollama",
    "model": "qwen2.5:1.5b",
    "base_url": "http://ollama:11434/v1"
  },
  "embedding": {
    "provider": "ollama",
    "model": "nomic-embed-text",
    "base_url": "http://ollama:11434/api/embed",
    "dimension": 768
  }
}

docker compose cp setup.json deeptutor:/tmp/setup.json
docker compose exec -u deeptutor deeptutor python -m deeptutor_cli config apply /tmp/setup.json --check
docker compose exec -u deeptutor deeptutor python -m deeptutor_cli config apply /tmp/setup.json
docker compose exec -u deeptutor deeptutor python -m deeptutor_cli doctor --online --format json

Der Lauf mit --check prüft nur und schreibt nichts, der zweite legt ein Profil namens „Agent Setup“ an. doctor --online schickt eine echte Anfrage an das Modell. Alternativ richten Sie die Modelle in der Oberfläche unter Einstellungen bei den Sprach- und Embedding-Modellen ein; dort lässt sich unter Allgemein auch Deutsch als Oberflächensprache wählen.

Verifizieren: config apply meldet "status": "applied", doctor zeigt bei Provider response den Status pass mit „The model returned a response.“ und insgesamt "ok": true.

Schritt 4: Wissensbasis anlegen und Fragen stellen

Die Kernfunktion für Unternehmen ist die Wissensbasis: DeepTutor indiziert eigene Dokumente und beantwortet Fragen daraus. Im Test diente ein kurzes Betriebshandbuch als Markdown-Datei.

docker compose cp handbuch.md deeptutor:/tmp/handbuch.md
docker compose exec -u deeptutor deeptutor python -m deeptutor_cli kb create musterfirma --doc /tmp/handbuch.md
docker compose exec -u deeptutor deeptutor python -m deeptutor_cli kb list
docker compose exec -u deeptutor deeptutor python -m deeptutor_cli run chat \
  "Wann läuft laut Handbuch die Datensicherung? Antworte in einem Satz auf Deutsch." --kb musterfirma

Das Anlegen dauerte rund zehn Sekunden, die Wissensbasis nutzt LlamaIndex mit 768 Dimensionen. Die Antwort kam nach etwa 25 Sekunden auf der CPU und stimmte mit dem Dokument überein:

Die Datensicherung der Musterfirma läuft jede Nacht um 01:30 Uhr auf das NAS im Keller.

Mit --format json liefert run chat einen maschinenlesbaren Ereignisstrom inklusive Tokenzahlen, praktisch für Skripte. Dieselben Gespräche erscheinen in der Weboberfläche unter http://127.0.0.1:3782.

Verifizieren: kb list zeigt musterfirma mit Status ready und einem Dokument, die Chat-Antwort gibt den Inhalt des Handbuchs wieder.

Schritt 5: Anmeldung einschalten

Ab Werk läuft DeepTutor im Einzelbenutzermodus ohne Anmeldung. Im Test lieferte /api/knowledge-bases sowohl direkt als auch über den Frontend-Port HTTP 200 ohne jede Anmeldung. Wer Port 3782 ungeschützt ins Netz stellt, gibt damit Chats, Dokumente und Modelleinstellungen frei. Schalten Sie die Anmeldung ein, bevor Sie einen Reverse Proxy davorsetzen:

sudo sed -i 's/"enabled": false/"enabled": true/' data/user/settings/auth.json
grep '"enabled"' data/user/settings/auth.json
docker compose restart deeptutor
curl -s http://127.0.0.1:8001/api/knowledge-bases

{"detail":"Not authenticated"}

Danach öffnen Sie /register und legen sofort das erste Konto an, denn laut Doku wird der erste registrierte Benutzer Administrator. Weitere Konten vergibt der Administrator unter /admin/users. Hinter einem Proxy mit HTTPS tragen Sie zusätzlich die Adresse der Oberfläche in cors_origins der Datei system.json ein.

Verifizieren: Die API antwortet ohne Anmeldung mit HTTP 401 und Not authenticated, /api/auth/is_first_user meldet bis zur ersten Registrierung true.

Schritt 6: Backup und Wiederherstellung

DeepTutor braucht keinen Datenbankserver. Einstellungen, Zugangsdaten, SQLite-Datenbanken mit den Gesprächen, Wissensbasen und Logs liegen alle unter data. Die Projektdoku verlangt, die Anwendung vor dem Kopieren zu stoppen, weil SQLite sonst offene Schreibvorgänge verlieren kann.

docker compose stop deeptutor redis
tar czf deeptutor-backup-$(date +%F).tgz data
docker compose start redis deeptutor

Das Archiv war im Test nur 46 KB groß und enthielt unter anderem data/user/chat_history.db, data/user/settings/model_catalog.json und data/knowledge_bases/musterfirma/. Die Modelle in ./ollama müssen nicht ins Backup, Sie laden sie bei Bedarf neu. Behandeln Sie das Archiv als vertraulich, es enthält Gesprächsinhalte und gegebenenfalls API-Schlüssel.

Für die Wiederherstellung simulierte der Test einen Totalverlust: Ordner gelöscht, Stack neu gestartet, kb list meldete No knowledge bases found. Danach:

docker compose down
rm -rf data
tar xzf deeptutor-backup-2026-10-30.tgz
docker compose up -d
docker compose exec -u deeptutor deeptutor python -m deeptutor_cli kb search musterfirma "Prüfcode Wiederherstellungstest"

Verifizieren: kb list zeigt wieder musterfirma mit Status ready, session list beide früheren Gespräche, und die Suche findet den im Handbuch hinterlegten Prüfcode ORANGE-PINGUIN-42.

Schritt 7: Update auf eine neue Version

Der Test startete bewusst mit 1.6.15 und wechselte dann auf 1.7.0. Sichern Sie vorher wie in Schritt 6, ändern Sie den Tag in der .env und ziehen Sie das neue Image:

sed -i 's/^DEEPTUTOR_TAG=.*/DEEPTUTOR_TAG=1.7.0/' .env
docker compose pull deeptutor
docker compose up -d
docker inspect $(docker compose ps -q deeptutor) \
  --format '{{index .Config.Labels "org.opencontainers.image.version"}}'

Nach dem Wechsel war die Instanz in zehn Sekunden bereit, Modellprofil und Wissensbasis waren unverändert vorhanden, und eine neue Frage aus der Wissensbasis wurde korrekt beantwortet. Die Upgrade-Hinweise zu 1.7.0 betreffen vor allem pip-Installationen (deeptutor[full]); im Container sind die Module bereits enthalten, python -m deeptutor_cli module list zeigt sie mit installed, enabled und ready.

Verifizieren: Das Label meldet 1.7.0, docker compose ps zeigt healthy, kb list listet die bestehende Wissensbasis.

Troubleshooting

Meldung	Ursache	Lösung
[ollama] Error calling LLM: Connection error. in doctor --online	Base-URL http://localhost:11434/v1; im Container ist das DeepTutor selbst	Dienstnamen http://ollama:11434/v1 eintragen, bei Ollama auf dem Host host.docker.internal mit extra_hosts
model 'llama3.2:3b' not found	Modell im Profil eingetragen, aber nicht in Ollama geladen	docker compose exec ollama ollama list prüfen, Modell mit ollama pull laden
exec: "deeptutor": executable file not found in $PATH	Im Image gibt es keinen Befehl deeptutor	python -m deeptutor_cli verwenden
No active LLM model is configured im Startlog	Frische Instanz ohne Modellprofil	Schritt 3 ausführen
curl auf /health/ready liefert 000	Backend startet noch	10 bis 20 Sekunden warten, Skripte mit Warteschleife statt set -e bauen
Oberfläche lädt, Einstellungen melden „Backend unreachable“	laut Doku fast immer ein nicht gestartetes Backend	docker compose logs deeptutor nach Zeilen von [program:backend] durchsuchen

Häufige Fragen

Brauche ich eine GPU?

Nein. Mit qwen2.5:1.5b auf einer reinen CPU kam die Antwort aus der Wissensbasis nach rund 25 Sekunden, davon etwa 15 Sekunden bis zum ersten Token. Für längere Antworten oder größere Modelle lohnt sich eine GPU deutlich. Kleine Modelle neigen außerdem dazu, englische Titel für Gespräche zu vergeben, auch wenn die Antwort deutsch ist.

Funktioniert DeepTutor auch mit Cloud-Modellen?

Ja. Das Projekt unterstützt viele Anbieter, darunter OpenAI, Anthropic und mehrere chinesische Plattformen. Die Schlüssel landen dann in data/user/settings/model_catalog.json, was das Backup noch schützenswerter macht. Für Firmendaten ist der lokale Weg mit Ollama datenschutzfreundlicher, weil keine Inhalte das Haus verlassen.

Warum Redis?

Redis koordiniert laut Compose-Vorlage die Abarbeitung von Gesprächsrunden über mehrere Worker. Der Dienst bekommt keinen veröffentlichten Port und ist nur im Compose-Netz erreichbar.

Kann ich PostgreSQL statt SQLite nutzen?

Nein. Laut Doku zur Datenhaltung ist SQLite das einzige unterstützte Backend, eine Variable wie DATABASE_URL wird ignoriert.

Fazit

DeepTutor 1.7.0 lässt sich mit drei Containern vollständig lokal betreiben: Installation, Modellanbindung über config apply, Wissensbasis, Backup mit Wiederherstellung und Update funktionierten im Test ohne Umwege. Die größten Stolpersteine sind localhost in der Modell-URL und die ab Werk abgeschaltete Anmeldung. Für eine Arbeitsgruppe, die interne Handbücher oder Lernmaterial befragbar machen will, ist das ein schneller Einstieg; wer viele Nutzer bedienen will, sollte eine GPU und ein stärkeres Modell einplanen.

Weiterführende Anleitungen und Quellen

• Docker und Docker Compose auf Linux installieren: die Self-Hosting-Grundlage
• Docker Compose absichern: Secrets, Healthchecks und Non-Root
• Caddy als Reverse Proxy mit automatischem HTTPS
• OpenCode als Docker-Server mit lokalem Ollama-Modell betreiben
• RAGFlow mit Docker: RAG-Engine selbst hosten
• HKUDS/DeepTutor auf GitHub
• Release-Notes DeepTutor v1.7.0
• DeepTutor Containerization (Projektdoku)
• DeepTutor Local Data Persistence (Projektdoku)
• DeepTutor Agent Setup mit config apply (Projektdoku)