This stack is meant for production use. TRACECAT__AUTH_TYPES=google_oauth,saml is the default configuration. You’ll need to configure Google OAuth or SAML SSO to login.

​
Prerequisites

The open source Terraform stack deploys Tracecat into AWS with a public facing application load balancer (ALB) and public hosted zone.

Internal services (e.g. API, worker, databases) are segregrated via private security groups. If your security model requires an internal facing ALB and private hosted zone, please reach out to founders@tracecat.com for help!

  • Terraform
  • curl, openssl, docker to create cryptographic keys used in the Tracecat app
  • AWS credentials. View AWS Provider docs for details.
  • A public Route53 hosted zone (save the hosted zone’s domain name and ID)
  • To create secrets in Secrets Manager, either:

​
Instructions

1

Download Terraform stack

Download installation files from the Tracecat GitHub repo: https://github.com/TracecatHQ/tracecat/tree/main/deployments/aws

2

Create encryption secrets for Tracecat

Tracecat relies on three symmetric encryption keys (TRACECAT__DB_ENCRYPTION_KEY, TRACECAT__SERVICE_KEY, TRACECAT__SIGNING_SECRET) to sign and encrypt secrets within the application.

The service key and signing secret are random 32-byte hexadecial strings generated by the openssl CLI tool. The database encryption key is created using the cryptography Python library, which is run in Docker.

Download and execute the secrets creation bash script.

curl -o create-aws-secrets.sh https://raw.githubusercontent.com/TracecatHQ/tracecat/main/deployments/aws/scripts/create-aws-secrets.sh
chmod +x create-aws-secrets.sh && ./create-aws-secrets.sh

View create-aws-secrets.sh file on GitHub for details if you want to run this step manually.

3

Retrieve secret ARNs

Store the ARNs of the three created secrets in a secure place. You will need these ARNs to pass into the Terraform stack as variables.

You can find the ARNs in the web console:

4

Configure Google OAuth or SAML SSO

The Terraform stack has two Google OAuth variables or four SAML SSO variables that need to be configured to setup Google OAuth or SAML SSO. The variables are:

  • oauth_client_id_arn
  • oauth_client_secret_arn
  • saml_idp_entity_id_arn
  • saml_idp_redirect_url_arn
  • saml_idp_certificate_arn
  • saml_idp_metadata_url_arn

These variables are the ARNs of the AWS Secrets Manager secrets that contain the Google OAuth or SAML SSO configuration. Create the secrets in AWS Secrets Manager and take note of the ARNs.

5

Deploy stack

Initialize Terraform and deploy the stack by running the following commands:

# Initialize Terraform directory
terraform init

# (Optional) Set Terraform variables via env vars
export TF_VAR_domain_name=<your-hosted-zone-domain-name>
export TF_VAR_hosted_zone_id=<your-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>

# Either: Set Google OAuth variables
export TF_VAR_oauth_client_id_arn=<secret-arn>
export TF_VAR_oauth_client_secret_arn=<secret-arn>

# Or: Set SAML SSO variables
export TF_VAR_saml_idp_entity_id_arn=<secret-arn>
export TF_VAR_saml_idp_redirect_url_arn=<secret-arn>
export TF_VAR_saml_idp_certificate_arn=<secret-arn>
export TF_VAR_saml_idp_metadata_url_arn=<secret-arn>

# Create Terraform stack
terraform apply

Wait for the Terraform stack to deploy. This can take up to 10 minutes as spinning up new RDS databases can be slow.

You can configure the Tracecat Fargate deployment via Terraform variables. View available configs in the variables.tf file on GitHub.

6

Access Tracecat UI

Access the Tracecat UI via https://<your-hosted-zone-domain-name>. You can also view Tracecat’s API docs via https://<your-hosted-zone-domain-name>/api/docs.

​
Login

The first user that logs in via Google OAuth or SAML SSO will be created with default admin privileges.

​
Next Steps

Docker ComposeIntroduction