Saltar a contenido

Docker Architecture

Estado

  • Documento de diseno. Compose conservador local ya preparado, no implementado.
  • No ejecutar cambios en el VPS desde este archivo.

Decision recomendada

  • Recomendacion principal: convivencia controlada en el mismo VPS.
  • Motivo: el host ya tiene Docker, Portainer y Nginx Proxy Manager operativos, y los requerimientos oficiales de OpenClaw para Docker son compatibles con un stack aislado.
  • Condicion: OpenClaw debe vivir como stack propio, con red propia, persistencia propia y sin publicar puertos nuevos a Internet.
  • Escenario para VPS separado mas adelante: si OpenClaw necesitara navegadores simultaneos, sandbox Docker intensivo, modelos locales o integraciones de alto riesgo.

Base oficial considerada

  • La guia Docker de OpenClaw indica Docker Engine o Docker Desktop con Compose v2 y al menos 2 GB RAM para build.
  • La guia Docker de OpenClaw para VPS publico pide revisar seguridad de exposicion y en especial la politica DOCKER-USER.
  • El compose oficial define dos servicios principales: openclaw-gateway y openclaw-cli.
  • El compose oficial publica 18789 y 18790 por defecto.
  • El estado persistente oficial vive en bind mounts hacia /home/node/.openclaw, /home/node/.openclaw/workspace y /home/node/.config/openclaw.
  • La documentacion de VM runtime indica que los binarios extra para skills deben hornearse en una imagen propia y no instalarse dentro del contenedor en runtime.
  • El compose oficial endurece la seguridad con cap_drop y no-new-privileges, y trata a openclaw-cli como frontera de confianza compartida porque usa network_mode: "service:openclaw-gateway".
  • El montaje de docker.sock queda ligado al sandbox y no debe asumirse como obligatorio para el caso inicial.

Arquitectura objetivo multi-app

  • Stack existente: portainer
  • Stack existente: nginx-proxy-manager
  • Stack futuro: openclaw
  • Stacks futuros: una carpeta, una red y una persistencia por aplicacion

Estructura recomendada en el VPS

  • /opt/stacks/shared
  • /opt/stacks/backups
  • /opt/stacks/apps
  • /opt/stacks/openclaw

Regla permanente de estructura

  • Cada aplicacion debe vivir en su propia carpeta bajo /opt/stacks/apps o en una ruta dedicada equivalente.
  • Cada aplicacion debe tener su propio docker-compose.yml.
  • Cada aplicacion debe tener su propio .env real no versionado.
  • Cada aplicacion debe tener volumenes o bind mounts persistentes separados.
  • Cada aplicacion debe tener una red Docker propia.
  • Solo nginx-proxy-manager debe exponer 80 y 443 al exterior.

Layout recomendado para OpenClaw

  • /opt/stacks/openclaw/docker-compose.yml
  • /opt/stacks/openclaw/.env
  • /opt/stacks/openclaw/config/
  • /opt/stacks/openclaw/workspace/
  • /opt/stacks/openclaw/auth-profile-secrets/
  • /opt/stacks/openclaw/images/ si se construye una imagen derivada
  • /opt/stacks/backups/openclaw/

Redes propuestas

  • proxy: red compartida para el reverse proxy. Debe ser la unica red compartida entre apps publicadas.
  • openclaw_internal: red privada del stack OpenClaw.
  • Futuras apps: una red interna dedicada por app, por ejemplo appname_internal.
  • Confirmacion en solo lectura al 2026-05-28: la red Docker real de NPM ya existe como proxy-network y esta en uso por nginx-proxy-manager y portainer.
  • Decision de preparacion local: el compose conservador se conecta a proxy-network como red externa real y mantiene openclaw_internal como red privada propia.

Flujo de red recomendado

  1. Internet llega solo a nginx-proxy-manager por 80/443.
  2. nginx-proxy-manager enruta por Docker hacia el servicio publico de OpenClaw en la red proxy.
  3. Los servicios internos de OpenClaw hablan entre si por openclaw_internal.
  4. Ningun contenedor de OpenClaw publica puertos directos al host en produccion.

Traduccion del compose oficial al VPS compartido

  • Mantener openclaw-gateway como servicio principal.
  • Mantener openclaw-cli solo como sidecar operativo del stack, sin exposicion externa.
  • Reemplazar la publicacion host de 18789 y 18790 por conectividad interna entre NPM y OpenClaw.
  • Mantener los bind mounts persistentes oficiales, pero ubicados dentro de /opt/stacks/openclaw/.
  • Conservar cap_drop y no-new-privileges si la version oficial del compose lo sigue permitiendo al momento de implementar.
  • No activar sandbox con Docker socket en la primera puesta en marcha salvo necesidad validada.

Borrador conceptual de compose

NO EJECUTAR TODAVIA

```yaml services: openclaw-gateway: image: imagen-definida-en-fase-de-implementacion env_file: - .env volumes: - ./config:/home/node/.openclaw - ./workspace:/home/node/.openclaw/workspace - ./auth-profile-secrets:/home/node/.config/openclaw networks: - proxy - openclaw_internal restart: unless-stopped # En produccion detras de NPM no deberia publicar puertos al host. # Si hiciera falta validacion local, se documentara como override temporal.

openclaw-cli: image: imagen-definida-en-fase-de-implementacion network_mode: "service:openclaw-gateway" env_file: - .env volumes: - ./config:/home/node/.openclaw - ./workspace:/home/node/.openclaw/workspace - ./auth-profile-secrets:/home/node/.config/openclaw cap_drop: - NET_RAW - NET_ADMIN security_opt: - no-new-privileges:true

networks: proxy: external: true openclaw_internal: driver: bridge ```

Puertos del host ya ocupados

  • 22/tcp SSH
  • 80/tcp HTTP
  • 443/tcp HTTPS
  • 81/tcp Nginx Proxy Manager admin
  • 8000/tcp Portainer edge o servicio auxiliar actual
  • 9443/tcp Portainer UI

Politica de puertos para OpenClaw

  • No exponer puertos nuevos publicamente salvo necesidad explicita aprobada.
  • Publicar OpenClaw solo detras de Nginx Proxy Manager.
  • Reservar un subdominio dedicado, por ejemplo openclaw.alpuntodeventa.com.ar, o el que el usuario defina.
  • En la preparacion local actual, el compose no publica puertos al host; solo expone 18789 y 18790 dentro de Docker.

Politica de recursos

  • Build: el requisito oficial de al menos 2 GB RAM es compatible con el host actual, pero el margen total del VPS sigue siendo limitado.
  • Runtime inicial: usar proveedores LLM externos.
  • No correr modelos locales pesados en este VPS.
  • Evitar multiples navegadores simultaneos al inicio.
  • Recomendar swap antes de produccion, pero no implementarla en esta fase.

Monitoreo recomendado

  • Revisar uso de CPU, RAM y disco por contenedor.
  • Vigilar crecimiento de workspace, logs y artefactos de plugins.
  • Agregar un chequeo basico de salud del gateway y disponibilidad del subdominio cuando se implemente.
  • Registrar reinicios de contenedores y eventos de OOM.

Regla de convivencia para futuras apps

  • Ninguna app nueva debe compartir volumenes con OpenClaw.
  • Ninguna app nueva debe reutilizar nombres de red de OpenClaw.
  • Cada app debe tener subdominio propio.
  • Cada app debe documentarse antes de instalarse.
  • Cada app debe tener runbook, backup y rollback propios.

Fuentes oficiales

  • https://docs.openclaw.ai/install
  • https://docs.openclaw.ai/install/docker
  • https://docs.openclaw.ai/install/docker-vm-runtime
  • https://github.com/openclaw/openclaw
  • https://github.com/openclaw/openclaw/blob/main/docker-compose.yml

Estado de preparacion local

  • Archivo local preparado: docker/openclaw/docker-compose.yml
  • Archivo local preparado: docker/openclaw/.env.example
  • Archivo local preparado: docker/openclaw/README.md
  • Despliegue real todavia bloqueado hasta revisar compose, confirmar subdominio y aprobar copia al VPS.