VOOZH about

URL: https://docs.tracecat.com/self-hosting/docker-compose

⇱ Docker Compose - Tracecat Docs

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

Skip to main content
Docker Compose deployments default to basic email / password authentication. Production deployments should use OIDC or SAML SSO. See Security for additional production hardening recommendations. Tracecat SAML SSO always requires signed assertions and signed responses.

Prerequisites

Core secrets

The env.sh script (next step) generates these automatically. If you need to generate them manually:

Download configuration files

# 1. Download the env.sh installation script
curl -o env.sh https://raw.githubusercontent.com/TracecatHQ/tracecat/1.0.0-beta.48/env.sh

# 2. Download the .env.example template file (env.sh needs this to generate your .env file)
curl -o .env.example https://raw.githubusercontent.com/TracecatHQ/tracecat/1.0.0-beta.48/.env.example

# 3. Make the env.sh script executable and run it
chmod +x env.sh && ./env.sh
After running env.sh, you’ll be prompted to input the following:
  • Set PUBLIC_APP_URL. Defaults to localhost.
  • Require PostgreSQL SSL mode? Defaults to n.
  • Required field: Enter email address for the first user (superadmin).

Download Caddyfile

Tracecat uses Caddy as a reverse proxy. You’ll need to download the following Caddyfile to configure this service. 
curl -o Caddyfile https://raw.githubusercontent.com/TracecatHQ/tracecat/1.0.0-beta.48/Caddyfile

Download Docker Compose file

curl -o docker-compose.yml https://raw.githubusercontent.com/TracecatHQ/tracecat/1.0.0-beta.48/docker-compose.yml

Start Tracecat

Run the command below to start Tracecat and all related services. Make sure your docker-compose.yml and generated .env files are in the same directory. 
docker compose up

Access Tracecat

Once deployed, access your instance at:
  • UI: http://localhost:${PUBLIC_APP_PORT}
  • API docs: http://localhost:${PUBLIC_APP_PORT}/api/docs
  • MCP: http://localhost:${PUBLIC_APP_PORT}/mcp

Updating Tracecat

Be careful when updating Tracecat. Do not accidentally overwrite or lose your existing TRACECAT__SERVICE_KEY, TRACECAT__SIGNING_SECRET, TRACECAT__DB_ENCRYPTION_KEY, and USER_AUTH_SECRET secrets. Losing these secrets will break your credentials and webhooks.
# 1. Download the latest env migration script and env template
curl -o env-migration.sh https://raw.githubusercontent.com/TracecatHQ/tracecat/<version>/env-migration.sh
curl -o .env.example https://raw.githubusercontent.com/TracecatHQ/tracecat/<version>/.env.example

# 2. Make the migration script executable and update your existing .env
chmod +x env-migration.sh && ./env-migration.sh

# 3. Download the latest Docker Compose file
curl -o docker-compose.yml https://raw.githubusercontent.com/TracecatHQ/tracecat/<version>/docker-compose.yml

# 4. Download the latest Caddyfile
curl -o Caddyfile https://raw.githubusercontent.com/TracecatHQ/tracecat/<version>/Caddyfile

# 5. Restart Tracecat with the updated configuration
docker compose up -d
The migration script creates a backup of your existing .env before rewriting it. After the stack starts, verify that your containers are healthy and that you can sign in successfully.

Scaling

Docker Compose runs all services on a single host. These are recommended minimums for different workload sizes.
ResourceSmallStandardProduction
CPU8 cores16 cores32+ cores
RAM16 GB32 GB64+ GB
Storage20 GB SSD50 GB SSD100+ GB SSD
Docker26.0.0+26.0.0+26.0.0+
Workflow starts/sec~5~15~40
Concurrent seats1-1010-5050+
Concurrent agents/sec1-25-1010+
  • Small: Development, testing, small teams (1-10 users)
  • Standard: Mid-size teams (10-50 users), moderate workflow execution
  • Production: Large teams (50+ users), high throughput
Memory is typically the constraining factor. Workflow throughput is lower than dedicated Kubernetes deployments where services have guaranteed resources and can scale independently. For production workloads that exceed single-host capacity, consider converting to Docker Swarm or deploying on Kubernetes.

Convert to Docker Swarm

Docker Swarm lets you scale individual services with resource limits and replicas across one or more nodes.

Service resource recommendations

ServiceCPU (cores)MemoryReplicas
caddy0.25256 Mi1
api24 Gi2
worker22 Gi4
executor48 Gi4
agent-worker22 Gi2
agent-executor416 Gi2
ui0.51 Gi2
mcp11 Gi1
postgres_db24 Gi1
temporal48 Gi1
temporal_postgres_db24 Gi1
redis0.51 Gi1
minio0.51 Gi1
Total~25~52 Gi23
Stateful services (postgres_db, temporal_postgres_db, minio, redis) must remain at 1 replica. Scaling these requires external managed services (e.g., RDS, ElastiCache) or specialized clustering.

Deploy with Docker Swarm

  1. Initialize Swarm:
docker swarm init
  1. Add deploy configuration to each service in your docker-compose.yml. For example, for the api service:
services:
 api:
 # ... existing configuration ...
 deploy:
 replicas: 2
 resources:
 limits:
 cpus: "2"
 memory: 4G
 reservations:
 cpus: "2"
 memory: 4G
  1. Deploy the stack:
docker stack deploy -c docker-compose.yml tracecat
  1. Verify services are running:
docker stack services tracecat

FAQ

For an overview of all services and networking, see Architecture.

Was this page helpful?

Architecture
Previous
AWS ECS Fargate
Next
⌘I
Assistant
Responses are generated using AI and may contain mistakes.