Skip to main content

Deploy Self-hosted Retool with Docker

Deploy a non-production instance of Self-hosted Retool on a Linux-based VM using Docker.

Self-hosted Retool Availability
Self-hosted EdgeGenerally Available
Self-hosted StableGenerally Available

You can locally deploy a non-production instance of Self-hosted Retool for testing and development on a Linux-based VM using Docker. The default Docker Compose configuration includes a PostgreSQL container and does not set up SSL for testing purposes. This is not suitable for production use cases.

Docker deployments are not suitable for production use. Deploy a Kubernetes instance using Helm for production.

Requirements​

To deploy Retool for non-production or development purposes using Docker, you need:

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.

Temporal​

Temporal is a distributed system used to schedule and run asynchronous tasks for Retool Workflows and Retool Agents. 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.

For nonproduction use, Retool recommends using the same database for the Retool Database and Workflows Queue. Without any extra configuration, Retool Workflows can process approximately 5-10 QPS (roughly, 5-10 concurrent blocks executed per second).

Network requirements​

Self-hosted Retool deployments must allow access to Retool's IP addresses or domains. If you make use of outbound firewall rules, include the following IP addresses or domains in its allowlist. These allow your deployment to connect to Retool's license check, user authentication, and usage reporting services.

CIDR IP addresses
35.92.202.168/29
44.211.178.248/29
Individual IP addresses
35.92.202.168
35.92.202.169
35.92.202.170
35.92.202.171
35.92.202.172
35.92.202.173
35.92.202.174
35.92.202.175
44.211.178.248
44.211.178.249
44.211.178.250
44.211.178.251
44.211.178.252
44.211.178.253
44.211.178.254
44.211.178.255
Domains
licensing.tryretool.com
invites.tryretool.com
email-service.retool.com
p.tryretool.com
specs.tryretool.com
pypi.org

Egress is required when using Retool-managed Temporal. Refer to the Egress section of the Temporal conceptual guide for more information.

HTTP proxy connections​

Retool supports connections to the internet through a HTTP proxy. Add HTTP_PROXY=http://example.com:8080 to your deployment's docker.env file with the required URL and port number.

License checks​

Retool uses HTTP to connect to licensing.tryretool.com on port 443 to verify your license. License checks are made at least once a day.

Inviting users​

Retool connects to invites.tryretool.com and email-service.retool.com on port 443 when inviting users. Retool verifies the users are authorized under your current billing plan, and then sends an invite to their email address.

Usage reporting​

Retool sends application usage information to p.tryretool.com on port 443, which is used to inform product decisions.

Usage categories​

The categories of usage information sent to Retool includes, but is not limited to, the following:

  • Page views, along with the page URL.
  • Query saves, including the query name and type.
  • Component creation and the component type.
  • Query preview, including the query name and type.
  • Adding a resource, including the resource name and type.

Events are also sent with the hostname, public IP address, browser user-agent string, and the user's email address.

1. Download Self-hosted Retool​

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

2. Install dependencies​

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

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

4. 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:X.Y.Z-stable.

Specify the exact version to use, such as X.Y.Z-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.

5. 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://0.0.0.0:3000/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​

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.

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 on your production Kubernetes deployment instance to ensure that change management is in use from the start.

Update your Docker 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:X.Y.Z-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.