Skip to main content

Deploy Self-hosted Retool on Azure Virtual Machines

Learn how to deploy Self-hosted Retool on an Azure Virtual Machines with Docker Compose.

You can deploy an instance of Self-hosted Retool on Azure Virtual Machines with Docker Compose.

Requirements​

To deploy Retool, you need:

  • A Retool license key, which you can obtain from the Retool Self-hosted Portal or your Retool account manager.
  • Familiarity with and installations of Docker Engine and Docker Compose.
  • A compatible Linux-based virtual machine.
  • An externally managed PostgreSQL database for use by the deployment.

VM configuration​

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

  • Ubuntu 22.04 or later.
  • x86 architecture.
  • 16GiB memory.
  • 8x vCPUs.
  • 60GiB storage.
  • curl and unzip software packages installed.

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 committed (under contract) on a Business or 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.

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.

System architecture​

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

System architecture for a Retool instance on Azure VM
System architecture for a Retool instance on Azure VM

1. Create a Linux VM​

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

VM SettingDescription
AuthenticationUse SSH public key authentication and provide a username. Generate a new key-pair and specify a name. Azure generates and stores the key in the Azure KeyVault to download later.
NetworkAllow SSH (22), HTTP (80), and HTTPS (443) inbound public ports. The VM must have a public IP address set for external access, or a private IP which allows egress traffic from Retool's IPs. Ensure Delete public IP and NIC when VM is deleted is enabled.
StorageSpecify Standard SSD with a size that meets or exceeds the minimum requirements. Ensure Delete with VM is enabled for the newly added data disk.

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​

Azure automatically runs the new virtual machine once created. Obtain the public IP address from the Azure Portal and connect to it using SSH.

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

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

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

5. Configure the instance​

There are three files to configure for your deployment:

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

Specify the version of Retool to use​

In the Dockerfile, specify the Docker tag for the version of Retool to install, such as tryretool/backend:3.300.0-stable.

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

Prepare Compose file​

The default Docker Compose configuration includes a Temporal container that enables the use of Retool Workflows. To instead use a Retool or self-managed Temporal cluster, comment out the include block in compose.yaml, and update the WORKFLOW_TEMPORAL environment variables in docker.env.

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

Configure environment variables​

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.
BASE_DOMAINThe deployment instance URL (e.g., https://retool.example.com).The FQDN for the Retool instance being deployed.

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-azurevm-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​

You must prepare any self-hosted deployment instance for use in a production environment. Additional configuration may also be required depending on your needs.

The use of environment variables is often necessary to configure SSO, source control, and other self-hosted features.

SSL​

Docker Compose deployments of Self-hosted Retool include https-portal to automatically configure HTTPS. Before you start using your deployment instance in production, you must configure SSL.

You can either provision a certificate with Let's Encrypt or manually add your own certificates.

Set COOKIE_INSECURE to false once you configure SSL.

Single sign-on (SSO)​

Retool supports OpenID Connect (OIDC) and Security Assertion Markup Language (SAML) identity providers. Organizations can map IdP roles to Retool permission groups using OIDC role mapping or SAML group sync. Retool also supports LDAP Google Group sync when using Sign in with Google.

Refer to the SSO quickstart for information on configuring IdP providers.

Source Control​

Source Control allows organizations to manage changes to apps, workflows, resources, and themes using pull requests on remote source control management (SCM) providers, such as GitHub, GitLab, AWS CodeCommit, Bitbucket, and Azure Repos. Instead of making changes directly to an app, changes are made on a separate branch.

If you intend to use Source Control, Retool recommends configuring this as you prepare for production use to ensure that change management is in use from the start.

Update your Azure VM instance​

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

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.300.0-stable
  2. If your deployment is using CodeExecutor.Dockerfile, update it with the same version.
  3. Run ./upgrade.sh to perform the update.

The Retool instance is temporarily stopped while the update takes place and restarts automatically. Retool recommends performing the upgrade during off-peak hours to minimize downtime for users.