MundiX - Production Quickstart¶

Time to deploy: 15 minutes
Prerequisites: Docker, Docker Compose, Domain DNS

1. Clone and Configure (5 min)¶

# Navigate to MundiX
cd /opt/mundix

# Copy environment template
cp infra/agents/.env.example infra/agents/.env

# Generate strong secret key
python3 -c "import secrets; print(secrets.token_urlsafe(64))"
# Copy output and paste into .env as ORCHESTRATOR_API_SECRET_KEY

# Edit configuration
nano infra/agents/.env

Required changes in .env:

# Database (update password)
REGISTRY_POSTGRES_URL=postgresql://mundix:CHANGE_THIS_PASSWORD@postgres:5432/agent_registry

# Redis (update password)
REDIS_URL=redis://:CHANGE_THIS_PASSWORD@redis:6379/0

# API Secret (paste generated key)
ORCHESTRATOR_API_SECRET_KEY=<your-64-char-key-here>

# Matrix (if using)
MATRIX_HOMESERVER_URL=https://matrix.capivaraonline.com
MATRIX_BOT_ACCESS_TOKEN=<your-matrix-bot-token>
MATRIX_ROOM_ID=!your-room-id:capivaraonline.com

2. Build and Start (3 min)¶

# Build all services
docker-compose -f infra/agents/docker-compose.yml build

# Start services
docker-compose -f infra/agents/docker-compose.yml up -d

# Check status
docker-compose -f infra/agents/docker-compose.yml ps

Expected output:

NAME                        STATUS      PORTS
mundix-orchestrator-api     Up          0.0.0.0:8001->8001/tcp
mundix-orchestrator-worker  Up          
mundix-postgres             Up          5432/tcp
mundix-redis                Up          6379/tcp

3. Verify Services (2 min)¶

# Check API health
curl http://localhost:8001/

# Check database
docker logs mundix-orchestrator-api | grep "database_initialized"

# Check rate limiter
docker logs mundix-orchestrator-api | grep "rate_limiter_initialized"

# Check worker + cleanup job
docker logs mundix-orchestrator-worker | grep "worker_starting_with_cleanup"

4. Create Admin User (2 min)¶

curl -X POST http://localhost:8001/auth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "admin",
    "email": "admin@mundix.local",
    "password": "Admin123!ChangeMe",
    "is_admin": true
  }'

Expected response:

{
  "id": 1,
  "username": "admin",
  "email": "admin@mundix.local",
  "is_active": true,
  "is_admin": true,
  "created_at": "2026-02-03T19:00:00"
}

5. Test Authentication (3 min)¶

# Login
curl -X POST http://localhost:8001/auth/login \
  -d "username=admin&password=Admin123!ChangeMe"

# Save tokens from response
export ACCESS_TOKEN="<access_token_from_response>"
export REFRESH_TOKEN="<refresh_token_from_response>"

# Test protected endpoint
curl http://localhost:8001/auth/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Test refresh
curl -X POST http://localhost:8001/auth/refresh \
  -H 'Content-Type: application/json' \
  -d "{\"refresh_token\": \"$REFRESH_TOKEN\"}"

# Test logout
curl -X POST http://localhost:8001/auth/logout \
  -H 'Content-Type: application/json' \
  -d "{\"refresh_token\": \"$REFRESH_TOKEN\"}"

6. Run Tests (Optional, 3 min)¶

# Run full test suite
./run_tests.sh

# Expected: ✅ All 27 tests passed!

Production Checklist¶

Before going live:

Security¶

DNS¶

matrix.capivaraonline.com → Server IP
mundix.capivaraonline.com → Server IP
api.mundix.capivaraonline.com → Server IP (optional)

Monitoring¶

Logs aggregation configured
Alerts set up:
Redis down
Postgres down
High 429 rate
Token table growth
Backup schedule configured

Performance¶

Rate limits reviewed and adjusted
Redis persistence enabled
Postgres backups configured
Resource limits set (Docker)

Common Issues¶

Issue: Port 8001 already in use¶

# Find process
lsof -i :8001

# Change port in docker-compose.yml
ports:
  - "8002:8001"  # External:Internal

Issue: Database connection refused¶

# Check Postgres
docker logs mundix-postgres

# Recreate database
docker-compose -f infra/agents/docker-compose.yml down
docker volume rm mundix_postgres-data
docker-compose -f infra/agents/docker-compose.yml up -d

Issue: Redis connection error¶

# Check Redis
docker exec mundix-redis redis-cli ping
# Should return: PONG

# Check password in .env
cat infra/agents/.env | grep REDIS_URL

Monitoring Commands¶

# View API logs
docker logs -f mundix-orchestrator-api

# View worker logs
docker logs -f mundix-orchestrator-worker

# Check rate limiting
docker exec mundix-redis redis-cli KEYS "rl:*"

# Check token table
docker exec mundix-postgres psql -U mundix -d agent_registry -c \
  "SELECT COUNT(*) FROM refresh_tokens;"

# Monitor 429 errors
docker logs mundix-orchestrator-api 2>&1 | grep -c "rate_limit_exceeded"

Backup & Restore¶

Backup¶

# Database
docker exec mundix-postgres pg_dump -U mundix agent_registry > mundix_backup_$(date +%Y%m%d).sql

# Redis (if needed)
docker exec mundix-redis redis-cli SAVE
docker cp mundix-redis:/data/dump.rdb redis_backup_$(date +%Y%m%d).rdb

Restore¶

# Database
cat mundix_backup_20260203.sql | docker exec -i mundix-postgres psql -U mundix agent_registry

# Redis
docker cp redis_backup_20260203.rdb mundix-redis:/data/dump.rdb
docker restart mundix-redis

Scaling¶

Vertical Scaling (Single Server)¶

# docker-compose.yml
services:
  orchestrator-api:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G

Horizontal Scaling (Multiple Servers)¶

Deploy Redis Cluster (HA)
Deploy Postgres with read replicas
Run multiple API instances behind load balancer
Share session state via Redis

Support¶

Documentation¶

Full docs: /opt/mundix/docs/
API reference: docs/auth.md
Architecture: docs/ADR-001-auth.md
Tests: TEST_INSTRUCTIONS.md

Troubleshooting¶

Check logs: docker-compose logs
Verify env vars: docker-compose config
Test connectivity: docker-compose exec orchestrator-api ping postgres
Review RUNBOOK: docs/RUNBOOK.md

Ready to deploy! 🚀

For production deployment to capivaraonline.com, follow the DNS and SSL/TLS setup in docs/DEPLOYMENT.md.