Ollama im Docker-Container betreiben

Ollama stellt lokale Sprachmodelle über eine schlanke HTTP-API bereit. Im Container läuft der Dienst reproduzierbar, getrennt von den Bibliotheken des Hosts, und lässt sich mit einer Datei auf eine andere Maschine umziehen. Diese Anleitung zeigt das vollständige Setup: Container starten, Modelle persistent ablegen, GPU durchreichen und die API prüfen.

Warum Ollama im Docker-Container betreiben?

Ollama im Docker-Container zu betreiben trennt die Laufzeit samt CUDA-Bibliotheken vom Host-System, hält alle Modelle in einem benannten Volume und stellt die HTTP-API auf Port 11434 bereit, ohne dass du Pakete systemweit installierst.

Der praktische Unterschied zeigt sich beim Umzug und beim Upgrade. Ein natives Setup verteilt sich auf /usr/local/bin/ollama, eine systemd-Unit und ~/.ollama. Der Container kapselt genau diese drei Dinge in einem Image plus einem Volume.

Voraussetzungen

• Ein Linux-Host mit Docker Engine 24.0 oder neuer und Compose v2 (docker compose version)
• Ein Benutzerkonto mit sudo-Rechten oder Mitgliedschaft in der Gruppe docker
• Mindestens 8 GB RAM für Modelle der 7B-Klasse, 16 GB für komfortables Arbeiten
• Mindestens 20 GB freier Speicherplatz unter /var/lib/docker für die Modell-Blobs
• Optional eine NVIDIA-GPU mit Treiber 525 oder neuer

Für Tests reicht eine skalierbare Cloud-VM mit Shared oder Dedicated CPU aus. Ohne GPU läuft Ollama auf der CPU. Das funktioniert für kleine Modelle wie llama3.2:3b, ist aber deutlich langsamer als eine GPU-Inferenz.

Ollama-Container starten

Das offizielle Image heißt ollama/ollama und bindet den Server im Container bereits auf 0.0.0.0:11434. Genau deshalb solltest du die Portveröffentlichung auf dem Host einschränken, statt den Port offen ins Netz zu legen:

$ docker run -d \
    --name ollama \
    -p 127.0.0.1:11434:11434 \
    -v ollama:/root/.ollama \
    --restart unless-stopped \
    ollama/ollama:latest

Die Angabe 127.0.0.1:11434:11434 veröffentlicht die API ausschließlich auf der Loopback-Adresse des Hosts. Schreibst du nur -p 11434:11434, ist der Dienst auf allen Interfaces erreichbar, und Ollama bringt keine eigene Authentifizierung mit.

Prüfe direkt nach dem Start, ob der Container läuft:

$ docker ps --filter name=ollama --format '{{.Names}}\t{{.Status}}\t{{.Ports}}'
ollama  Up 12 seconds   127.0.0.1:11434->11434/tcp

Modelle persistent ablegen

Ollama speichert Modelle unter /root/.ollama/models. Ohne Volume liegen mehrere Gigabyte im Schreiblayer des Containers und sind beim nächsten docker rm verloren. Das benannte Volume ollama aus dem Startbefehl verhindert das.

$ docker volume inspect ollama --format '{{.Mountpoint}}'
/var/lib/docker/volumes/ollama/_data

Wenn dein Root-Dateisystem knapp ist, lege das Volume auf eine separate Platte oder nutze ein Bind-Mount auf einen eigenen Datenträger, etwa -v /data/ollama:/root/.ollama. Rechne pro Modell mit 2 bis 5 GB, bei größeren Varianten deutlich mehr.

Modelle laden und abfragen

Modelle lädst du über die CLI, die im Image bereits enthalten ist. docker exec spricht dabei den laufenden Server an:

$ docker exec -it ollama ollama pull llama3.2:3b
$ docker exec -it ollama ollama list
NAME             ID              SIZE      MODIFIED
llama3.2:3b      a80c4f17acd5    2.0 GB    12 seconds ago

Für einen interaktiven Test startest du eine Sitzung im Container. Mit /bye beendest du sie wieder:

$ docker exec -it ollama ollama run llama3.2:3b

Die eigentliche Integration läuft über HTTP. Der Endpunkt /api/generate liefert standardmäßig einen Stream aus JSON-Objekten. Mit "stream": false bekommst du eine einzelne Antwort:

$ curl -s http://127.0.0.1:11434/api/generate -d '{
    "model": "llama3.2:3b",
    "prompt": "Nenne drei Vorteile von Containern in einem Satz.",
    "stream": false
  }' | jq -r .response

Für Chat-Verläufe mit Rollen nutzt du /api/chat, für Embeddings /api/embed. Der Endpunkt /v1/chat/completions ist OpenAI-kompatibel, sodass bestehende Clients meist nur eine andere Basis-URL brauchen.

Wie reichst du eine NVIDIA-GPU an den Container durch?

Eine NVIDIA-GPU erreichst du im Ollama-Container über das NVIDIA Container Toolkit ab Version 1.14: Du registrierst die Runtime mit nvidia-ctk runtime configure, startest den Docker-Daemon neu und ergänzt den Startbefehl um --gpus=all.

$ curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
    | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
$ sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
$ sudo nvidia-ctk runtime configure --runtime=docker
$ sudo systemctl restart docker

Anschließend erstellst du den Container neu, diesmal mit GPU-Zugriff:

$ docker rm -f ollama
$ docker run -d --name ollama --gpus=all \
    -p 127.0.0.1:11434:11434 \
    -v ollama:/root/.ollama \
    --restart unless-stopped \
    ollama/ollama:latest

Das Volume überlebt das Löschen des Containers, die Modelle musst du also nicht erneut laden. Für AMD-Karten nimmst du stattdessen den Tag ollama/ollama:rocm und reichst /dev/kfd sowie /dev/dri durch.

Der folgende Ablauf zeigt, welchen Weg eine Anfrage nimmt und wo die Entscheidung zwischen GPU und CPU fällt:

graph TD
  A["Client oder curl"] -->|"HTTP auf Port 11434"| B["Docker-Host"]
  B --> C["Container ollama"]
  C --> D["Volume ollama:/root/.ollama"]
  C --> E{"NVIDIA-Runtime verfügbar?"}
  E -->|"ja"| F["Inferenz auf der GPU"]
  E -->|"nein"| G["Rückfall auf die CPU, spürbar langsamer"]
  F --> H["Antwort als JSON-Stream"]
  G --> H

Setup mit Docker Compose

Sobald Portbindung, Volume und Umgebungsvariablen feststehen, gehört das Setup in eine Datei. Lege /opt/ollama/compose.yaml an:

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    ports:
      - "127.0.0.1:11434:11434"
    volumes:
      - ollama:/root/.ollama
    environment:
      - OLLAMA_KEEP_ALIVE=15m
      - OLLAMA_MAX_LOADED_MODELS=2
      - OLLAMA_NUM_PARALLEL=2
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: ["gpu"]
volumes:
  ollama:

Den Block deploy.resources.reservations.devices wertet Compose v2 auch ohne Swarm aus. Ohne GPU im Host entfernst du ihn, sonst verweigert Docker den Start. Danach:

$ cd /opt/ollama
$ docker compose up -d
$ docker compose logs -f ollama

Welche Umgebungsvariablen steuern Ollama im Container?

Ollama liest seine Laufzeitkonfiguration ausschließlich aus Umgebungsvariablen, die wichtigsten sind OLLAMA_KEEP_ALIVE, OLLAMA_MAX_LOADED_MODELS, OLLAMA_NUM_PARALLEL und OLLAMA_CONTEXT_LENGTH für Speicherverhalten, Parallelität und Kontextgröße.

Setze OLLAMA_KEEP_ALIVE=-1, wenn ein Modell dauerhaft geladen bleiben soll. Das eliminiert die Ladezeit beim ersten Request, belegt aber permanent VRAM. Auf Hosts mit knappem Speicher ist ein Wert von wenigen Minuten die bessere Wahl.

Verifikation

Drei Prüfungen zeigen, dass das Setup vollständig funktioniert. Zuerst die API selbst:

$ curl -s http://127.0.0.1:11434/api/tags | jq '.models[].name'
"llama3.2:3b"

Dann die GPU-Nutzung. Der Befehl listet geladene Modelle mit dem Anteil, der auf GPU beziehungsweise CPU liegt:

$ docker exec ollama ollama ps
NAME           ID              SIZE      PROCESSOR    UNTIL
llama3.2:3b    a80c4f17acd5    3.5 GB    100% GPU     14 minutes from now

Steht dort 100% CPU, obwohl eine Karte vorhanden ist, greift die Runtime nicht. Prüfe das direkt im Container:

$ docker exec ollama nvidia-smi --query-gpu=name,memory.used --format=csv

Zuletzt die Persistenz. Nach docker compose down und docker compose up -d muss ollama list dieselben Modelle zeigen. Ist die Liste leer, hat das Volume nicht gegriffen.

Troubleshooting

could not connect to ollama app bei docker exec ollama ollama pull: Der Server im Container ist noch nicht bereit oder abgestürzt. docker logs ollama zeigt den Grund, meist ein fehlgeschlagener GPU-Init nach einem Treiber-Update auf dem Host.

could not select device driver "nvidia" beim Start: Die Runtime ist nicht registriert. Führe sudo nvidia-ctk runtime configure --runtime=docker aus und starte den Docker-Daemon neu. Prüfe danach, ob nvidia in /etc/docker/daemon.json unter runtimes steht.

no space left on device während ollama pull: Das Volume liegt unter /var/lib/docker und die Partition ist voll. Räume alte Modelle mit docker exec ollama ollama rm <modellname> ab oder verschiebe das Volume auf einen eigenen Datenträger. Wenn du Modelle für mehrere Hosts vorhältst, lohnt sich ein separater Datenträger statt des Root-Dateisystems.

Verbindung von einem anderen Host schlägt fehl: Das ist bei der Bindung an 127.0.0.1 erwartet. Stelle Ollama nicht direkt ins Netz, sondern setze einen Reverse Proxy mit TLS und Authentifizierung davor, etwa nginx mit proxy_pass http://127.0.0.1:11434; und proxy_buffering off; für Streaming-Antworten.

Fazit

Mit dem Image ollama/ollama, einem benannten Volume und einer Portbindung auf 127.0.0.1 läuft ein lokaler LLM-Dienst in wenigen Minuten. Kontrolliere nach jedem Treiber- oder Image-Update mit ollama ps, ob die Inferenz weiterhin auf der GPU landet: Ein stiller Rückfall auf die CPU kostet Faktoren an Antwortzeit und fällt sonst erst unter Last auf.

Weitere Docker-Themen

• Docker-Volumes mit Restic verschlüsselt sichern
• Nextcloud mit Docker Compose betreiben
• Docker-Images mit mehrstufigen Builds verkleinern