Compozy Symbol
ALPHA
DocsInstallGetting StartedFeaturesPricing
CoreCLI ReferenceSchema DefinitionAPI Reference
Deployment

Deploying with Docker

Deploy Compozy using our production-ready Docker images with comprehensive environment configuration

Production Prerequisites

Required Managed Services

  • PostgreSQL

    Main database for workflows, agents, and application data
    Recommended providers: AWS RDS, Google Cloud SQL, Azure Database, Neon, Supabase

  • Redis

    Caching, configuration storage, pub/sub messaging, and rate limiting
    Recommended providers: Upstash, AWS ElastiCache, Azure Cache for Redis, Redis Cloud

  • Temporal

    Workflow orchestration engine for reliable task execution
    Recommended provider: Temporal Cloud (managed service)

Available Docker Images

Compozy provides two production-ready Docker images:

  • ghcr.io/compozy/compozy

    Full Compozy server with workflow engine, API server, and Bun runtime for TypeScript tools

  • ghcr.io/compozy/mcp-proxy

    Standalone MCP Proxy server for Model Context Protocol integrations

Local Development with Docker Compose

Start a complete development stack locally:

# Download our development docker-compose.yml
curl -O https://raw.githubusercontent.com/compozy/compozy/main/cluster/docker-compose.yml

# Create a .env file with your configuration
cat > .env << EOF
# AI Provider (choose one)
OPENAI_API_KEY=sk-your-openai-key

# Database passwords
DB_PASSWORD=your_secure_password
TEMPORAL_DB_PASSWORD=your_temporal_password
REDIS_PASSWORD=your_redis_password
EOF

# Start all services
docker-compose up -d

Your Compozy stack will be available at:

Production Deployment with Docker

Running Compozy Server

docker run -d \
  --name compozy-server \
  -p 5001:5001 \
  -e DB_CONN_STRING="postgresql://user:pass@your-managed-postgres:5432/compozy?sslmode=require" \
  -e REDIS_URL="redis://:password@your-managed-redis:6379/0" \
  -e TEMPORAL_HOST_PORT="your-temporal-cloud:7233" \
  -e OPENAI_API_KEY="sk-your-key" \
  ghcr.io/compozy/compozy:latest

With Custom Configuration

Mount your project directory and configuration:

docker run -d \
  --name compozy-server \
  -p 5001:5001 \
  -v $(pwd):/app/project \
  -v $(pwd)/compozy.yaml:/app/config/compozy.yaml \
  -e COMPOZY_CONFIG_FILE=/app/config/compozy.yaml \
  ghcr.io/compozy/compozy:latest

Running MCP Proxy

The MCP Proxy enables integration with external Model Context Protocol servers:

docker run -d \
  --name mcp-proxy \
  -p 6001:6001 \
  -e MCP_PROXY_ADMIN_TOKEN="your-admin-token" \
  -e REDIS_URL="redis://:password@host:6379/0" \
  ghcr.io/compozy/mcp-proxy:latest

Environment Configuration

Core Environment Variables

# Connection string (overrides individual settings)
DB_CONN_STRING="postgresql://user:pass@host:5432/compozy?sslmode=require"

# Or use individual settings
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=compozy
DB_SSL_MODE=require  # disable, require, verify-ca, verify-full

AI Provider Configuration

Configure at least one LLM provider:

# OpenAI
OPENAI_API_KEY=sk-your-openai-key
OPENAI_BASE_URL=https://api.openai.com/v1  # Optional custom endpoint

# Anthropic
ANTHROPIC_API_KEY=sk-ant-your-key

# Groq
GROQ_API_KEY=gsk_your-groq-key

# Ollama (local)
OLLAMA_BASE_URL=http://host.docker.internal:11434

Runtime Configuration

Configure the TypeScript tool execution environment:

# Tool Execution
TOOL_EXECUTION_TIMEOUT=60s
RUNTIME_TYPE=bun
RUNTIME_ENTRYPOINT_PATH=./tools.ts

# Bun Permissions (security sandboxing)
RUNTIME_BUN_PERMISSIONS=["--allow-read","--allow-write=/app/data"]

# System Limits
LIMITS_MAX_NESTING_DEPTH=20
LIMITS_MAX_STRING_LENGTH=10485760
LIMITS_MAX_MESSAGE_CONTENT_LENGTH=10240

Production Best Practices

Container Orchestration

Security Recommendations

Use Secrets Management

Store sensitive environment variables in a secrets manager
# Example with Docker Swarm secrets
echo "your-api-key" | docker secret create openai_key -

docker service create \
  --secret openai_key \
  -e OPENAI_API_KEY_FILE=/run/secrets/openai_key \
  ghcr.io/compozy/compozy:latest

Configure TLS

Enable TLS for all external connections
# PostgreSQL
DB_SSL_MODE=verify-full

# Redis
REDIS_TLS_ENABLED=true

# Server (behind reverse proxy)
SERVER_AUTH_ENABLED=true

Set Resource Limits

Prevent resource exhaustion with Docker limits
docker run -d \
  --memory="2g" \
  --cpus="2" \
  --restart=unless-stopped \
  ghcr.io/compozy/compozy:latest

Health Monitoring

Both images include health checks:

# Check Compozy server health
docker exec compozy-server /usr/local/bin/compozy api health

# View health status
docker ps --format "table {{.Names}}\t{{.Status}}"

Logging Configuration

# Set log level
RUNTIME_LOG_LEVEL=info  # debug, info, warn, error

# View logs
docker logs -f compozy-server

# JSON structured logs for production
docker run -d \
  -e RUNTIME_LOG_LEVEL=info \
  -e RUNTIME_LOG_FORMAT=json \
  ghcr.io/compozy/compozy:latest

Volumes and Data Persistence

The Compozy Docker image defines these volumes:

  • /app/config

    Configuration files including compozy.yaml

  • /app/data

    Application data and file storage

  • /app/tools

    Custom TypeScript tools for your workflows

  • /app/logs

    Application logs (when file logging is enabled)

Mount these volumes for data persistence:

docker run -d \
  -v compozy-config:/app/config \
  -v compozy-data:/app/data \
  -v compozy-tools:/app/tools \
  -v compozy-logs:/app/logs \
  ghcr.io/compozy/compozy:latest

Debugging and Troubleshooting

Interactive Shell Access

# Access the container shell
docker exec -it compozy-server /bin/sh

# Run CLI commands inside the container
docker exec compozy-server compozy workflow list
docker exec compozy-server compozy api health

Common Issues

Environment Variable Debugging

# View all environment variables
docker exec compozy-server env | grep -E '^(DB_|REDIS_|TEMPORAL_)'

# Test database connection
docker exec compozy-server compozy api health --verbose

Next Steps

Kubernetes Deployment
Deploy Compozy on Kubernetes with our Helm chart
Configuration Reference
Complete guide to all configuration options
MCP Integration
Configure Model Context Protocol servers

Event API

The Event API provides programmatic access to Compozy's signal system, enabling external applications, services, and integrations to participate in event-driven workflows. This RESTful API is essential for building complex integrations, webhook handlers, and distributed system coordination with Compozy workflows.

Deploying with Kubernetes

How to deploy your Compozy application with our Kubernetes Helm chart