Skip to content

How-to: deploy mult-agentes to production

Three supported deploy paths, from simplest to most flexible:

  1. Docker Compose (recommended; turnkey)
  2. systemd on bare metal (when you don't want Docker)
  3. Kubernetes (when you already run K8s)

Path 1 — Docker Compose

Full walkthrough lives in Tutorial 05. Quick reference here:

cd deploy/
# Create .env with ORG_DOMAIN, AUDIT_HMAC_KEY, DASHBOARD_API_KEY
docker compose --profile production up -d
docker compose logs -f dashboard

Path 2 — systemd on bare metal

For environments without Docker (regulated/on-prem):

# 1. Create user + dirs
sudo useradd -r -s /bin/false -d /opt/organismo organismo
sudo mkdir -p /opt/organismo /var/lib/organismo /etc/organismo
sudo chown -R organismo:organismo /opt/organismo /var/lib/organismo
sudo chmod 700 /etc/organismo

# 2. Clone + install
sudo -u organismo bash -c '
  cd /opt/organismo
  git clone https://github.com/claudinoinsights/mult-agentes.git .
  python3 -m venv .venv
  .venv/bin/pip install -e ".[dashboard,observability,llm]"
'

# 3. Environment file
sudo cp deploy/systemd/environment.example /etc/organismo/environment
sudo chmod 600 /etc/organismo/environment
sudo chown organismo:organismo /etc/organismo/environment
sudo vi /etc/organismo/environment   # set AUDIT_HMAC_KEY, DASHBOARD_API_KEY, ...

# 4. Install + enable the service
sudo cp deploy/systemd/organismo-dashboard.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now organismo-dashboard
sudo systemctl status organismo-dashboard

Then put Caddy or nginx in front of it for TLS.

Path 3 — Kubernetes

A starter manifest set lives in deploy/k8s/ (TODO: not in v1.0; coming v1.1). For now, build the Docker image and use any standard K8s deploy pattern:

docker build -f deploy/Dockerfile -t organismo:1.0.0 .
docker tag organismo:1.0.0 your-registry/organismo:1.0.0
docker push your-registry/organismo:1.0.0
# Then deploy with your usual Helm/kustomize/manifests

Key requirements for K8s deploys:

  • FRAMEWORK_DIR mounted on a PersistentVolumeClaim
  • AUDIT_HMAC_KEY in a Secret
  • A LoadBalancer or Ingress with TLS
  • Liveness probe on /healthz, readiness probe on /readyz
  • Resource requests: 256MB RAM, 0.5 CPU minimum (1GB / 1 CPU recommended)

Operational concerns

Secrets

  • AUDIT_HMAC_KEY — generate with openssl rand -hex 32. Losing this means the existing chain becomes unverifiable. Back it up offline.
  • DASHBOARD_API_KEY — protects /api/chat. Rotate quarterly.
  • ANTHROPIC_API_KEY — only needed for headless LLM mode. The bridge flow doesn't need it.

Backups

See backup-and-recover.md. Daily tar.gz + S3 sync recommended. The audit chain HMAC + (optional) S3 Object Lock guarantee detection of tampering even if backups are compromised.

Upgrades

# Path 1 (Docker)
cd /opt/organismo/deploy
git pull
docker compose --profile production up -d --build

# Path 2 (systemd)
sudo systemctl stop organismo-dashboard
sudo -u organismo bash -c 'cd /opt/organismo && git pull && .venv/bin/pip install -e ".[dashboard,observability,llm]" --upgrade'
sudo systemctl start organismo-dashboard

The HMAC chain is forward-compatible: new releases can read chains written by older releases.

Monitoring + alerting

Signal Source Alert if
/healthz returns non-200 uptime monitor Immediate page
Audit chain verify fails recover_chain.py --verify cron Immediate page
Disk > 80% on _framework/ node-exporter Warn at 80%, page at 90%
Backup hasn't run in 36h last-modified on backups/ Page
Coverage drift / test failure CI Block PR merge
Hormone cortisol > 0.7 sustained Prometheus from /metrics Page on-call (something is repeatedly failing)

See also