Skip to main content
This stack supports Tracecat >1.0.0-beta.xx and is not backward compatible with pre-1.0 executor modes. Default auth_types is saml, so configure SAML before first login.

​
⚠️ Critical security requirement for code execution

If you run untrusted or third-party code in production, you must enable nsjail.This includes both:
  • core.script.run_python actions
  • Custom registry actions that execute code pulled from third-party sources
AWS Fargate deployments have nsjail disabled by default. In that mode, script execution falls back to unsafe_pid_executor subprocess isolation.unsafe_pid_executor uses PID namespace isolation only when unshare --pid is permitted. On Fargate this is typically unavailable, so scripts generally run without PID namespace isolation.Additionally, in fallback mode allow_network is not OS-enforced and should be treated as best-effort only.Fargate does not provide the required permissions model for nsjail. For production workloads that execute untrusted code, we still recommend Kubernetes (Helm chart), where nsjail is enabled by default.For comparison: Helm chart / Kubernetes deployments have nsjail enabled by default.

​
Prerequisites

  • Terraform
  • AWS credentials configured for your target account/role
  • A public Route53 hosted zone (domain + hosted zone ID)
  • openssl and AWS CLI (if using the helper secret script)
The stack deploys a public ALB with private ECS/RDS/Redis networking and creates three blob buckets: attachments, registry, and workflow artifacts.

​
Instructions

1

Open the Terraform stack

Use the Terraform stack in this repository. If you’re following this guide from the docs site, open the deployment folder first so you can see the expected files:Then clone the repo (if you haven’t already) and change into that directory locally:
git clone https://github.com/TracecatHQ/tracecat.git
cd tracecat
cd deployments/fargate
2

Create core Tracecat secrets

Create required secrets (TRACECAT__DB_ENCRYPTION_KEY, TRACECAT__SERVICE_KEY, TRACECAT__SIGNING_SECRET):
export AWS_DEFAULT_REGION=<aws-region>
./scripts/create-aws-secrets.sh
Keep the resulting secret ARNs for Terraform variables.
3

Configure auth secrets (optional)

Depending on your auth mode, optionally provide:
  • OAuth: oauth_client_id_arn, oauth_client_secret_arn
  • OIDC: oidc_issuer, oidc_scopes, oidc_client_id_arn, oidc_client_secret_arn
  • SAML: saml_idp_metadata_url_arn, saml_ca_certs_arn, saml_metadata_cert_arn
  • User auth tokens: user_auth_secret_arn
4

Initialize and deploy

terraform init

export TF_VAR_aws_region=<aws-region>
export TF_VAR_domain_name=<domain>
export TF_VAR_hosted_zone_id=<hosted-zone-id>

export TF_VAR_tracecat_db_encryption_key_arn=<secret-arn>
export TF_VAR_tracecat_service_key_arn=<secret-arn>
export TF_VAR_tracecat_signing_secret_arn=<secret-arn>

# Optional but recommended
export TF_VAR_tracecat_image_tag=1.0.0-beta.6

terraform apply
Provisioning may take ~10-20 minutes due to RDS and ECS startup.
5

Access Tracecat

  • App: https://<domain>
  • API docs: https://<domain>/api/docs

​
Deployment behavior

  • Migrations run in an init container in the API task definition.
  • API container startup is gated on migration success.
  • If migrations fail, API deployment does not stabilize and dependent service updates are blocked by Terraform dependency ordering.

​
Reference