Tutorial 05 — Deploy to production¶

This walks through deploying the mult-agentes dashboard to a real server with TLS, persistence, federation, observability, and backups.

Prerequisites¶

Linux server with Docker + docker-compose installed
A domain name (e.g. organismo.example.com) pointing at the server's IP
Ports 80 and 443 open
Completed tutorials 01-04

Step 1 — Clone + configure¶

On the server:

git clone https://github.com/claudinoinsights/mult-agentes.git
cd mult-agentes/deploy

# Create the environment file
cat > .env <<'EOF'
ORG_DOMAIN=organismo.example.com
AUDIT_HMAC_KEY=GENERATE_WITH_openssl_rand_hex_32
DASHBOARD_API_KEY=GENERATE_WITH_openssl_rand_hex_24
EOF

# Generate real secrets
openssl rand -hex 32   # paste as AUDIT_HMAC_KEY
openssl rand -hex 24   # paste as DASHBOARD_API_KEY

Step 2 — Boot the stack¶

cd deploy/
docker compose --profile production up -d

Services started:

Service	Port	Purpose
`caddy`	80, 443	Reverse proxy + auto-TLS via Let's Encrypt
`dashboard`	8000 (internal)	FastAPI backend
`redis`	6379 (internal)	Federation pub/sub for multi-node
`otel-collector`	4317, 4318 (internal)	Receives traces/metrics
`jaeger`	16686	Trace UI (proxy externally if needed)

Caddy will request a Let's Encrypt cert on first request to your domain.

Verify:

curl https://organismo.example.com/healthz
# → {"status": "healthy", "version": "1.2.0"}

Step 3 — Verify TLS + security headers¶

curl -I https://organismo.example.com/
# Expect:
#   strict-transport-security: max-age=31536000; includeSubDomains; preload
#   x-content-type-options: nosniff
#   x-frame-options: SAMEORIGIN

Step 4 — Set up backups¶

Add to crontab (crontab -e):

0 2 * * * docker exec organismo-dashboard python scripts/backup_framework.py \
  --source /data --output /data/backups --gzip --retention-days 30 \
  >> /var/log/organismo-backup.log 2>&1

For off-host durability, sync backups to S3:

# Example: aws s3 sync /var/lib/docker/volumes/deploy_framework-data/_data/backups \
#   s3://my-org-backups/organismo/

Step 5 — Enable S3 Object Lock on the audit chain¶

If you have an S3 bucket with Object Lock enabled, edit your stack to wire it:

# Custom dashboard launcher (mount as /app/launcher.py):
from src.dashboard import create_app
from src.privacy import AuditChain, ObjectLockImmutability
from src.bridge import Recorder

backend = ObjectLockImmutability(
    bucket="my-audit-bucket",
    region="us-east-1",
    retention_days=2555,   # 7 years for compliance
)
rec = Recorder.singleton(framework_dir="/data")
rec.audit_chain.immutability = backend

app = create_app(framework_dir="/data")

Add IAM credentials to your .env:

AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=us-east-1

Every audit chain append now uploads to S3 with COMPLIANCE retention.

Step 6 — Monitor¶

Health: Caddy proxies /healthz and /readyz. Hook into Uptime Robot or similar.
Traces: Jaeger at http://your-server:16686 (firewall it or proxy behind Caddy with auth).
Metrics: Prometheus scrape endpoint at http://your-server:8889/metrics (from the OTel collector).
Logs: docker compose logs -f dashboard caddy

Step 7 — Scale out (optional)¶

For multi-node federation, deploy another server with the same Docker stack pointing at the same Redis instance:

# In the new node's docker-compose.yml override
services:
  dashboard:
    environment:
      REDIS_URL: redis://NODE_1_IP:6379/0   # Shared Redis
      FEDERATION_NODE_ID: node-east-2

Both dashboards now exchange events via Redis. Each writes its own audit chain locally; periodic backups should preserve both.

Failure scenarios¶

Failure	Recovery
Disk full	Free space, restart dashboard. `_framework/` auto-cleans capsules >90d
Postgres-style corruption (events.jsonl truncated)	`python scripts/recover_chain.py --rebuild capsules`
Caddy can't issue cert	Check DNS A record + port 80 reachable for ACME http-01
Audit chain tamper detected	Restore latest backup; the chain HMAC tells you which line first failed

See Backup and recover for procedures.

What you just deployed¶

A production-grade Organismo instance with: - TLS-fronted dashboard - HMAC-chained audit log - Daily backups with 30-day retention - Redis-backed federation (ready to scale out) - OpenTelemetry traces + metrics - Optional S3 Object Lock for compliance