Horizontal scaling for self-hosted deployments

Retool is packaged as a single stateless Docker container. The only dependency it has is a Postgres database that Retool uses for storing data like user information, organization settings, audit logs, and applications.

At startup, Retool checks and runs any pending migrations on the database, and then starts itself up. The Retool server serves the API and frontend assets.

Scale a Retool instance

These are the general steps for scaling a Retool instance:

1. Host the Postgres database on an external system like AWS RDS.
2. Start multiple Retool containers that use the same Postgres database.
3. Use a load balancer to route traffic between the Retool server containers.

See our GitHub repo for a full list of deployment options.

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