Desplegando el Sitio de Documentación

Esta página documenta cómo se despliega el sitio de documentación en producción. La configuración utiliza jwilder/nginx-proxy para el enrutamiento automático de contenedores Docker, letsencrypt-nginx-proxy-companion para HTTPS y tu propio Ollama en your-ollama-host.example para el backend de Oracle — no se requieren claves API de LLM pagadas.

Topología

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

Requisitos previos en el 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"}'

Archivos en docs/

Archivo	Propósito
Dockerfile	Construcción multi-etapa: construye índice Oracle contra your Ollama instance, construye Astro, elimina dependencias de desarrollo.
docker-compose.yml	Producción — VIRTUAL_HOST=nibiru-framework.com, unido a la red nginx-proxy.
docker-compose.local.yml	Anulación de prueba local — expone 4321:4321, elimina variables de entorno de nginx-proxy.
.dockerignore	Mantiene node_modules, .git, etc. fuera del contexto de la construcción.
.env.example	Plantilla — predeterminado a Ollama en su Ollama, no se requieren claves API.

Levántalo

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

El primer build ejecuta build-oracle-index.mjs para incorporar las documentaciones contra tu Ollama. Las reconstrucciones posteriores son rápidas — Docker almacena en caché la capa de dependencias; solo los bloques modificados necesitan ser reincorporados.

Después de unos 30 segundos, jwilder/nginx-proxy detecta el nuevo contenedor, solicita un certificado de Let’s Encrypt y enruta https://nibiru-framework.com → :4321.

Verificar

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

O bien abre el sitio en un navegador, haz clic en el lanzador amarillo de Oracle y pregunta una pregunta.

Actualización después de un cambio en la documentación

git pull
docker compose up -d --build

La compilación vuelve a ejecutar el índice de Oracle contra el contenido más reciente; el nuevo contenedor se inicia en :4321; jwilder cambia el flujo ascendente; el antiguo contenedor se detiene — sin tiempo de inactividad perceptible.

Variables de entorno

Var	Default	Usado en	Propósito
LLM_PROVIDER	ollama	tiempo de ejecución	ollama (predeterminado) o anthropic.
OLLAMA_BASE_URL	https://your-ollama-host.example	construcción + tiempo de ejecución	Dónde alcanzar a Ollama.
OLLAMA_CHAT_MODEL	qwen2.5-coder:14b	tiempo de ejecución	Modelo de completación de chat.
OLLAMA_EMBED_MODEL	nomic-embed-text	construcción + tiempo de ejecución	Modelo de incrustación.
EMBED_PROVIDER	ollama	construcción + tiempo de ejecución	ollama o openai.
ANTHROPIC_API_KEY	—	tiempo de ejecución	Solo se usa si LLM_PROVIDER=anthropic.
ANTHROPIC_MODEL	claude-haiku-4-5-20251001	tiempo de ejecución	Anula el modelo Claude.
OPENAI_API_KEY	—	construcción + tiempo de ejecución	Solo se usa si EMBED_PROVIDER=openai.
ORACLE_TOP_K	6	tiempo de ejecución	Fragmentos inyectados por respuesta de Oracle.
LETSENCRYPT_EMAIL	stephan.kasdorf@bittomine.com	letsencrypt	Dónde Let’s Encrypt envía las notificaciones de expiración.
VIRTUAL_HOST	nibiru-framework.com,www.nibiru-framework.com	nginx-proxy	Configurado en compose.

Solución de problemas

502 Bad Gateway. El contenedor de nivel superior falló al iniciar. Verifique docker logs nibiru-docs — probablemente falta un artefacto de compilación en dist/server/entry.mjs.

Cert no emitido. Let’s Encrypt limita agresivamente las solicitudes. Verifica los registros de docker logs letsencrypt-nginx-proxy-companion para determinar la causa.

Oracle responde sin citas. El índice de incrustación está vacío. Ya sea que nomic-embed-text no se haya extraído en Ollama, o el build no pudo alcanzar your Ollama instance. Vuelva a extraer el modelo:```bash curl https://your-ollama-host.example/api/pull -d ’{“name”:“nomic-embed-text”}’ docker compose up -d —build

**Oracle devuelve "el Oracle no pudo responder".** Verifica que el modelo de chat esté cargado:```bash
curl https://your-ollama-host.example/api/tags | jq '.models[].name'

Quieres caer en Claude. Establece LLM_PROVIDER=anthropic y ANTHROPIC_API_KEY en .env, luego ejecuta docker compose up -d.

Uso de recursos

	Inactivo	Bajo carga de Oracle
RAM	~120 MB	~200 MB
CPU	< 0.5%	~5%
Red	minimal	un viaje HTTPS por pregunta
Disco	~60 MB imagen + ~5 MB índice	+ exportaciones de corpus

Un droplet de 1 GB / 1 vCPU maneja el sitio de documentación cómodamente junto con otros servicios. El trabajo pesado (inferencia LLM) ocurre en su clúster de GPU, no en el contenedor de documentación.