Self-hosted Retool architecture
Learn about Retool's self-hosted architecture.
Retool's self-hosted Docker image consists of containers which run the web app, store instance-level data like users and permissions, and run jobs like database migrations. The docker-compose file for self-hosted Retool Self-hosted defines these containers.
Retool uses semantic versioning—X.Y.Z—for self-hosted releases and publishes them in Docker Hub. Each tag corresponds to the release version of the image, which you can use with Docker Compose or Kubernetes. The image includes the frontend, backend, and db-connector services.
Services
At a high level, Retool consists of the following services.
| Service | Description |
|---|---|
| API | Primary container to serve the Retool application. Contains frontend and backend services, and handles most logic for user interactions in the app. |
| Load balancer or Ingress | Distributes requests to the API containers. |
| DB Connector | Connects to customer resources (databases, APIs, etc.) and returns results to the API service. |
| Storage database | PostgreSQL database to store apps, resources, users, permissions, and data necessary to run Retool. |
| Jobs runner | Handles database migrations, source control, background tasks, and related logs. Syncs changes between API containers and the storage database, so it is dependent on the storage database container. There should only ever be one jobs runner container. |
Kubernetes deployments consist of api (which includes frontend, backend, db-connector, and db-ssh-connector services) and jobs_runner pods.
Docker deployments consist of api, db-connector, db-ssh-connector, and jobs-runner containers.
All deployments contain a default postgres pod or container for the storage database, which you should only use for demo and testing purposes, and externalize for production uses.
Data flow
The following explains how queries flow from user interactions in a browser through the Retool application.
- In the browser, the user enters a URL to a Retool application.
- The request is sent to a load balancer, which proxies the request to the frontend service.
- The frontend service responds to the browser with the HTML, CSS, and JavaScript for the application.
- The frontend sends a request to backend service to execute queries.
- The backend service forwards queries to the DB Connector service.
- The DB Connector service connects to customer resources (e.g. databases, APIs) and sends results back to the backend service.
- The backend service forwards the results back to the browser that renders in the application.