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.

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 Terraform blueprints for production.

Requirements​

VM configuration​

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

  • Ubuntu 22.04 or later.
  • x86 architecture.
  • 64 GiB memory minimum.
  • 8 vCPUs minimum.
  • 60 GiB storage minimum.
  • 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.

Source control proxy configuration​

If your environment routes outbound traffic through a proxy, source control connections (such as GitHub or GitLab) require additional configuration. The standard HTTP_PROXY and HTTPS_PROXY variables are not sufficient for source control operations.

Set the following GLOBAL_AGENT_* variables in your deployment, using the same values as your HTTP_PROXY, HTTPS_PROXY, and NO_PROXY settings:

GLOBAL_AGENT_HTTPS_PROXY=https://your-proxy:8080
GLOBAL_AGENT_HTTP_PROXY=http://your-proxy:8080
GLOBAL_AGENT_NO_PROXY=localhost,127.0.0.1,.internal.example.com

Then enable the proxy agent for the services that need outbound access:

GLOBAL_AGENT_BACKEND=true
GLOBAL_AGENT_JOBS_RUNNER=true
GLOBAL_AGENT_DB_CONNECTOR=true

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-onpremise GitHub repository.

Download with curl
curl -L -O https://github.com/tryretool/retool-onpremise/archive/refs/heads/main.zip \
&& unzip main.zip \
&& cd retool-onpremise-main
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. The stable release is 4.0.0-stable.

Specify the same exact version tag for every image in the Dockerfile. All services must run matching versions. Mismatches will cause unexpected failures.

Prepare Compose file​

By default, temporal.yaml is disabled in the Compose configuration. Retool-managed Temporal is the recommended path for most deployments. If you have an existing Temporal cluster, you can configure it instead by uncommenting the include block in compose.yaml and setting the WORKFLOW_TEMPORAL environment variables in docker.env.

Retool-managed Temporal requires outbound egress on the following ports and domains:

PortDomains
443*.retool.com, *.tryretool.com, *.temporal.io
7233*.tmprl.cloud

Complete Temporal setup in the Retool UI after the instance is running: navigate to the Workflows page and follow the in-product steps. A valid license key is required.

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​

The Compose configuration includes the following services in addition to the core Retool containers: js-executor (backend function execution), agent-sandbox (app editing environment), r2Agent (agent Temporal worker), rrGitServer (Git server for source control), and MinIO (local blob storage for development). These start automatically alongside the core containers.

Retool-managed AI keys are not compatible with self-hosted deployments. The managed key proxy has a 29-second timeout that agent operations regularly exceed, causing silent failures. Configure your own API keys (Bring Your Own Key) under Resources → AI after the instance is running.

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 version tag in Dockerfile for all image references (backend, code-executor-service, js-executor-service, and agent-sandbox-service) to the same version. For example: 4.0.0-stable.
  2. If your deployment uses a separate CodeExecutor.Dockerfile, update it to 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.