---
title: "Desplegando el Sitio de Documentación"
description: "Despliegue de producción de nibiru-framework.com utilizando jwilder/nginx-proxy y tu propio Ollama en neuronetz.ai."
---

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 api.neuronetz.ai** 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          │ ──────▶ │ api.neuronetz.ai     │
            │ Astro Node SSR :4321 │ HTTPS   │ Ollama (5× GPU)      │
            │ Oracle endpoint      │         │ qwen2.5-coder:14b    │
            └──────────────────────┘         │ nomic-embed-text     │
                                             └──────────────────────┘
```
## Requisitos previos en el host
```bash
# 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 neuronetz.ai (one time)
curl https://api.neuronetz.ai/api/pull -d '{"name":"qwen2.5-coder:14b"}'
curl https://api.neuronetz.ai/api/pull -d '{"name":"nomic-embed-text"}'
```
## Archivos en `docs/`

| Archivo | Propósito |
|---|---|
| `Dockerfile` | Construcción multi-etapa: construye índice Oracle contra neuronetz.ai, 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 neuronetz.ai, no se requieren claves API. |

## Levántalo
```bash
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
```bash
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
```bash
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://api.neuronetz.ai` | 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 neuronetz.ai. Vuelva a extraer el modelo:```bash
curl https://api.neuronetz.ai/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://api.neuronetz.ai/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.
