Docker Deployment¶

Deploy AegisAI using Docker Compose — the recommended method for development, staging, and small production deployments.

Prerequisites¶

Docker 24+ with Compose v2
4 GB RAM minimum
Git

Quick Start¶

git clone https://github.com/valera7623/AegisAI.git
cd aegisai
cp .env.example .env
docker compose up --build

Services start on:

Service	URL
Frontend	http://localhost:5173
API	http://localhost:8000
API Docs	http://localhost:8000/docs
OPA	http://localhost:8181

Docker Compose Services¶

The docker-compose.yml defines five services:

PostgreSQL¶

postgres:
  image: postgres:15-alpine
  environment:
    POSTGRES_USER: aegisai
    POSTGRES_PASSWORD: aegisai_pass
    POSTGRES_DB: aegisai
  volumes:
    - postgres_data:/var/lib/postgresql/data
  ports:
    - "5432:5432"

Redis¶

redis:
  image: redis:7-alpine
  ports:
    - "6379:6379"
  volumes:
    - redis_data:/data

OPA¶

opa:
  image: openpolicyagent/opa:0.68.0
  ports:
    - "8181:8181"
  command: ["run", "--server", "--addr", "0.0.0.0:8181"]

Application (FastAPI)¶

app:
  build: .
  ports:
    - "8000:8000"
  depends_on:
    postgres:
      condition: service_healthy
    redis:
      condition: service_healthy
    opa:
      condition: service_started

Startup command:

poetry run alembic upgrade head &&
poetry run python scripts/init_super_admin.py &&
poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Frontend (Vite)¶

frontend:
  build:
    context: ./frontend
  ports:
    - "5173:5173"
  environment:
    VITE_PROXY_TARGET: http://app:8000

Environment Variables¶

Set in docker-compose.yml under app.environment or via .env:

Variable	Default	Description
`DATABASE_URL`	`postgresql+asyncpg://aegisai:aegisai_pass@postgres:5432/aegisai`	DB connection
`REDIS_URL`	`redis://redis:6379/0`	Redis connection
`SECRET_KEY`	`dev-secret-key-change-in-production`	JWT signing
`ADMIN_API_KEY`	`admin-key`	Tenant provisioning
`OPA_ENABLED`	`true`	Enable OPA
`OPA_URL`	`http://opa:8181`	OPA address
`OPA_POLICY_PATH`	`/app/policies/json`	Policy JSON path
`AUDIT_SIGNING_ENABLED`	`true`	Audit HMAC signing
`ENVIRONMENT`	`development`	Environment name
`WEBHOOK_SECRET`	`webhook-secret-key`	Webhook HMAC secret
`SUPER_ADMIN_EMAIL`	`admin@aegisai.com`	Bootstrap admin
`SUPER_ADMIN_PASSWORD`	`admin123`	Bootstrap password
`ENABLE_GUARD`	`true`	Prompt Guard middleware + API
`GUARD_MODEL_PATH`	`./models/guard/guard_model.pkl`	Optional trained ML model

Production Overrides¶

For production, create docker-compose.prod.yml:

services:
  app:
    environment:
      ENVIRONMENT: production
      SECRET_KEY: ${SECRET_KEY}
      ADMIN_API_KEY: ${ADMIN_API_KEY}
      WEBHOOK_SECRET: ${WEBHOOK_SECRET}
      SUPER_ADMIN_PASSWORD: ${SUPER_ADMIN_PASSWORD}
    command: >
      sh -c "poetry run alembic upgrade head &&
             poetry run python scripts/init_super_admin.py &&
             poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4"
    restart: unless-stopped

  frontend:
    command: npm run build && npm run preview -- --host 0.0.0.0 --port 5173
    restart: unless-stopped

  postgres:
    restart: unless-stopped

  redis:
    command: redis-server --appendonly yes
    restart: unless-stopped

  opa:
    restart: unless-stopped

Deploy with:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build

Volume Management¶

Volume	Mount	Purpose
`postgres_data`	`/var/lib/postgresql/data`	Database persistence
`redis_data`	`/data`	Redis persistence
`./app`	`/app/app`	Hot-reload (dev only)
`./policies`	`/app/policies`	Policy templates
`./storage`	`/app/storage`	Export files

Production volumes

Remove source code volume mounts in production. Use built images only.

Common Commands¶

# Start all services
docker compose up -d

# View logs
docker compose logs -f app

# Run migrations
docker compose exec app poetry run alembic upgrade head

# Seed demo data
docker compose exec app poetry run python scripts/seed_data.py --reset

# Database shell
docker compose exec postgres psql -U aegisai -d aegisai

# Restart a single service
docker compose restart app

# Stop all services
docker compose down

# Stop and remove volumes (destructive)
docker compose down -v

Health Verification¶

# Wait for services
docker compose ps

# API health
curl http://localhost:8000/api/v1/health
curl http://localhost:8000/api/v1/health/ready

# OPA health
curl http://localhost:8181/health

# Frontend
curl -s -o /dev/null -w "%{http_code}" http://localhost:5173

Building Images¶

# Build all images
docker compose build

# Build only the app
docker compose build app

# Build with no cache
docker compose build --no-cache

Networking¶

All services communicate on the default Docker Compose network. Internal hostnames:

Hostname	Service
`postgres`	PostgreSQL
`redis`	Redis
`opa`	OPA
`app`	FastAPI
`frontend`	Vite

External access is via published ports only.