Skip to main content

Deploy Self-hosted Retool on AWS Fargate and ECS with Terraform

Learn how to deploy Retool on AWS Fargate and ECS with Terraform.

You can deploy Self-hosted Retool on ECS Fargate and EC2 with a Terraform module.

Requirements​

To deploy Self-hosted Retool on AWS Fargate and ECS, you need:

Retool recommends using the Retool-provided Terraform module for ECS deployments.

Temporal​

Temporal is a distributed system used to schedule and run asynchronous tasks for Retool Workflows. A Self-hosted Retool instance uses a Temporal cluster to facilitate the execution of each workflow amongst a pool of self-hosted workers that make queries and execute code in your VPC. Temporal manages the queueing, scheduling, and orchestration of workflows to guarantee that each workflow block executes in the correct order of the control flow. It does not store any block results by default.

You can use a Retool-managed cluster on Temporal Cloud, which is recommended for most use cases. You can also use an existing self-managed cluster that is hosted on Temporal Cloud or in your own infrastructure. Alternatively, you can spin up a new self-hosted cluster alongside your Self-hosted Retool instance.

Recommended

You should use a Retool-managed cluster if:

  • You are on a version greater than 3.6.14.
  • Your organization is on the Enterprise plan.
  • You don't have an existing cluster which you prefer to use.
  • Your cluster only needs to be used for a Self-hosted Retool deployment.
  • You don't want to manage the cluster directly.
  • You have a single or multi-instance Retool deployment, where each instance requires its own namespace.

Retool admins can enable Retool-managed Temporal. To get started, navigate to the Retool Workflows page and click Enroll now. Once you update your configuration, return to the page and click Complete setup.

It can take a few minutes to initialize a namespace in Retool-managed Temporal.

Retool-managed Temporal clusters are hosted on Temporal Cloud. Your Self-hosted Retool deployment communicates with the cluster when building, deploying, and executing Retool Workflows. All orchestration data to Temporal is fully encrypted and uses the private encryption key set for your deployment.

1. Update Terraform configuration​

A Retool-managed Temporal cluster requires v3.6.15 or later.

First, update your Terraform configuration to directly use the module. Next, set ecs_retool_image to the Docker tag for the version of Retool to install, such as tryretool/backend:3.75.3-stable.

Specify the exact version to use, such as 3.75.3-stable. This ensures you know exactly which version will be deployed.

If you are not using Fargate, set launch_type to EC2. Retool recommends t3.large instances for EC2-backed ECS as this avoids Elastic Network Interface (ENI) limits since each ECS Service requires an ENI.

Ensure that workflows_enabled=true.

Terraform configuration
module "retool" {
  source = "git@github.com:tryretool/terraform-retool-modules.git//modules/aws_ecs"

  aws_region = "<your-aws-region>"
  vpc_id = "<your-vpc-id>"
  subnet_ids = [
      "<your-subnet-1>",
      "<your-subnet-2>"
  ]
  ssh_key_name = "<your-key-pair>"
  retool_license_key = "<your-retool-license-key>"
  ecs_retool_image = "<desired-retool-version>"
  launch_type = "FARGATE" | "EC2"
  workflows_enabled = true
  ...
}

Allow your deployment to connect to Temporal​

Open up egress to the public internet on ports 443 and 7233 to allow outbound-only connections to Temporal Cloud from your deployment. This is so services can enqueue work to, and poll work out, of Temporal.

Temporal Cloud does not have a static IP range to allow list. If more specificity is required, egress is required on ports on the following domains:

PortDomains
443*.retool.com, *.tryretool.com, *.temporal.io
7233*.tmprl.cloud

Configure Terraform for Temporal​

Update your Terraform configuration to configure Temporal:

module "retool" {
  ...
  workflows_enabled = true
  use_existing_temporal_cluster = true
  // temporal_cluster_config = <config-for-your-own-temporal>
  ...
}

Set encryption key​

Self-hosted Retool deployments use an encryption key to encrypt:

  • Private keys in the PostgreSQL database of the Self-hosted Retool instance.
  • All data stored in Temporal when deploying Self-hosted Retool.

Set the ENCRYPTION_KEY environment variable for your deployment.

2. Install module requirements​

Run terraform init to install all requirements for the module.

3. Verify security settings additional input variables​

Ensure that the default security settings in security.tf matches your specifications. If you need to restrict access further, you can configure ingress and egress rules into container_egress_rules, container_ingress_rules, alb_egress_rules, and alb_ingress_rules.

Check variables.tf for any other input variables that may be required.

4. Review and apply changes​

Run terraform plan to view all planned changes to your account. Once complete, run terraform apply to apply the changes and deploy Self-hosted Retool.

A load balancer is then associated with the deployment and available in the AWS EC2 Console. The instance address should now be running Self-hosted Retool.