Skip to main content

Deploy Retool on Google Compute Engine

Learn how to deploy Self-hosted Retool with a GCP Compute Engine VM.

You can deploy an instance of Self-hosted Retool on Google Compute Engine with Docker Compose.

Requirements

To deploy Retool, you need:

VM configuration

Self-hosted Retool instances require a Linux-based virtual machine that meets the following requirements:

  • Ubuntu 22.04 or later.
  • 16GiB memory.
  • 8x vCPUs.
  • 60GiB storage.
  • curl and unzip software packages installed.
Allocate more resources to scale

Retool recommends you allocate more resources than the minimum requirements so that your instance can more easily scale.

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.

Initializing namespace in Retool-managed Temporal

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. Create a Linux VM instance

Create a new Linux VM in the Google Cloud console that meets the minimum requirements. Refer to the Google Cloud documentation to learn how to create a new virtual machine.

VM settingDescription
NetworkConfigure the VM to allow HTTP and HTTPS traffic.
StorageSpecify SSD persistent with a size that meets or exceeds the minimum requirements.

Once the VM is initialized, download the private key when prompted. Update the permissions of the key-pair to ensure it has the required permissions for your SSH client.

chmod 400 <path_to_pem_file>

2. Download Self-hosted Retool

GCP automatically runs the new virtual machine once created. Once the new Linux VM is ready, use the Google Cloud console to connect using SSH.

Download or clone the retool-on-premise GitHub repository.

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

3. Install Docker dependencies

Run ./install.sh to prepare the Docker image. The script also installs Docker and Docker Compose if they are not already available.

4. 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.

Encryption key cannot be recovered

You will need to reconfigure all resources if the encryption key is lost.

5. Configure deployment

There are three files to configure for your deployment:

FileDescription
docker.envEnvironment variables to control or override certain deployment options.
docker-compose.ymlThe Docker Compose configuration to use for the deployment.
DockerfileThe standard configuration file for Retool's Docker image.

Specify the version of Retool to use

Specify the Docker tag for the version of Retool to install, such as tryretool/backend:3.52.3-stable.

Avoid using latest

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

Prepare Compose file

Retool provides two Docker Compose files from which to choose, depending on the Temporal cluster you will use:

Compose fileTemporal cluster typeConfiguration
docker-compose.ymlRetool-managed or self-managedPreconfigured for use with a Retool-managed cluster and ready to use.
docker-compose-with-temporal.ymlLocalDelete docker-compose.yml and rename docker-compose-with-temporal.yml to docker-compose.yml. You must also copy the dynamicconfig directory in retool-onpremise onto your deployment instance.

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

Set license key and disable SSL

Configure the following environment variables in docker.env:

VariableValueDescription
LICENSE_KEYYour Self-hosted Retool license key.The license key obtained from the Self-hosted Portal.
COOKIE_INSECUREtrueAllows you to use Self-hosted Retool without SSL. This variable is included in docker.env for you to uncomment.
Update configuration when enabling SSL

Once you configure SSL, set COOKIE_INSECURE to false.

6. Start the instance

Run sudo docker-compose up -d to start Self-hosted Retool. This can take several minutes as the instance performs the initial setup and starts its services for the first time.

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

You can check whether Docker containers are running with sudo docker-compose ps.

Additional configuration

When deploying a production instance of Self-hosted Retool, 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 your Google Compute Engine instance

Follow these instructions to update your Retool instance to a newer release version.

Back up the instance before performing an update

Retool strongly recommends that you back up the VM before performing an update. If you cannot complete 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:

  1. Update the Dockerfile with the newer version number. For example, tryretool/backend:3.52.3-stable.
  2. Run ./update_retool.sh to start the update.

The Retool instance is temporarily stopped while the update takes place. Once complete, the instance starts automatically.