Saltar a contenido

ADR 022: Despliegue HIVE (Docker / Coolify)

Estado

Aceptado — 2026-07

Relacionado con ADR 001, ADR 009 y ADR 017.

Contexto

Cortex/HIVE se despliega como stack de contenedores: API FastAPI, shell web estático con nginx, PostgreSQL 16 y Redis 7. En producción el orquestador típico es Coolify; en local se usa deploy/docker-compose.yml.

Procedimiento operativo detallado: deploy/COOLIFY.md.

Decisión

Servicio Imagen / build Puerto Rol
api deploy/Dockerfile.api 8000 FastAPI /api/v1, MCP, WS
web deploy/Dockerfile.web 80 (mapeado 5173 en compose) nginx: SPA React + proxy /api → api
postgres postgres:16-alpine 5432 BD cortex (plataforma + tablas booking_*, …)
redis redis:7-alpine 6379 Cache, rate limit, checkpoints LangGraph

Variables críticas: DATABASE_URL, REDIS_URL, JWT_SECRET (producción). Convención sin prefijo vendor; ver Configuración. Los alias CORTEX_* están deprecados (dual-read temporal). La activación de plugins es vía /control/plugins (state store PG), no variables de entorno.

Health checks: GET /api/v1/health, GET /api/v1/ready.

Fuente del diagrama: docs/diagrams/adr/022-despliegue-hive-01.mermaid.

Leyenda: Topología de despliegue Docker/Coolify con proxy nginx y datos compartidos. Actores: usuario, Cloudflare (opcional), Coolify. Estado: Implementado (compose + Coolify doc).

flowchart TB
  subgraph edge [Borde opcional]
    CF[Cloudflare TLS]
  end
  subgraph orchestrator [Orquestador]
    Coolify[Coolify o docker compose]
  end
  subgraph runtime [Contenedores]
    Nginx[nginx web :80]
    API[api FastAPI :8000]
    PG[(PostgreSQL 16)]
    Redis[(Redis 7)]
  end
  User[Usuario browser]
  User --> CF
  CF --> Nginx
  Coolify --> Nginx
  Coolify --> API
  Coolify --> PG
  Coolify --> Redis
  Nginx -->|proxy /api| API
  Nginx -->|SPA static| User
  API --> PG
  API --> Redis

Consecuencias

  • Un solo dominio sirve UI y API; el panel no llama a otro origen en producción.
  • Redis es opcional para desarrollo mínimo pero requerido para NFRs (ADR 009) y ai-agents.
  • Migraciones de plugins con alembic.ini se aplican en setup (deploy/setup-postgres-local.sh).

Referencias