Déploiement du site de documentation

Cette page documente comment le site de documentation est déployé en production. La configuration utilise jwilder/nginx-proxy pour le routage automatique des conteneurs Docker, letsencrypt-nginx-proxy-companion pour HTTPS et votre propre Ollama à your-ollama-host.example pour le backend Oracle — aucune clé API LLM payante n’est requise.

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     │
                                             └──────────────────────┘

Prérequis sur l’hôte

# 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"}'

Fichiers dans docs/

Fichier	Objectif
Dockerfile	Construction multi-stages : construit l’index Oracle contre your Ollama instance, construit Astro, élimine les dépendances de développement.
docker-compose.yml	Production — VIRTUAL_HOST=nibiru-framework.com, joint à réseau nginx-proxy.
docker-compose.local.yml	Remplacement pour test local — expose 4321:4321, supprime les variables d’environnement nginx-proxy.
.dockerignore	Garde node_modules, .git, etc. hors du contexte de construction.
.env.example	Modèle — par défaut, utilise Ollama sur votre Ollama, aucune clé API requise.

Levez-le

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

La première construction exécute build-oracle-index.mjs pour intégrer les documents contre votre Ollama. Les reconstructions ultérieures sont rapides — Docker met en cache la couche des dépendances ; seul les morceaux modifiés ont besoin de re-intégration.

Après environ 30 secondes, jwilder/nginx-proxy détecte le nouveau conteneur, demande un certificat Let’s Encrypt et route https://nibiru-framework.com vers :4321.

Vérifier

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, … }
# }

Ou ouvrez le site dans un navigateur, cliquez sur l’ lanceur d’Oracle jaune et posez une question.

Mise à jour après un changement dans la documentation

git pull
docker compose up -d --build

La construction réexécute l’index Oracle sur le contenu le plus récent ; le nouveau conteneur démarre sur :4321 ; jwilder échange l’amont ; le vieux conteneur est arrêté — aucune interruption notable.

Variables d’environnement

Var	Default	Utilisé à	Objectif
LLM_PROVIDER	ollama	exécution	ollama (par défaut) ou anthropic.
OLLAMA_BASE_URL	https://your-ollama-host.example	build + exécution	Où joindre Ollama.
OLLAMA_CHAT_MODEL	qwen2.5-coder:14b	exécution	Modèle de complétion conversationnelle.
OLLAMA_EMBED_MODEL	nomic-embed-text	build + exécution	Modèle d’embedding.
EMBED_PROVIDER	ollama	build + exécution	ollama ou openai.
ANTHROPIC_API_KEY	—	exécution	Utilisé uniquement si LLM_PROVIDER=anthropic.
ANTHROPIC_MODEL	claude-haiku-4-5-20251001	exécution	Remplacer le modèle Claude.
OPENAI_API_KEY	—	build + exécution	Utilisé uniquement si EMBED_PROVIDER=openai.
ORACLE_TOP_K	6	exécution	Fragments injectés par réponse Oracle.
LETSENCRYPT_EMAIL	stephan.kasdorf@bittomine.com	letsencrypt	Où Let’s Encrypt envoie les notifications d’expiration.
VIRTUAL_HOST	nibiru-framework.com,www.nibiru-framework.com	nginx-proxy	Défini dans compose.

Dépannage

502 Bad Gateway. Le conteneur amont n’a pas réussi à démarrer. Vérifiez docker logs nibiru-docs — probablement un artefact de construction manquant dans dist/server/entry.mjs.

Le certificat n’a pas été émis. Let’s Encrypt limite agressivement les demandes. Vérifiez docker logs letsencrypt-nginx-proxy-companion pour déterminer la cause.

Oracle répond sans références. L’index d’incrustation est vide. Soit nomic-embed-text n’est pas tiré sur Ollama, soit la construction n’a pas pu atteindre your Ollama instance. Ré-tirez le modèle :```bash curl https://your-ollama-host.example/api/pull -d ’{“name”:“nomic-embed-text”}’ docker compose up -d —build

**L'Oracle retourne "l'Oracle ne peut pas répondre".** Vérifiez que le modèle de conversation est chargé :```bash
curl https://your-ollama-host.example/api/tags | jq '.models[].name'

Voulez-vous revenir à Claude ? Définissez LLM_PROVIDER=anthropic et ANTHROPIC_API_KEY dans le fichier .env, puis exécutez docker compose up -d.

Utilisation des ressources

	Inactif	Sous charge Oracle
RAM	environ 120 Mo	environ 200 Mo
CPU	< 0,5 %	environ 5 %
Réseau	minimal	un aller-retour HTTPS par question
Disque	environ 60 Mo d’image + environ 5 Mo d’index	+ exports de corpus

Un serveur gouttelette de 1 Go / 1 vCPU gère confortablement le site de documentation en parallèle avec d’autres services. Le gros du travail (inférence LLM) se fait sur votre cluster GPU, pas dans le conteneur de la documentation.