text-generation-webui mit Docker installieren: Umfassende Web-UI für lokale LLMs (llama.cpp, ExLlama, Transformers)

Wer lokale Large Language Models betreiben will, ohne sich auf Cloud-Dienste verlassen zu müssen, findet in text-generation-webui von oobabooga (Repository inzwischen unter oobabooga/textgen) eine weit verbreitete Lösung. Die Gradio-Oberfläche unterstützt Backends wie llama.cpp, ExLlamaV2 und Transformers sowie die Formate GGUF, GPTQ, AWQ, EXL2 und Safetensors. Port 5000 bietet optional eine OpenAI-kompatible API für LangChain, Continue.dev oder das OpenAI SDK. Diese Anleitung richtet text-generation-webui per Docker Compose auf einem Linux-Host oder einer VM ein.

Voraussetzungen

1. Docker Engine >= 24.0 mit Compose Plugin v2.17+ (docker compose mit Leerzeichen, nicht das veraltete docker-compose v1) – siehe Docker und Docker Compose auf Linux installieren
2. Linux-Host, VM oder NAS mit Docker-Unterstützung (x86_64; arm64 ist nicht offiziell unterstützt)
3. NVIDIA GPU mit CUDA-Support (empfohlen: RTX 3080 oder besser, mindestens 8 GB VRAM) und NVIDIA Container Toolkit auf dem Host – oder AMD GPU mit ROCm oder mindestens 16 GB RAM für CPU-only-Betrieb
4. Mindestens 20 GB freier Speicherplatz für Image-Build und Modelle (Modelle allein: 4–70 GB je nach Größe)
5. git und curl auf dem Host installiert
6. Für HTTPS nach außen: ein Reverse Proxy wie Nginx Proxy Manager oder Traefik – die Grundkonfiguration ist in Traefik als Docker-Reverse-Proxy beschrieben

Schritt 1: Repository klonen und Projektordner vorbereiten

text-generation-webui veröffentlicht keine fertigen Images auf Docker Hub oder GHCR. Der Build läuft lokal aus dem geklonten Repository. Für eine NVIDIA-GPU wechseln Sie nach dem Klonen in docker/nvidia/; für AMD, Intel Arc (Beta) und CPU-only gibt es analoge Verzeichnisse. Die alte Repository-URL leitet GitHub auf oobabooga/textgen weiter.

# Repository klonen (einmalig)
git clone https://github.com/oobabooga/text-generation-webui.git
cd text-generation-webui

# Für NVIDIA-GPU:
cd docker/nvidia

# Für AMD (ROCm):
# cd docker/amd

# Für CPU-only:
# cd docker/cpu

# user_data-Verzeichnis anlegen (PFLICHT vor dem ersten Start)
mkdir -p user_data

# .env aus dem Beispiel erstellen
cp ../.env.example .env

Legen Sie user_data/ vor dem Start selbst an. Fehlt es, erzeugt Docker es beim Start als root-eigenes Verzeichnis, in das der Container nicht schreiben kann. Es enthält später Modelle, Presets, Charaktere, Logs und die zentrale CMD_FLAGS.txt.

Verifizieren: Die folgenden Dateien und Verzeichnisse sind vorhanden:

ls -la
# Erwartete Ausgabe (u. a.):
# drwxr-xr-x  user_data/
# -rw-r--r--  .env
# -rw-r--r--  docker-compose.yml

Schritt 2: .env anpassen

Die wichtigste Einstellung ist TORCH_CUDA_ARCH_LIST: Dieser Wert muss zur CUDA Compute Capability Ihrer GPU passen. Ist er falsch, bricht der Build mit CUDA-Kompilierungsfehlern ab. Die Werte für gängige Consumer-GPUs:

Den Wert Ihrer GPU liefert nvidia-smi --query-gpu=name,compute_cap --format=csv oder https://developer.nvidia.com/cuda-gpus. Passen Sie die .env an. Die Ports binden Sie über die Hostseite an 127.0.0.1, da die Web-UI keine Anmeldung hat:

# .env – wichtige Werte
# PFLICHT: CUDA Compute Capability der eigenen GPU anpassen!
TORCH_CUDA_ARCH_LIST=8.6

# Ports: nur lokal erreichbar (Zugriff von außen per Reverse Proxy oder SSH-Tunnel)
HOST_PORT=127.0.0.1:7860
CONTAINER_PORT=7860
HOST_API_PORT=127.0.0.1:5000
CONTAINER_API_PORT=5000

# Dateiberechtigungen auf Linux (eigene GID eintragen: id -g)
APP_RUNTIME_GID=1000

# Extensions beim Build kompilieren (optional, leer lassen für Standard)
BUILD_EXTENSIONS=

Verifizieren: Die gesetzten Werte enthalten Ihren TORCH_CUDA_ARCH_LIST-Wert:

grep -v '^#' .env | grep -v '^$'
# Erwartete Ausgabe enthält u. a.:
# TORCH_CUDA_ARCH_LIST=8.6

Schritt 3: Image bauen

Der Build kompiliert PyTorch-Erweiterungen und CUDA-Kernel – das dauert beim ersten Mal 20 bis 60 Minuten. Nicht unterbrechen; den Fortschritt zeigt die Ausgabe von docker compose build selbst.

# Im Verzeichnis docker/nvidia/ (oder amd/cpu/intel/)
docker compose build

Ohne Build nutzen Sie das Community-Image (siehe „Häufige Fragen“).

Verifizieren: Nach dem erfolgreichen Build erscheint das Image in der lokalen Registry:

docker images | grep textgen
# Erwartete Ausgabe (Beispiel, Name nach Projektordner):
# nvidia-textgen   latest   a1b2c3d4e5f6   5 minutes ago   12.4GB

Schritt 4: Container starten

Das Repository bringt eine fertige docker-compose.yml mit, die alle GPU-Ressourcen, Volumes und Ports bereits korrekt verdrahtet. Die wichtigsten Eckdaten:

Die docker-compose.yml für NVIDIA aus dem Repository; die Zeile restart: unless-stopped ergänzen Sie selbst, sie fehlt im Original:

version: "3.3"

services:
  textgen:
    build:
      context: .
      args:
        TORCH_CUDA_ARCH_LIST: ${TORCH_CUDA_ARCH_LIST:-8.6;8.9+PTX}
        BUILD_EXTENSIONS: ${BUILD_EXTENSIONS:-}
        APP_GID: ${APP_GID:-6972}
        APP_UID: ${APP_UID:-6972}
    env_file: .env
    user: "${APP_RUNTIME_UID:-6972}:${APP_RUNTIME_GID:-6972}"
    ports:
      - "${HOST_PORT:-7860}:${CONTAINER_PORT:-7860}"
      - "${HOST_API_PORT:-5000}:${CONTAINER_API_PORT:-5000}"
    stdin_open: true
    tty: true
    volumes:
      - ./user_data:/home/app/textgen/user_data
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Starten Sie den Container im Hintergrund:

docker compose up -d

Verifizieren: Container-Status und Logs zeigen einen laufenden Dienst:

docker compose ps
# Erwartete Ausgabe:
# NAME        IMAGE          COMMAND   SERVICE   STATUS    PORTS
# nvidia-textgen-1   nvidia-textgen   ...   textgen   Up   127.0.0.1:7860->7860/tcp

docker compose logs --tail=30
# Erwartete Ausgabe am Ende (im Container):
# Running on local URL:  http://0.0.0.0:7860

Schritt 5: Web-UI öffnen und erstes Modell laden

Rufen Sie http://localhost:7860 auf, von einem anderen Rechner per SSH-Tunnel (ssh -L 7860:127.0.0.1:7860 benutzer@host). Beim ersten Start ist kein Modell geladen.

Öffnen Sie den Tab „Model“ und geben Sie eine Hugging-Face-Repo-ID ein, zum Beispiel:

1. TheBloke/Mistral-7B-Instruct-v0.2-GGUF – kompaktes 7B-Modell im GGUF-Format, läuft auch mit 8 GB VRAM
2. TheBloke/Llama-2-13B-chat-GGUF – für 16+ GB VRAM

Klicken Sie auf „Download“ und warten Sie, bis das Modell in user_data/models/ liegt. Wählen Sie es in der Liste aus, klicken Sie auf „Load“ und wechseln Sie in den Tab „Chat“.

Alternativ kopieren Sie Modelldateien nach user_data/models/<Modellname>/; sie erscheinen beim nächsten Laden der Liste.

Verifizieren: Die Web-UI antwortet, und im Chat-Tab liefert das geladene Modell eine Antwort:

curl -I http://localhost:7860
# Erwartete Ausgabe:
# HTTP/1.1 200 OK
# content-type: text/html; charset=utf-8

Schritt 6: OpenAI-kompatible API aktivieren

Die API auf Port 5000 ist standardmäßig deaktiviert. Sie aktivieren sie dauerhaft über CMD_FLAGS.txt im persistenten user_data/-Verzeichnis. Setzen Sie mit --api-key einen Schlüssel, sonst nimmt die API Anfragen ohne Prüfung an:

# CMD_FLAGS.txt anlegen/bearbeiten
echo "--api --listen --api-key $(openssl rand -hex 24)" > user_data/CMD_FLAGS.txt
cat user_data/CMD_FLAGS.txt   # Schlüssel notieren

# Container neu starten damit die Flags wirken
docker compose restart

Die API ist anschließend unter http://127.0.0.1:5000/v1 erreichbar und spricht das OpenAI-Schema, etwa für LangChain, Continue.dev oder das OpenAI Python SDK. Wer damit eigene RAG-Pipelines aufbauen möchte, findet weiterführende Hinweise in der Anleitung zu lokalen RAG-Systemen mit Qdrant.

Verifizieren: Die API antwortet mit dem Schlüssel (IHR-API-KEY ersetzen):

curl http://localhost:5000/v1/models -H "Authorization: Bearer IHR-API-KEY"
# Erwartete Ausgabe: JSON mit geladenen Modellen
# {"object":"list","data":[{"id":"Mistral-7B-Instruct...","object":"model",...}]}

curl http://localhost:5000/v1/chat/completions \
  -H "Authorization: Bearer IHR-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"","messages":[{"role":"user","content":"Hallo!"}],"max_tokens":50}'
# Erwartete Ausgabe: JSON mit "choices" und Modellantwort

Schritt 7: Updates und Backup

Da text-generation-webui lokal gebaut wird, läuft ein Update über git pull und anschließenden Rebuild:

# Ins Repository-Root-Verzeichnis wechseln
cd /pfad/zu/text-generation-webui

# Neue Version holen
git pull

# Zurück in den Varianten-Ordner und neu bauen
cd docker/nvidia
docker compose build --no-cache
docker compose up -d

Alle Modelle, Einstellungen und Charaktere liegen in user_data/ – sichern Sie dieses Verzeichnis. Ein einfaches rsync oder die 3-2-1-Backup-Strategie genügen, um alles zu sichern.

Beim Community-Image (atinoda/text-generation-webui) läuft das Update einfacher:

docker compose pull
docker compose up -d

Verifizieren: Der Container läuft nach dem Update wieder:

docker compose ps
# STATUS: Up (running)

docker compose logs --tail=10
# Keine Fehlermeldungen zu fehlenden Modulen oder CUDA-Fehler

Troubleshooting / Typische Fehler

1. Build bricht mit CUDA-Kompilierungsfehler ab: TORCH_CUDA_ARCH_LIST in .env stimmt nicht mit der GPU überein. Wert auf https://developer.nvidia.com/cuda-gpus nachschlagen und anpassen, dann docker compose build --no-cache erneut ausführen.
2. „could not select device driver nvidia“: Das NVIDIA Container Toolkit fehlt oder ist nicht für Docker konfiguriert. Nach der Installation laut NVIDIA-Installationsanleitung (Paketquelle einrichten, nvidia-container-toolkit installieren) führen Sie sudo nvidia-ctk runtime configure --runtime=docker und sudo systemctl restart docker aus.
3. Schreibfehler in user_data/ nach dem ersten Start: Das Verzeichnis fehlte und wurde von Docker als root angelegt. Lösung: Container stoppen, sudo chown -R $(id -u):$(id -g) user_data, APP_RUNTIME_GID prüfen, neu starten.
4. Port 7860 bereits belegt: Ein anderer Dienst nutzt diesen Port. HOST_PORT=127.0.0.1:7861 in .env setzen und Container neu starten.
5. Berechtigungsfehler in user_data/ (Linux): Der Container kann keine Dateien schreiben. APP_RUNTIME_GID in .env auf die eigene GID setzen (id -g liefert den Wert), danach docker compose up -d.
6. API auf Port 5000 nicht erreichbar: --api fehlt in user_data/CMD_FLAGS.txt, oder die Anfrage enthält nicht den Schlüssel aus --api-key (HTTP 401/403). Eintrag ergänzen und docker compose restart ausführen.
7. Modell-Download schlägt fehl (gated Models): HuggingFace-Token fehlt. Token in den Web-UI-Einstellungen unter „Hugging Face“ eintragen oder als Umgebungsvariable HF_TOKEN in die .env aufnehmen.
8. Build dauert extrem lange oder hängt: Normaler Vorgang bei der ersten CUDA-Kompilierung (20–60 Minuten). Nicht abbrechen; der Fortschritt steht in der Ausgabe von docker compose build.
9. docker-compose: command not found oder Syntax-Fehler: Das veraltete docker-compose v1 ist im Einsatz. Pflicht ist docker compose (mit Leerzeichen) als Plugin in Version 2.17+.

Häufige Fragen

Welche Modelle werden unterstützt?

Alle gängigen Open-Source-LLMs im GGUF-, GPTQ-, AWQ-, EXL2- und HuggingFace-Safetensors-Format – darunter LLaMA 3, Mistral, Qwen, Phi, Gemma und Falcon. Der Download läuft direkt über die Web-UI im Tab „Model“: Hugging-Face-Repo-ID eingeben, Modell-Datei auswählen, herunterladen.

Was ist der Unterschied zwischen offiziellem Build und dem atinoda-Community-Image?

Das offizielle Projekt veröffentlicht keine fertigen Images, Sie bauen lokal. Das Community-Image atinoda/text-generation-webui ist ein fertiges Image ohne Build-Schritt, folgt dem Upstream-Projekt aber mit Verzögerung. Beispiel mit Ports nur auf 127.0.0.1:

version: "3.3"
services:
  textgen:
    image: atinoda/text-generation-webui:default-nvidia
    # CPU-only: atinoda/text-generation-webui:default-cpu
    environment:
      - EXTRA_LAUNCH_ARGS=--verbose --listen --api
    ports:
      - "127.0.0.1:7860:7860"
      - "127.0.0.1:5000:5000"
      - "127.0.0.1:5005:5005"
    volumes:
      - ./config:/app/user_data
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

Kann ich text-generation-webui ohne GPU (CPU-only) betreiben?

Ja: docker/cpu/docker-compose.yml verwenden. Die Inferenz ist deutlich langsamer als auf einer GPU, aber funktional – llama.cpp ist speziell für CPU-Betrieb optimiert. Empfehlenswert sind mindestens 16 GB RAM; mit 32 GB laufen 7B-Modelle in guter Qualität.

Ist AMD-GPU-Betrieb möglich?

Ja, über docker/amd/docker-compose.yml mit ROCm-kompatiblen GPUs (RX 6000/7000-Serie). ROCm muss auf dem Host installiert sein; das Projekt beschreibt den AMD-Weg als experimentell.

Wie nutze ich text-generation-webui als OpenAI-API-Ersatz?

Nach Schritt 6 tragen Sie in LangChain, Continue.dev oder dem OpenAI Python SDK http://127.0.0.1:5000/v1 als Basis-URL und den Wert aus --api-key als API-Key ein. Bestehende Skripte laufen so ohne Code-Änderung mit einem lokalen Modell.

Wie viel Speicherplatz brauche ich?

Das Docker-Image nach dem Build belegt je nach Variante 10–15 GB. Modelle kommen obendrauf: Ein 7B-Modell in Q4-Quantisierung (GGUF) belegt ca. 4–5 GB, ein 13B-Modell ca. 8–10 GB, ein 70B-Modell 40–70 GB. Legen Sie user_data/ auf ein Laufwerk mit ausreichend Platz, am besten nicht auf das System-Volume.

Fazit

text-generation-webui eignet sich, wenn Sie lokale LLMs mit vielen Formaten und Backends betreiben wollen. Der Docker-Weg erfordert einmalig einen längeren Build und trennt Image und Daten sauber: user_data/ hält Modelle und Einstellungen, CMD_FLAGS.txt die Startoptionen. Mit aktivierter API und API-Key nutzen bestehende OpenAI-Tools das lokale Modell, ohne Daten an Cloud-Dienste zu geben.

Alternativen: Ollama mit Open WebUI ist der einfachere Einstieg, vLLM für offene LLMs zielt auf hohen Durchsatz im Produktivbetrieb. Einen weiteren OpenAI-kompatiblen Server beschreibt LocalAI als OpenAI-kompatibler KI-Server.

Weiterführende Anleitungen und Quellen

1. Ollama und Open WebUI mit Docker: eigenes lokales KI-Sprachmodell ohne Cloud betreiben
2. Offene LLMs selbst serven mit vLLM (Llama, Mistral, Hermes)
3. LocalAI mit Docker: lokaler, OpenAI-kompatibler KI-Server
4. Docker und Docker Compose auf Linux installieren: die Self-Hosting-Grundlage
5. 3-2-1-Backup-Strategie umsetzen: Anleitung mit Restic, USB-Disk und S3-Cloud

Offizielle Dokumentation: text-generation-webui GitHub Repository | Docker-Dokumentation (docs/09 - Docker.md) | atinoda/text-generation-webui auf Docker Hub