Deploy Retool with Azure VM

Learn how to deploy Self-hosted Retool with Azure VMs.

Follow the instructions in this guide to deploy self-hosted Retool on an Azure VM.


To deploy Retool on Azure VM, you need:

  • A Retool license key, which you can obtain from or your Retool account manager.
  • Some familiarity with Azure and Azure VMs.
  • An Azure account.

1. Create an Azure VM instance

  1. In the Azure Portal, click Create a Resource. Under Virtual Machines, click on Create. Select a subscription and resource group. Name your VM, and select your preferred region.

  2. At a minimum, select the Ubuntu 22.04 image using Standard_D2s_v3 - 2 vcpus, 8 GiB memory.. Refer to Retool's storage requirements to see supported operating systems and select an instance that fits your needs.

  3. Select SSH public key in Authentication type, and provide a username. Select Generate a new key pair in the SSH public key dropdown, and name your key. Azure generates this key and stores it in the Azure KeyVault. You can download this key later and use it to log in to your remote VM.

  4. In Public inbound ports, select Allow selected ports. Click Select inbound ports and select SSH (22), HTTP (80), and HTTPS (443).

  5. In the next Disk section, select Standard SSD. Enable the Delete with VM option. Select Create, and attach a new disk. Name the disk and select None in Source type. Set the Size to 64 GiB and select OK. Ensure Delete with VM is enabled for the newly added data disk.

  6. In the next Networking section, use the provided defaults. Allow the HTTP (80), HTTPS (443), and SSH (22) ports for inbound traffic, and ensure a public IP is set.

  7. Enable Delete public IP and NIC when VM is deleted. Select Review + create.

  8. Wait for the validations to pass, then click Create. Click Download private key and create resource from the resulting modal. Your Azure VM is now running.

  9. Run the following command to ensure your downloaded key pair has the appropriate permissions for your SSH client.

chmod 400 <path_to_pem_file>
  1. Wait on the Create VM deployment screen until your VM deployment is complete. After a couple of minutes, your VM will be deployed and you can click Go to resource.

  2. On the Virtual machine status page, copy the public IP address.

2. Install Retool

  1. Open a new terminal and SSH into your new VM using the username you set, the public IP address, and your downloaded .pem key pair:
ssh -i keypair.pem <username>@<public_ip>
  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 for Docker and Docker Compose:

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.

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 an Azure VM. Go to http://<your-azurevm-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. Azure provides a method to back up your 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 Azure VM and pull the changes.

cd retool
git pull

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