# Deploy to a New WxO Tenant — Cold Start Playbook

Cuando arrancás esta solución en un tenant WxO **completamente nuevo**
(otro cliente, otro environment, fresh start), seguí este playbook
literal. Es el camino más corto desde "tengo credenciales" a "demo
funcionando".

---

## Step 0 — Pre-requisitos

- [ ] IBM Cloud account del cliente con WxO instance provisionada
- [ ] API key del tenant
- [ ] Coolify (u otro host Docker) accesible
- [ ] Dominio público con DNS apuntando al host
- [ ] Acceso a Gitea/repo para clonar el código

---

## Step 1 — Provisionar el ADK localmente

```bash
python3.12 -m venv .venv-wxo
source .venv-wxo/bin/activate
pip install --upgrade "ibm-watsonx-orchestrate==2.1.0"
orchestrate --version    # 2.1.x
```

Verificá que el modelo esté disponible:

```bash
orchestrate env add -n nuevo-tenant \
  --iam-url https://iam.cloud.ibm.com/identity/token \
  -u "$ORCHESTRATE_API_URL"
orchestrate env activate nuevo-tenant

orchestrate models list | grep gpt-oss-120b
```

Si no aparece `gpt-oss-120b`, editá los YAMLs en `wxo/agents/` y poné
`meta-llama/llama-3-3-70b-instruct` (con la advertencia de I-002).

---

## Step 2 — Secretos

Crear `.env` desde `.env.example`:

```bash
cp .env.example .env
nano .env
```

Llenar:
- `ORCHESTRATE_API_URL`
- `ORCHESTRATE_API_KEY`
- `WATSONX_API_KEY` (si vas a usar Plan A)
- `PUBLIC_HOST`
- (Coolify) `COOLIFY_API_URL`, `COOLIFY_API_TOKEN`

---

## Step 3 — Deploy del backend / mocks

Si tu solución incluye un backend propio o mocks:

```bash
# Coolify: crear app desde el git repo, configurar env vars, deploy
# O localmente:
docker compose up -d --build
```

Verificá que el `PUBLIC_HOST/health` responde 200:

```bash
curl -sf "https://$PUBLIC_HOST/health"
```

Si da 503 → Traefik exclude por healthcheck. Issue I-008.
Si da default cert → labels manuales en compose. Issue I-009.

---

## Step 4 — Deploy del stack WxO

```bash
PUBLIC_HOST=mi-cliente.fitlabs.dev ./scripts/deploy-wxo.sh
```

El script:
1. Crea las connections (draft + live)
2. Importa los tools
3. Importa las KBs
4. Importa los agentes en orden (specialists primero)
5. Hace `deploy --env live` de cada uno
6. Crea el canal webchat

Si falla a mitad de camino:
- Re-corré el script (es idempotente)
- Si persiste, ver `docs/known-issues.md`

---

## Step 5 — Capturar IDs

```bash
orchestrate agents list
```

Buscá tu orchestrator en el env `live`, capturá:
- `agent_id` (UUID)
- `environment_id` (UUID)

Ponelos en:
- `web/.../templates/index.html` (o donde esté tu landing): `agentId` y `agentEnvironmentId`
- `.env`: `WXO_AGENT_ID`
- Coolify panel: `WXO_AGENT_ID` env var

Commit + redeploy de la landing.

---

## Step 6 — Embed Security OFF (manual, UI)

**Esto es manual. No hay API.**

1. WxO Console → Settings
2. Embed Security → **Off**
3. Confirmar

Sin esto, el widget de chat queda en "Cargando..." para siempre.
Issue I-007.

---

## Step 7 — Smoke test

```bash
./evals/smoke-test.sh
```

Si pasa, validá manualmente:

```bash
# Abrir el chat
open "https://$PUBLIC_HOST/"
```

Tirale al chat tu primer scenario. Verifica que:
1. El agente responde
2. El tool se llama (mirá `docker logs <web>` para ver las trazas)
3. El resultado final aparece en la UI (kanban / control plane / lo que sea)

---

## Step 8 — Direct backend probe (diagnóstico)

Si el chat funciona pero ves errores, ejecutá:

```bash
./evals/direct-backend-probe.sh
```

Esto llama tu backend directamente con curl + el token de WxO. Sirve
para aislar:
- **200 OK con error de lógica** → el backend está bien, el problema
  está en la conversación con el agente
- **401/403** → problema de auth / connection / credentials
- **502/504** → problema de red entre WxO y tu backend (firewall, DNS,
  Cloud Run cold start, etc.)

---

## Step 9 — Activar Plan A (webhook → Runs API)

Si tu solución tiene auto-trigger desde un sistema externo:

1. Capturá el `WXO_AGENT_ID` (paso 5)
2. Asegurate que `WATSONX_API_KEY` está en `.env`
3. Re-deployá el backend/mocks (`docker compose up -d --force-recreate`)
4. Probá disparando un evento desde el sistema externo
5. Mirá los logs: debería ver `→ POST /v1/orchestrate/runs ... 200`

Issue I-011 si los env vars no se actualizan: `restart` no relee `.env`,
usar `--force-recreate`.

---

## Step 10 — Set up monitoring básico

- Coolify alerta por email si el container reinicia >3 veces en 5 min
- Healthcheck endpoint custom si necesitás
- Logs accesibles desde Coolify panel
- `./evals/smoke-test.sh` corriendo nightly desde CI

---

## Checklist final

- [ ] Step 0 — Pre-reqs listos
- [ ] Step 1 — ADK provisionado + modelo disponible
- [ ] Step 2 — `.env` completo
- [ ] Step 3 — Backend/mocks responden 200 en /health
- [ ] Step 4 — `./scripts/deploy-wxo.sh` sin errores
- [ ] Step 5 — IDs capturados y propagados
- [ ] Step 6 — Embed Security OFF
- [ ] Step 7 — Smoke test pasa
- [ ] Step 8 — Direct probe responde 200
- [ ] Step 9 — (si aplica) Plan A funciona
- [ ] Step 10 — Monitoring básico

Cuando los 10 estén ✅, estás listo para demo.

---

## Si algo se rompió en producción

Ver `docs/RUNBOOK.md` para recovery procedures.