Skip to main content

Scale Retool infrastructure

Learn how to scale your Retool deployment and infrastructure.

This guide provides technical best practices to scale your Retool infrastructure for enterprise use cases.

Retool's self-hosted Docker image consists of several containers required to run your deployment. Before you continue, you should review Retool's self-hosted architecture to understand which services need scaling as usage increases.

Scale your Retool deployment​

It's recommend to self-host Retool on a container orchestration service, such as Kubernetes. Retool provides Helm charts and Terraform modules for you to easily get started. See the deployment overview for a full list of supported deployment options.

Retool is packaged as a single stateless Docker container. The only dependency it has is a PostgreSQL database, which is used to store data such as user information, organization settings, audit logs, and applications.

To scale a Retool instance, you follow these high-level steps:

  1. Host the PostgreSQL database on an external system, e.g., AWS RDS. The separation of database and application allows you to independently scale and manage each service.
  2. Start multiple Retool containers that use the same Postgres database. The number of containers you deploy depends on your traffic and resource requirements. We recommend scaling the api container. You can do this by updating the replica count in your container orchestration service of choice.
  3. Use a load balancer to route traffic between the Retool server containers to ensure high availability.

You should only run one replica of the jobs-runner in each Retool environment because it runs database migrations and other background tasks that should only operate as a singleton. You can scale up as many replicas as necessary of the containers/pods that run the other service types.

Zero-downtime upgrades​

When you upgrade to a Retool version that requires running database migrations, it's possible for multi-container setups to run into downtime issues. This is because every container tries to run the migration at startup, which can lead to a deadlock. Follow these steps to avoid downtime.

  1. Know when you need to run a migration. Whenever Retool increments a minor version—from 2.0.0 to 2.1.0 for example—a migration is required.
  2. When you upgrade a major version, deploy a single Retool container with the newest version and allow that container to finish running the migrations. Because Retool makes sure that migrations are backwards compatible, this doesn't cause downtime.
  3. After the migration succeeds on the single Retool container, you can rollout the other containers.
  4. After all the migrations are complete, remove the container created in step two.