Add DockerHub README with usage, env vars and compose examples

2026-04-29 08:26:47 +02:00 · 2026-04-29 08:26:47 +02:00 · 03712fe401
commit 03712fe401
parent a0512b3b2b
1 changed files with 149 additions and 0 deletions
--- a/DOCKERHUB.md
+++ b/DOCKERHUB.md
@ -0,0 +1,149 @@
+# mediaeng/llmproxy
+
+Ein schlanker Reverse-Proxy für [Ollama](https://ollama.com), der API-Keys mit konfigurierbaren Token- und Request-Quoten verwaltet. Eingehende Anfragen im OpenAI-kompatiblen Format werden authentifiziert, auf Quota geprüft und an den konfigurierten Ollama-Server weitergeleitet.
+
+## Funktionen
+
+- OpenAI-kompatibler Endpunkt (`/v1/chat/completions`, `/v1/models`)
+- API-Key-Verwaltung mit tages- und monatlichen Token-/Request-Limits
+- Web-basierte Admin-Oberfläche (Port 8001)
+- Streaming-Support (Server-Sent Events)
+- Tool-Use / Function Calling wird durchgereicht
+- Rotierende Nutzungs-Logs
+- SQLite (Standard) oder PostgreSQL
+
+## Ports
+
+| Port | Dienst |
+|------|--------|
+| `8000` | Proxy-Endpunkt (OpenAI-API) |
+| `8001` | Admin-API + Web-Oberfläche |
+
+> **Hinweis:** Port 8001 sollte nicht öffentlich erreichbar sein. Den Zugriff auf die Admin-Oberfläche über einen Reverse-Proxy oder SSH-Tunnel absichern.
+
+## Umgebungsvariablen
+
+| Variable | Standard | Beschreibung |
+|----------|----------|--------------|
+| `ADMIN_PASSWORD` | – | **Pflicht.** Passwort für die Admin-Oberfläche |
+| `OLLAMA_URL` | `http://localhost:11434` | URL des Ollama-Servers (ohne `/v1`-Suffix) |
+| `DEFAULT_MODEL` | `llama3` | Modell, das verwendet wird wenn der Client keines angibt |
+| `DATABASE_URL` | `sqlite:///./test.db` | Datenbank-Verbindungsstring (SQLite oder PostgreSQL) |
+| `PROXY_HOST` | `0.0.0.0` | Bind-Adresse des Proxy |
+| `PROXY_PORT` | `8000` | Port des Proxy |
+| `ADMIN_PORT` | `8001` | Port der Admin-API |
+| `ALLOWED_ORIGINS` | `http://localhost:5173` | CORS-Ursprünge für die Admin-Oberfläche (kommagetrennt) |
+| `APP_TZ` | `Europe/Berlin` | Zeitzone für Tages-/Monats-Reset der Quoten |
+| `LOG_FILE` | `logs/usage.log` | Pfad der rotierenden Nutzungs-Logdatei |
+
+## Docker Compose – SQLite
+
+Einfachste Variante, Daten werden in einem Volume persistiert.
+
+```yaml
+services:
+  llmproxy:
+    image: mediaeng/llmproxy:latest
+    restart: unless-stopped
+    ports:
+      - "8000:8000"
+      - "127.0.0.1:8001:8001"   # Admin nur lokal erreichbar
+    environment:
+      ADMIN_PASSWORD: changeme
+      OLLAMA_URL: http://ollama:11434
+      DEFAULT_MODEL: llama3
+      APP_TZ: Europe/Berlin
+    volumes:
+      - llmproxy-data:/app/backend
+    depends_on:
+      - ollama
+
+  ollama:
+    image: ollama/ollama:latest
+    restart: unless-stopped
+    volumes:
+      - ollama-data:/root/.ollama
+
+volumes:
+  llmproxy-data:
+  ollama-data:
+```
+
+## Docker Compose – PostgreSQL
+
+Für Produktionsumgebungen mit externer Datenbank.
+
+> **Voraussetzung:** PostgreSQL-Unterstützung erfordert `psycopg2-binary` im Image. Entweder ein eigenes Image auf Basis von `mediaeng/llmproxy` bauen oder den Container beim Start erweitern:
+> ```dockerfile
+> FROM mediaeng/llmproxy:latest
+> RUN pip install psycopg2-binary
+> ```
+
+```yaml
+services:
+  llmproxy:
+    image: mediaeng/llmproxy:latest   # oder eigenes Image mit psycopg2
+    restart: unless-stopped
+    ports:
+      - "8000:8000"
+      - "127.0.0.1:8001:8001"
+    environment:
+      ADMIN_PASSWORD: changeme
+      OLLAMA_URL: http://ollama:11434
+      DEFAULT_MODEL: llama3
+      APP_TZ: Europe/Berlin
+      DATABASE_URL: postgresql://llmproxy:secret@db:5432/llmproxy
+    depends_on:
+      db:
+        condition: service_healthy
+      ollama:
+        - ollama
+
+  db:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_DB: llmproxy
+      POSTGRES_USER: llmproxy
+      POSTGRES_PASSWORD: secret
+    volumes:
+      - pg-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U llmproxy"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  ollama:
+    image: ollama/ollama:latest
+    restart: unless-stopped
+    volumes:
+      - ollama-data:/root/.ollama
+
+volumes:
+  pg-data:
+  ollama-data:
+```
+
+## Schnellstart
+
+```bash
+docker run -d \
+  -p 8000:8000 \
+  -p 127.0.0.1:8001:8001 \
+  -e ADMIN_PASSWORD=changeme \
+  -e OLLAMA_URL=http://host.docker.internal:11434 \
+  -v llmproxy-data:/app/backend \
+  mediaeng/llmproxy:latest
+```
+
+Admin-Oberfläche: `http://localhost:8001`
+
+## Client-Konfiguration
+
+Den Proxy als OpenAI-kompatibler Endpunkt konfigurieren:
+
+```
+Base URL:  http://<host>:8000/v1
+API Key:   <angelegter API-Key aus der Admin-Oberfläche>
+```