---
title: "Ejecútalo Localmente"
description: "Tres formas de iniciar el sitio de documentación (con Oracle) en tu propia máquina."
---

El sitio de documentación — y el Oracle que vive en la esquina — es simplemente una aplicación de Astro. Puedes ejecutarlo de tres formas dependiendo de lo que tengas a mano.

## Opción A — Servidor de desarrollo Astro, backend neuronetz.ai (más rápido)

El Oracle llama a tu Ollama compartida en `https://api.neuronetz.ai`. No se necesita un GPU local ni claves de API para gestionar.
```bash
cd /home/stephan/PhpstormProjects/Nibiru/docs

# .env (copy from .env.example, defaults already point at neuronetz.ai)
cp .env.example .env

npm install      # one-time
npm run dev      # http://localhost:4321
```
Abre <http://localhost:4321/>. Haz clic en el lanzador amarillo de Oracle en la esquina inferior derecha y pregunta lo que quieras.

**Extraiga el modelo de incrustación una vez** en su host Ollama (en tiempo de construcción + en tiempo de ejecución):
```bash
curl https://api.neuronetz.ai/api/pull -d '{"name":"nomic-embed-text"}'
```
Sin él, el Oracle sigue funcionando — solo que en modo de chat solamente (sin RAG) y responde basándose en el conocimiento paramétrico del modelo. Con él, las respuestas están respaldadas por esta documentación.

### Construye el índice de embeddings
```bash
npm run build:oracle    # writes public/oracle-index.json
```
El servidor de desarrollo lo detectará en la próxima solicitud. O omite este paso por completo — el punto final de tiempo de ejecución maneja una índice ausente o vacío con gracia.

### Inspecciona la configuración en tiempo de ejecución

El punto final `/api/oracle` del Oracle también responde a GET con su configuración actual (sin secretos):
```bash
curl http://localhost:4321/api/oracle
# {"status":"ok","llm":{"provider":"ollama","ollamaUrl":"https://api.neuronetz.ai",
#  "model":"qwen2.5-coder:14b"},"embed":{...},"index":{...}}
```
## Opción B — Docker Compose, localmente

Más cerca de la producción. Construye la misma imagen que desplegarías.
```bash
cd /home/stephan/PhpstormProjects/Nibiru/docs
cp .env.example .env

docker compose -f docker-compose.yml -f docker-compose.local.yml up --build
```
El `docker-compose.local.yml` override:

- Publica `4321:4321` para que la aplicación sea accesible en <http://localhost:4321/>.
- Elimina las variables de entorno `VIRTUAL_HOST` / `LETSENCRYPT_HOST`.
- No necesita una red `nginx-proxy` en tu máquina de desarrollo.

El primer build tarda 1-2 minutos. Las reconstrucciones posteriores son rápidas (Docker almacena en caché la capa de dependencias).

## Opción C — Totalmente sin conexión, Ollama local

Para desarrollo sin conexión, demostraciones en avión o quemando tu propia GPU.
```bash
# 1) Run Ollama on your laptop
ollama serve &

# 2) Pull a chat model (any of these works)
ollama pull qwen2.5-coder:14b      # 8 GB, recommended
# ollama pull qwen2.5-coder:1.5b   # 1 GB, faster but less accurate
# ollama pull llama3.2:3b          # 2 GB, alternative

# 3) Pull an embedding model
ollama pull nomic-embed-text

# 4) Point the docs at it
cd /home/stephan/PhpstormProjects/Nibiru/docs
cat > .env <<EOF
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_CHAT_MODEL=qwen2.5-coder:14b
OLLAMA_EMBED_MODEL=nomic-embed-text
EOF

npm run build:oracle
npm run dev
```
Ahora `http://localhost:4321/api/oracle` llama a tu portátil Ollama. No se requiere internet.

## Cambiar a Anthropic / OpenAI (si lo deseas)

El Oracle admite API pagadas como alternativa. En `.env`:
```bash
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

EMBED_PROVIDER=openai
OPENAI_API_KEY=sk-...
```
Útil si tu Ollama está caído o para comparar la calidad de las respuestas entre proveedores.

## Hoja de referencia para pruebas de humo
```bash
curl http://localhost:4321/                                    # 301 → /en/
curl -I http://localhost:4321/en/                              # 200
curl http://localhost:4321/api/oracle                          # GET = config
curl -X POST -H 'Content-Type: application/json' \
     -d '{"messages":[{"role":"user","content":"How do I create a module?"}]}' \
     http://localhost:4321/api/oracle | jq .answer
```
Si la última llamada devuelve una respuesta real que menciona `./nibiru -m`, tu pila está configurada correctamente.

## Solución de problemas

**Oracle devuelve "el Oracle no pudo responder".**
El servidor de Ollama no es accesible o el modelo de chat no está extraído. Verifique:```bash
curl https://api.neuronetz.ai/api/tags | jq '.models[].name'
```
**Oracle responde sin citas.**
El índice de incrustación está vacío. Vuelve a ejecutar `npm run build:oracle` después de extraer `nomic-embed-text`.

**Ollama devuelve 404 modelo-no-encontrado.**
Extrae el modelo, por ejemplo:```bash
curl https://api.neuronetz.ai/api/pull -d '{"name":"qwen2.5-coder:14b"}'
```
**`ECONNREFUSED 127.0.0.1:11434`** en la opción C.
El Ollama local no está ejecutándose. Inícielo con `ollama serve &` (o a través de su servicio del sistema).
