Skip to main content

​
Services

The Docker Compose stack runs 15 containers. Only caddy is exposed externally; all other ports are internal to the Docker network.
ServicePortDescription
caddy80 (configurable)Reverse proxy and TLS termination
api8000REST API and webhook receiver
ui3000Next.js frontend
worker—Workflow orchestrator
executor—Action executor with optional sandbox
agent-worker—AI agent orchestrator
agent-executor—AI agent action executor
mcp8099MCP server for IDE integrations
postgres_db5432Application database (PostgreSQL 16)
temporal7233Workflow engine
temporal_postgres_db5432Temporal database (PostgreSQL 13)
temporal_ui8081 (not exposed)Temporal web UI
minio9000, 9001S3-compatible object storage
redis6379Cache and message broker
migrations—One-shot database migration runner

​
Networking

​
Caddy routing

Caddy is the single entry point for all external traffic. It forwards requests based on path:
PathDestinationPurpose
/api*api:8000REST API
/mcp*mcp:8099MCP server
/.well-known/oauth-*, /authorize*, /token, /register, /consent*, /auth/callback*mcp:8099MCP OAuth flow
/s3/*minio:9000Presigned URL proxy
/*ui:3000Frontend (default)

​
Data flow

The browser connects to Caddy, which proxies to the API or UI. The UI server also calls the API directly via INTERNAL_API_URL for server-side rendering. External systems send webhooks to /api/webhooks/..., which Caddy forwards to the API service. The API submits workflow runs to the Temporal server on port 7233. Workers pull tasks from Temporal’s task queue and dispatch actions to executors. Executors run individual action steps, optionally inside an nsjail sandbox. Agent workers and agent executors follow the same Temporal-based pattern for AI agent workflows.

​
Docker networks

Four networks isolate traffic between service groups:
NetworkScopeServices
coredefaultcaddy, api, ui, worker, executor, agent-worker, agent-executor, mcp, redis, minio, temporal, temporal_ui, migrations
core-dbinternalapi, worker, executor, agent-worker, agent-executor, mcp, migrations, postgres_db
temporaldefaulttemporal, temporal_ui, worker, executor, agent-worker, agent-executor, mcp
temporal-dbinternaltemporal, temporal_postgres_db
Networks marked internal cannot reach the internet, preventing direct external access to databases.

​
OIDC

Set TRACECAT__AUTH_TYPES=oidc in your .env file and configure these variables:
  • OIDC_ISSUER — your identity provider’s issuer URL
  • OIDC_CLIENT_ID — client ID from your identity provider
  • OIDC_CLIENT_SECRET — client secret from your identity provider
Set the callback URI in your identity provider to <your-domain>/auth/oauth/callback. See OIDC configuration for provider-specific setup instructions.

​
SAML

Set TRACECAT__AUTH_TYPES=saml in your .env file and configure SAML_IDP_METADATA_URL with your identity provider’s metadata URL. Supported identity providers: Okta, Microsoft Entra ID, Authentik, and Keycloak. See SAML configuration for provider-specific setup instructions.

​
FAQ

Yes. Update TRACECAT__DB_URI to point to your managed PostgreSQL instance and REDIS_URL for Redis. For Temporal, update the Temporal PostgreSQL credentials in your .env file.See Security for production credential recommendations.
Caddy auto-provisions TLS certificates from Let’s Encrypt when BASE_DOMAIN is set to a real domain. Set PUBLIC_APP_URL to use https:// and expose ports 80 and 443 on the Caddy container.See Configure SSL for production for step-by-step instructions.
Yes. Tracecat has been tested with Amazon S3, MinIO, SeaweedFS, and RustFS.
Point your IDE’s MCP configuration to <PUBLIC_APP_URL>/mcp. Authentication uses a built-in OIDC provider — your agent will be redirected to sign in through the browser on first connection.See Tracecat MCP for IDE-specific setup instructions.