Skip to main content
This stack exposes Tracecat to the public internet. We’ve set the auth_types Terraform variable to saml by default. You must configure SAML before your first login or change auth_types to another method. See Security for additional production hardening recommendations.

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)
  • openssl and 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 with openssl:
Store these securely. Losing TRACECAT__DB_ENCRYPTION_KEY makes encrypted credentials unrecoverable. Losing TRACECAT__SIGNING_SECRET invalidates existing webhook URLs and agent channel endpoint URLs.
See Where to store them for the recommended storage on each deployment target, and which of these secrets can be rotated. You can create these in AWS Secrets Manager manually or use the helper script:
Save the resulting secret ARNs. You’ll need them for Terraform variables.

Configure authentication secrets (optional)

Depending on your chosen auth_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.
Provisioning takes about 10-20 minutes due to RDS and ECS startup.

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.
The account becomes superadmin and owner of the default organization.

Updating Tracecat

To update an existing Tracecat deployment on Fargate: If your stack includes the legacy bundled WAF, follow WAF (legacy) when upgrading.
  1. Pull the latest Fargate stack from the Tracecat repository to ensure you have the most recent infrastructure changes.
  2. Change the TF_VAR_tracecat_image_tag variable to the desired image tag compatible with the stack, or remove the variable to default to the latest image tag.
  3. Run terraform apply to 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 runs alembic 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 Fargate temporalio/auto-setup deployment, temporal_db_force_ssl defaults to false:
This setting applies only to the bundled Temporal RDS instance. It requires a DB reboot when changed and permits non-TLS connections to the Temporal database for compatibility with the current Fargate Temporal auto-setup flow. If you are using Temporal Cloud or another external Temporal cluster, set 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 the AWS_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:
With the Deny off, every workspace user can assume any role in that account whose trust policy names the account root or the executor task role and doesn’t require a different 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

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.
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.
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
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.
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.