Deploy Retool with EC2

Follow the instructions in this guide to deploy self-hosted Retool on AWS EC2.

Requirements

To deploy Retool on EC2, you need:

• A Retool license key, which you can obtain from my.retool.com or your Retool account manager.
• Some familiarity with AWS and Amazon EC2.
• An AWS account.
• An SSH key to connect to the instance via SSH.

In addition, Retool recommends you:

• Follow this guide using an administrative, non-Root AWS user.
• Manage your service quotas for your Retool deployment's AWS Region as you scale.

System architecture

The following diagram shows the resulting system architecture for your deployment.

1. Create an EC2 instance

In the EC2 dashboard:

1. Launch a new instance. Name the instance, and optionally add tags.

2. Select an AMI. Refer to Retool's storage requirements to see supported operating systems and select an instance that fits your needs. At a minimum, use the quickstart's Ubuntu 22.04 LTS AMI with an x86 architecture and a t3.large instance type.

3. Create or select an SSH key pair.

4. In network settings, create or use an existing security group with the following inbound rules.

By default, Retool runs on port 3000. The user's browser connects using a web server on port 80 (HTTP) and port 443 (HTTPS). After SSL is configured, access to port 3000 is no longer required.

5. For storage, configure the root volume to have at least 60GiB of general purpose SSD capacity.

6. Review the summary and launch.

2. Install Retool

1. Connect to your instance. You can connect in the AWS console using EC2 Instance Connect, or on the command line using an SSH client, with the SSH key pair you selected in your EC2 dashboard.

2. After connecting, clone the retool-on-premise repository and change your working directory to retool.

git clone https://github.com/tryretool/retool-onpremise.git retool
cd retool

3. Run the install script to create a docker.env file.

./install.sh

3. Update environment variables

On Docker deployments, environment variables are set in docker.env.

1. In docker.env, set LICENSE_KEY to your license key.

2. In docker.env, uncomment the COOKIE_INSECURE=true line. After you set up SSL, you should set COOKIE_INSECURE to false.

3. Copy the ENCRYPTION_KEY in docker.env generated by the install script. Save this key in a secure location outside of Retool. This key encrypts secrets for your Retool resources.

4. Set the version and start Retool

1. In your Dockerfile, replace X.Y.Z with a Retool version tag, for example 2.116.3. Identify the appropriate release version by viewing the tags on Docker Hub. See Retool's self-hosted release notes to learn about version-specific features.

2. Start Retool. It may take a few minutes to pull the images and start each service.

sudo docker-compose up -d

3. Confirm the containers are running.

sudo docker-compose ps

Self-hosted Retool is now running on EC2. Go to http://<your-ec2-ip-address>/auth/signup to create your Retool admin account.

Additional steps

On production instances, you should:

• Externalize your PostgreSQL database to a managed service.
• Set up SSL on your deployment.
• Keep up-to-date with the newer versions of Retool.

For ease of use and as a proof of concept, the default docker-compose configuration includes a PostgreSQL container, and it does not set up SSL. This is not suitable for production use cases, and you should host the Retool storage database on an external, managed database. Managed databases are more maintainable, scalable, and reliable than containerized PostgreSQL instances. Follow the instructions in the external storage database guide to configure your database.

Setting environment variables is also often necessary to configure SSO, source control, and other self-hosted features. See the environment variable reference for additional configuration options.

Update Retool

1. Create a backup. AWS provides a method to back up your EC2 instance with an AMI. If you don't perform a full backup, you should at least:

• Create a snapshot of your PostgreSQL database.
• Copy the environment variables in docker.env to a secure location outside of Retool.

2. SSH into your instance and update your Dockerfile with the newer version number.

FROM tryretool/backend:X.Y.Z

3. Install the upgrade.

./update_retool.sh

Retool instances temporarily go down while they upgrade. You can check the status of your containers with sudo docker-compose ps.

Update configuration files

Occasionally, new Retool products and features require updates to the configuration files in retool-onpremise or other Retool repositories. To update these files when new features are available, SSH into your EC2 instance and pull the changes.

cd retool
git pull

Refer to the product or feature-specific documentation for configuration instructions.