Skip to main content

Deploy Self-hosted Retool with Amazon EC2

Learn how to deploy Self-hosted Retool on Amazon EC2 with Docker Compose.

You can deploy Self-hosted Retool onto Amazon EC2 using Docker Compose. You also have the option to deploy with Retool Workflows.

Requirements​

To deploy Self-hosted Retool on Amazon EC2 using Docker Compose, you need:

Self-hosted deployments also require a Linux VM with the following:

  • Ubuntu 22.04 or later.
  • x86 architecture.
  • t3.large instance type.

In addition, Retool recommends you:

System architecture​

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

Example Retool deployment with EC2 architecture

Video walkthrough​

Watch the video to see an example of deploying Retool on Amazon EC2, or get started by following the steps below.

1. Create a Linux EC2 instance​

Create a new Linux EC2 instance in the Amazon EC2 console using an Amazon Machine Image (AMI) that meets the minimum requirements. Refer to the Amazon EC2 documentation to learn how to create a new instance.

Authentication​

When creating the instance, use SSH public key authentication and provide a username. Generate a new key-pair and specify a name.

Network​

Create or use an existing security group with the following inbound rules:

Port rangeTypeSource
80HTTP0.0.0.0/0 and ::/0
443HTTPS0.0.0.0/0 and ::/0
22SSH0.0.0.0/0 and ::/0
3000Custom TCP0.0.0.0/0 and ::/0

Self-hosted Retool initally runs on port 3000. Once SSL is configured, this port is no longer required.

2. Download Self-hosted Retool​

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.

ssh -i keypair.pem <username>@<public_ip>

Download or clone the retool-on-premise repository. 

curl -L -O https://github.com/tryretool/retool-onpremise/archive/master.zip \
&& unzip master.zip \
&& cd retool-onpremise-master

3. Set up Docker​

Run the install.sh script to install Docker and create the docker.env file.

./install.sh

4. Update environment variables​

Configure environment variables in docker.env:

  • Set LICENSE_KEY to your license key.
  • Uncomment COOKIE_INSECURE=true to use Self-hosted Retool without SSL. Once you configure SSL, set this to false.

5. Back up encryption key​

The install script generates a value for ENCRYPTION_KEY and stores it within docker.env. This key encrypts secrets for your Retool resources. Save this key in a secure location outside of Retool.

6. Configure deployment​

Set your Retool release version in Dockerfile. We recommend using the most recent tag available in tryretool/backend.

By default docker-compose.yml starts a worker service for use w/the Workflows product.

To stop this worker from starting up, comment or delete the following lines from docker-compose.yml:

7. Start Self-hosted Retool​

Run sudo docker-compose up -d to start Self-hosted Retool. This can take several minutes as the deployment performs initial setup and first starts its services. You can confirm that the deployment containers are running with sudo docker-compose ps

Once running, Self-hosted Retool is available at http://<your-ec2-ip-address>/auth/signup. When you first visit the page, you must create an admin account.

Additional steps​

On production instances, you should:

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​

Before updating your deployment, create a backup of the instance. 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.

To update your deployment to a newer version of Self-hosted Retool, first update your Dockerfile with the newer version number. Self-hosted Retool uses semantic versioning with MAJOR.MINOR.PATCH version numbers. For example, to update your deployment to 3.22.1, specify:

FROM tryretool/backend:3.22.1

Next, run the update_retool.sh script. 

./update_retool.sh

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