Prerequisites
- Terraform 1.7 or later
- AWS credentials configured for your target account and role
- A public Route53 hosted zone (domain and hosted zone ID)
openssland AWS CLI (if using the helper secret script)
Clone the repository
Clone the Tracecat repository and navigate to the Fargate deployment directory.Create core secrets
Tracecat requires four secrets. Generate them withopenssl:
Configure authentication secrets (optional)
Depending on your chosenauth_types (e.g. saml, oidc, oauth), provide the necessary secret ARNs as Terraform variables.
For example, for SAML:
saml_idp_metadata_url_arn
Initialize and deploy
Initialize Terraform and apply the configuration.auth_superadmin_email has no default — if you leave it unset, no one can sign in to the new deployment.
Access Tracecat
Once deployed, access your instance at:- UI:
https://<domain> - API docs:
https://<domain>/api/docs - MCP:
https://<domain>/mcp
First login
Set the first superadmin’s email before anyone signs in. Until it is set, nobody can register, and the first account must match it. It takes one case-sensitive email address, so use the exact casing your identity provider sends.- Basic auth: sign up with that email, then log in.
- SSO: log in through your identity provider. Tracecat creates the account on first login.
Updating Tracecat
To update an existing Tracecat deployment on Fargate: If your stack includes the legacy bundled WAF, follow WAF (legacy) when upgrading.- Pull the latest Fargate stack from the Tracecat repository to ensure you have the most recent infrastructure changes.
- Change the
TF_VAR_tracecat_image_tagvariable to the desired image tag compatible with the stack, or remove the variable to default to the latest image tag. - Run
terraform applyto apply the updates.
WAF (legacy)
Manage AWS WAF rules, ALB associations, event logging, and monitoring through a separate CloudFormation stack or your own security tooling.
Get the ALB ARN with
terraform output -raw alb_arn, then use your security tooling to associate a REGIONAL web ACL in the ALB’s AWS account and region.
Existing deployments keep their WAF when upgrading with Terraform 1.7+ and the bundled waf-handoff.tf.
See the Fargate WAF cleanup guide for migration, manual setup, and troubleshooting.Database login
The migrations init container in the API task runsalembic upgrade head as the stack’s database user on every API task start. Database roles aren’t available on Fargate yet.
Temporal DB SSL enforcement
For the bundled Fargatetemporalio/auto-setup deployment, temporal_db_force_ssl defaults to false:
disable_temporal_autosetup=true and point temporal_cluster_url at your external cluster. In that setup, temporal_db_force_ssl is typically unused because the bundled Temporal RDS instance is not created. If you run your own external Temporal PostgreSQL and want SSL-only enforcement there, set TF_VAR_temporal_db_force_ssl=true.
Database login
The Fargate deployment logs Tracecat in to RDS with a password from Secrets Manager. Database IAM login describes RDS IAM token login, which the Fargate Terraform doesn’t configure yet.AWS role assumption
The executor assumes the role from theAWS_ROLE_ARN key in a workflow’s protected aws or amazon_s3 secret, or from an external secret store, using its ECS task role. By default, executor_deny_same_account_assume_role denies that sts:AssumeRole call for any role in the deployment’s own AWS account. Create your AWS integration roles in a different account.
If you run a single-account install and your integration roles must live in the same account as Tracecat, turn the Deny off:
ExternalId. Keep other roles in that account from trusting either. Cross-account roles are unaffected by this setting; their trust policy, including its ExternalId condition, still applies.
FAQ
Will updating the Fargate stack delete my existing WAF?
Will updating the Fargate stack delete my existing WAF?
A normal apply with the bundled handoff file forgets the legacy WAF state entries while preserving the live ACL and ALB association; no manual
terraform state rm is required. Remove the retired WAF inputs and follow the upgrade and error-recovery instructions before applying.Is untrusted code execution safe on Fargate?
Is untrusted code execution safe on Fargate?
Fargate does not support the permissions model required by
nsjail. Tracecat uses a fallback executor without nsjail isolation on Fargate.
If you need the highest isolation for untrusted code execution (like custom registry actions or core.script.run_python), deploy Tracecat on Kubernetes, where nsjail is enabled by default.What infrastructure does this stack create?
What infrastructure does this stack create?
The Terraform stack deploys:
- Public ALB, Route53 records, and ACM certificates
- ECS cluster with Service Connect
- RDS instances (core database and optional Temporal database)
- ElastiCache Redis
- S3 buckets for attachments, registry, and workflow artifacts
- VPC endpoints for S3 and Secrets Manager
Connecting a VPC-internal LiteLLM, vLLM, or Ollama fails with 'Host is not allowed'
Connecting a VPC-internal LiteLLM, vLLM, or Ollama fails with 'Host is not allowed'
Tracecat rejects LLM provider and MCP endpoints that resolve to private addresses unless you allow them.
Set
outbound_allowed_private_cidrs in your Terraform variables to the endpoint’s IP or CIDR, e.g. "10.0.12.34/32", and apply.
See Private endpoints.What happens if database migrations fail?
What happens if database migrations fail?
Migrations run in an init container during the API task startup. The API container only starts if migrations succeed. If migrations fail, the deployment pauses and dependent services (
worker, executor) will not update.