Saltar a contenido

Deployment Runbook

Estado del runbook

Runbook actualizado a estado post-go-live certificado al 2026-05-31.

  • VPS: GO
  • Publicacion HTTPS: GO
  • Runtime OpenClaw: GO
  • Portainer: GO
  • Certificacion funcional completa: SI

Certificacion final resumida

  • Safe point local:
  • git status -sb -> ## main...origin/main
  • git rev-parse HEAD -> e7c255532e70d4122bb182779838cd49ce0bb4e0
  • VPS:
  • hostname -> srv977009
  • uptime -> up 2 days, 11:24
  • OpenClaw CLI:
  • default model openai/gpt-5.5
  • provider auth OK
  • default agent main
  • health --json -> ok: true
  • Resultado humano:
  • Gabi valido Portainer navegable
  • Gabi valido pairing
  • Gabi valido chat funcional
  • Gabi valido respuesta OpenClaw OK

Topologia actual validada

  • Host: srv977009
  • Stack: /opt/stacks/openclaw
  • Imagen: ghcr.io/openclaw/openclaw:2026.5.5
  • Backend NPM: http://openclaw-gateway:18789
  • Dominio publico: https://openclaw.alpuntodeventa.com.ar/
  • Redes:
  • proxy-network
  • openclaw_openclaw_internal
  • Mounts:
  • /opt/stacks/openclaw/config -> /home/node/.openclaw
  • /opt/stacks/openclaw/workspace -> /home/node/.openclaw/workspace
  • /opt/stacks/openclaw/auth-profile-secrets -> /home/node/.config/openclaw

Evidencia consolidada

Infraestructura

  • uptime -p: up 20 hours, 58 minutes
  • RAM: 7.8 GiB total
  • Swap: 4 GiB activa
  • Disco /: 85G libres
  • docker: active
  • fail2ban: active
  • ufw: active
  • ssh: active

Docker

  • openclaw-openclaw-gateway-1: Up (healthy)
  • nginx-proxy-manager: Up
  • portainer: Up en 2.39.2

Publicacion

  • DNS resuelve a 46.202.151.32
  • HTTPS responde HTTP 200
  • HSTS presente
  • HTML base devuelve titulo OpenClaw Control
  • El gateway no expone 18789 ni 18790 al host por diseno

Recuperacion

  • Reinicio controlado ejecutado el 2026-05-29
  • Shutdown limpio observado por logs
  • Gateway vuelve a ready
  • Estado post-restart: running healthy
  • Auth OpenAI persiste tras restart

Incidentes historicos ya resueltos

  • Faltaba gateway.mode
  • Error de permisos al crear /home/node/.openclaw/logs

Ambos quedaron resueltos el 2026-05-28.

Hallazgos finales

1. Auth OpenAI validada

  • Metodo: api-key interactivo sobre openclaw models auth --agent main login --provider openai --method api-key
  • Resultado:
  • profile openai:default persistido
  • models status muestra profiles=1
  • el agente main responde con openai/gpt-5.5

2. token_missing reclasificado como comportamiento esperado

  • Origen: websocket / Control UI sin token del gateway
  • Evidencia:
  • control-ui-config.json sin token -> 401
  • control-ui-config.json con token -> 200
  • Impacto:
  • protege correctamente la UI
  • no es defecto del runtime ni del provider

3. trustedProxies corregido

  • Causa: NPM inyectaba X-Forwarded-* desde 172.18.0.3 en proxy-network
  • Correccion:
  • gateway.trustedProxies: ["172.18.0.3"]
  • Resultado:
  • reload y restart limpio del gateway
  • warning no reproducido en los accesos proxied finales

4. Portainer modernizado para Docker 29.x

  • Backup nuevo generado:
  • /root/portainer-backups/portainer-data-20260531-001058.tar.gz
  • sha256: b67c05ae7e95a5a7fc93738fdf78d9e950b1146770aebded85273da024c4326d
  • Upgrade aplicado:
  • desde 2.33.1
  • hacia 2.39.2
  • con mismo volumen portainer_data_new
  • con mismos puertos 8000 y 9443
  • con mismo mount /var/run/docker.sock
  • con misma policy unless-stopped
  • con misma red proxy-network
  • Validacion:
  • logs muestran migracion de base 2.33.1 -> 2.39.2
  • docker exec portainer /portainer --version -> 2.39.2
  • curl -k -I https://127.0.0.1:9443 -> HTTP/1.1 200 OK
  • OpenClaw sigue healthy
  • NPM sigue Up

5. Auditoria Docker post-modernizacion

  • Inventario activo final:
  • portainer -> portainer/portainer-ce:2.39.2
  • nginx-proxy-manager -> jc21/nginx-proxy-manager:latest
  • openclaw-openclaw-gateway-1 -> ghcr.io/openclaw/openclaw:2026.5.5
  • Uso real confirmado:
  • Portainer monta portainer_data_new:/data y /var/run/docker.sock
  • NPM monta /docker/nginx-proxy-manager/data y /docker/nginx-proxy-manager/letsencrypt
  • OpenClaw monta /opt/stacks/openclaw/{config,workspace,auth-profile-secrets}
  • Limpieza segura aplicada:
  • docker rmi alpine:latest
  • docker rmi portainer/portainer-ce:latest
  • Legado preservado:
  • volumen portainer_data con portainer.db historica y backup interno
  • red portainer2_default sin contenedores, originada por el Compose previo
  • metadata de stack portainer persistida en portainer_data_new/_data/compose/2/docker-compose.yml

6. Certificacion OpenClaw end-to-end

  • openclaw models status confirma:
  • config activa
  • openai/gpt-5.5 como modelo default
  • auth profile efectivo para OpenAI
  • openclaw health --json confirma:
  • ok: true
  • agente default main
  • sessions.count: 1
  • openclaw doctor --non-interactive deja warnings no bloqueantes:
  • NODE_COMPILE_CACHE ausente
  • OPENCLAW_NO_RESPAWN ausente
  • commands.ownerAllowFrom no configurado
  • plugin registry persistido stale o ausente
  • Smoke tests cerrados:
  • inferencia directa OpenClaw_OK
  • agente main OpenClaw_OK
  • HTTPS publico HTTP/2 200
  • gateway interno desde contenedor HTTP/1.1 200 OK
  • gateway interno desde NPM HTTP/1.1 200 OK
  • Nota operacional:
  • curl -I http://127.0.0.1:18789/ falla en el host y eso es consistente con la politica vigente de no publicar el gateway al host

Smoke checks operativos minimos

  1. Verificar estado del host: ssh openclaw-vps "uptime -p && free -h && swapon --show && df -h /"
  2. Verificar contenedores: ssh openclaw-vps "docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"
  3. Verificar OpenClaw: ssh openclaw-vps "docker inspect openclaw-openclaw-gateway-1 --format '{{.State.Status}} {{.State.Health.Status}}'"
  4. Verificar HTTPS: curl -k -I https://openclaw.alpuntodeventa.com.ar/
  5. Verificar modelo/auth: ssh openclaw-vps "docker exec openclaw-openclaw-gateway-1 sh -lc 'openclaw models status'"
  6. Verificar agente principal: ssh openclaw-vps "docker exec openclaw-openclaw-gateway-1 sh -lc 'openclaw agent --agent main --message \"Respondé solamente: OpenClaw OK\" --json'"
  7. Verificar Control UI protegida: sin token -> 401, con token -> 200 sobre __openclaw/control-ui-config.json
  8. Verificar Portainer: ssh openclaw-vps "docker exec portainer /portainer --version && docker ps --filter name=^/portainer$"

Politica operativa vigente

  • No exponer 18789 ni 18790 al host.
  • No tocar NPM, firewall o DNS salvo evidencia concreta de regresion.
  • No imprimir ni versionar secretos.
  • Mantener a NPM como unico punto de entrada publico.
  • Mantener gateway.trustedProxies alineado al proxy real del stack.

Proximo paso permitido

Formalizar backup/restore del stack, documentar command owner y mover el foco principal hacia casos de uso y automatizaciones.