Deployment (Admin)¶

This guide provides an administrator's overview of deploying AegisAI to production. For step-by-step instructions, see the Deployment Guide.

Deployment Options¶

Method	Best For	Guide
Docker Compose	Development, staging, small production	Docker
VPS / Bare Metal	Production with custom infrastructure	VPS

Production Architecture¶

flowchart TB
    subgraph Internet
        U[Users]
    end

    subgraph Reverse Proxy
        NG[Nginx / Caddy<br/>TLS termination]
    end

    subgraph Application
        FE[Frontend<br/>static build]
        API[FastAPI :8000]
        WS[WebSocket]
    end

    subgraph Data Layer
        PG[(PostgreSQL)]
        RD[(Redis)]
        OPA[OPA]
    end

    U --> NG
    NG --> FE
    NG --> API
    NG --> WS
    API --> PG & RD & OPA
    WS --> RD

Pre-Deployment Checklist¶

Security¶

[ ] Generate strong SECRET_KEY (256-bit random)
[ ] Change ADMIN_API_KEY from default
[ ] Change WEBHOOK_SECRET from default
[ ] Change SUPER_ADMIN_PASSWORD
[ ] Enable HTTPS with valid TLS certificates
[ ] Restrict CORS to frontend origin
[ ] Set ENVIRONMENT=production

Infrastructure¶

[ ] PostgreSQL 15+ with persistent volume
[ ] Redis 7+ with persistence (AOF or RDB)
[ ] OPA container or sidecar
[ ] Reverse proxy (Nginx, Caddy, Traefik)
[ ] Firewall rules (only 443/80 public)
[ ] DNS configured for API and frontend domains

Operations¶

[ ] Database backup schedule configured
[ ] Health check monitoring set up
[ ] Log aggregation configured
[ ] Run alembic upgrade head on deploy
[ ] Verify OPA policy templates loaded

Environment Variables¶

Variable	Required	Production Value
`DATABASE_URL`	Yes	`postgresql+asyncpg://user:pass@host:5432/aegisai`
`REDIS_URL`	Yes	`redis://host:6379/0`
`SECRET_KEY`	Yes	Random 256-bit string
`ADMIN_API_KEY`	Yes	Strong random key
`OPA_ENABLED`	Yes	`true`
`OPA_URL`	Yes	`http://opa:8181`
`ENVIRONMENT`	Yes	`production`
`LOG_LEVEL`	No	`INFO` or `WARNING`
`AUDIT_SIGNING_ENABLED`	No	`true`
`WEBHOOK_SECRET`	Yes	Strong random key
`SUPER_ADMIN_EMAIL`	Yes	Admin email
`SUPER_ADMIN_PASSWORD`	Yes	Strong password
`SUPER_ADMIN_SYNC_PASSWORD`	No	`true` — sync password from env on container start
`KEYCLOAK_ENABLED`	No	Enable Keycloak SSO
`SIEM_ENABLED`	No	`false` until real SIEM destination is configured

See SSO and SIEM for full variable lists.

Super Admin Sync¶

On each container start, scripts/init_super_admin.py ensures the super-admin account exists and optionally syncs the password from SUPER_ADMIN_PASSWORD:

docker compose exec app poetry run python scripts/init_super_admin.py --force-sync

Set SUPER_ADMIN_SYNC_PASSWORD=false to disable automatic password updates.

Database Migrations¶

Run migrations before starting the application:

# Docker
docker compose exec app poetry run alembic upgrade head

# Bare metal
poetry run alembic upgrade head

Migrations are in migrations/versions/. Always back up the database before running migrations in production.

Frontend Build¶

For production, build the frontend to static assets:

cd frontend
npm install
npm run build

Serve frontend/dist/ via Nginx or mount into the reverse proxy. Configure the API proxy:

location /api/ {
    proxy_pass http://app:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

location /api/v1/ws {
    proxy_pass http://app:8000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Scaling Considerations¶

Component	Scaling Strategy
API	Horizontal — multiple Uvicorn workers behind load balancer
WebSocket	Sticky sessions or Redis pub/sub (built-in)
PostgreSQL	Vertical scaling, read replicas for reporting
Redis	Redis Cluster for high availability
OPA	Sidecar per API instance or shared OPA service

Zero-Downtime Deployment¶

Pull new image / code
Run database migrations
Start new API containers
Health check new instances (/api/v1/health/ready)
Switch traffic via load balancer
Drain old WebSocket connections
Stop old containers