Die Dokumentationssite bereitstellen

Diese Seite dokumentiert, wie die Dokumentationssite in der Produktionsumgebung bereitgestellt wird. Die Einrichtung verwendet jwilder/nginx-proxy für automatische Docker-Containerrouting, letsencrypt-nginx-proxy-companion für HTTPS und Ihre eigene Ollama unter your-ollama-host.example für den Oracle-Backend — keine bezahlten LLM-API-Schlüssel erforderlich.

Topologie

                     Internet
                        │
                        ▼
            ┌──────────────────────┐
            │ jwilder/nginx-proxy  │  ← reverse proxy on :80 / :443
            │ (network: nginx-proxy)│    terminates TLS
            └──────────┬───────────┘
                       │ http://nibiru-docs:4321
                       ▼
            ┌──────────────────────┐         ┌──────────────────────┐
            │ nibiru-docs          │ ──────▶ │ your-ollama-host.example     │
            │ Astro Node SSR :4321 │ HTTPS   │ Ollama (5× GPU)      │
            │ Oracle endpoint      │         │ qwen2.5-coder:14b    │
            └──────────────────────┘         │ nomic-embed-text     │
                                             └──────────────────────┘

Voraussetzungen auf dem Host

# 1) Create the shared external network (one time)
docker network create nginx-proxy

# 2) Run nginx-proxy + acme-companion (one time)
#    See https://github.com/nginx-proxy/nginx-proxy for the canonical compose.

# 3) Pull the Oracle's models on your Ollama instance (one time)
curl https://your-ollama-host.example/api/pull -d '{"name":"qwen2.5-coder:14b"}'
curl https://your-ollama-host.example/api/pull -d '{"name":"nomic-embed-text"}'

Dateien in docs/

Datei	Zweck
Dockerfile	Mehrstufiger Build: erstellt Oracle-Index gegen your Ollama instance, baut Astro, entfernt Entwicklungsabhängigkeiten.
docker-compose.yml	Produktion — VIRTUAL_HOST=nibiru-framework.com, verbunden mit dem Netzwerk nginx-proxy.
docker-compose.local.yml	Lokale-Test-Überschreibung — macht Port 4321:4321 verfügbar, entfernt Umgebungsvariablen von nginx-proxy.
.dockerignore	Verhindert, dass node_modules, .git usw. in den Build-Kontext aufgenommen werden.
.env.example	Vorlage — standardmäßig verwendet Ollama auf Ihrer Ollama-Instanz, keine API-Schlüssel erforderlich.

Befehl ausführen

cd docs
cp .env.example .env
# defaults are fine for production unless you want to override the Ollama URL or models

docker compose up -d --build

Der erste Build führt build-oracle-index.mjs aus, um die Dokumentation in Ihr Ollama einzubetten. Nachfolgende Neuaufbauten sind schnell – Docker speichert den Abhängigkeitslayer im Cache; nur geänderte Blöcke müssen erneut eingebettet werden.

Nach etwa 30 Sekunden erkennt jwilder/nginx-proxy den neuen Container und fordert ein Let’s Encrypt-Zertifikat an. Anschließend leitet es https://nibiru-framework.com zu :4321 weiter.

Überprüfen

curl -s https://nibiru-framework.com/api/oracle | jq
# {
#   "status": "ok",
#   "llm":   { "provider": "ollama", "model": "qwen2.5-coder:14b", … },
#   "embed": { "provider": "ollama", "model": "nomic-embed-text", … },
#   "index": { "present": true, "chunks": 177, … }
# }

Oder öffnen Sie die Seite im Browser, klicken Sie auf den gelben Oracle-Launcher und stellen Sie eine Frage.

Aktualisierung nach einer Dokumentenänderung

git pull
docker compose up -d --build

Der Build führt den Oracle-Index erneut gegen den neuesten Inhalt aus; der neue Container startet auf :4321; jwilder wechselt den Upstream; der alte Container wird gestoppt – kein auffälliger Ausfallzeitraum.

Umgebungsvariablen

Var	Default	Used at	Purpose
LLM_PROVIDER	ollama	runtime	ollama (default) oder anthropic.
OLLAMA_BASE_URL	https://your-ollama-host.example	build + runtime	Wo Ollama erreichbar ist.
OLLAMA_CHAT_MODEL	qwen2.5-coder:14b	runtime	Chat-Vervollständigungsmodell.
OLLAMA_EMBED_MODEL	nomic-embed-text	build + runtime	Einbettungsmodell.
EMBED_PROVIDER	ollama	build + runtime	ollama oder openai.
ANTHROPIC_API_KEY	—	runtime	Nur verwendet, wenn LLM_PROVIDER=anthropic.
ANTHROPIC_MODEL	claude-haiku-4-5-20251001	runtime	Claude-Modell überschreiben.
OPENAI_API_KEY	—	build + runtime	Nur verwendet, wenn EMBED_PROVIDER=openai.
ORACLE_TOP_K	6	runtime	Chunks pro Oracle-Antwort eingefügt.
LETSENCRYPT_EMAIL	stephan.kasdorf@bittomine.com	letsencrypt	Wo Let’s Encrypt Ablaufbenachrichtigungen sendet.
VIRTUAL_HOST	nibiru-framework.com,www.nibiru-framework.com	nginx-proxy	In Compose setzen.

Problembehandlung

502 Bad Gateway. Der Upstream-Container konnte nicht gestartet werden. Überprüfen Sie docker logs nibiru-docs – wahrscheinlich fehlt ein Build-Artefakt in dist/server/entry.mjs.

Zertifikat nicht ausgestellt. Let’s Encrypt begrenzt die Anzahl der Ausgaben sehr restriktiv. Überprüfen Sie docker logs letsencrypt-nginx-proxy-companion, um den Grund zu ermitteln.

Oracle antwortet ohne Zitate. Der Einbettungsindex ist leer. Entweder wurde nomic-embed-text nicht auf Ollama gezogen, oder der Build konnte nicht zu your Ollama instance erreichen. Laden Sie das Modell erneut herunter:```bash curl https://your-ollama-host.example/api/pull -d ’{“name”:“nomic-embed-text”}’ docker compose up -d —build

**Oracle gibt "der Oracle konnte nicht antworten".** Überprüfen Sie, ob das Chat-Modell abgerufen wurde:```bash
curl https://your-ollama-host.example/api/tags | jq '.models[].name'

Wollen Sie zu Claude zurückfallen? Legen Sie LLM_PROVIDER=anthropic und ANTHROPIC_API_KEY in .env fest, dann führen Sie docker compose up -d aus.

Ressourcennutzung

	Leerlauf	Unter Oracle-Last
RAM	ca. 120 MB	ca. 200 MB
CPU	< 0,5%	ca. 5%
Netzwerk	minimal	ein HTTPS-Roundtrip pro Frage
Festplatte	ca. 60 MB Bild + ca. 5 MB Index	+ Korpus-Exporte

Ein Droplet mit 1 GB Speicher und 1 vCPU verarbeitet die Dokumentationssite problemlos zusammen mit anderen Diensten. Die intensiven Berechnungen (LLM-Inferenz) erfolgen in Ihrem GPU-Cluster, nicht im Dokumentationscontainer.