Deploy Retool with GCP Compute Engine

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

Follow the instructions in this guide to deploy self-hosted Retool on Google Cloud Platform (GCP) Compute Engine.


To deploy Retool on GCP Compute Engine, you need:

  • A Retool license key, which you can obtain from or your Retool account manager.
  • Some familiarity with Google Cloud and Compute Engine VMs.
  • A Google Cloud account.

1. Create a GCP instance

  1. In the Google Cloud console dashboard sidebar, go to the VM instances tab in the Compute Engine section.

  2. Click on Create instance. Under Virtual Machines, click Create. Select a subscription and resource group. Name your VM, add any optional labels, and select an appropriate region and zone.

  3. At a minimum, select e2-standard-2 2vCPU 8GB under Machine type. Refer to Retool's storage requirements for supported operating systems and select an instance that fits your needs.

  4. In the Boot disk section, click Change. Select Ubuntu as the operating system, and under version select Ubuntu 22.04 LTS for x64/64.

  5. In Boot disk type, select SSD persistent disk. Change the size of the disk to 64 GB, and click Select.

  6. Use the defaults for Identity and API access. In the Firewall section, ensure that Allow HTTP traffic and Allow HTTPS traffic are both enabled.

  7. Click Create to spin up your instance. After about a minute, your instance should appear with a green checkmark status in the VM instances list. Click on SSH next to your instanceโ€™s name in the Connect column to SSH into your instance.

2. Install Retool

  1. Once SSHโ€™d in, clone the Retool on-premise repository and switch into the new directory.
git clone retool
cd retool
  1. Run the install script to create a docker.env file.

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.117.2. 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
  1. Confirm the containers are running.
sudo docker-compose ps

Self-hosted Retool is now running on GCP Compute Engine. Go to http://<your-gcp-ip-address>/auth/signup to create your Retool 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

  1. Create a backup. GCP provides a method to back up your GCP instance. 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.
  1. SSH into your instance and update your Dockerfile with the newer version number.
FROM tryretool/backend:X.Y.Z
  1. Install the upgrade.

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 GCP instance and pull the changes.

cd retool
git pull

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