Environment Best Practices
Retool provides two different ways teams can develop. The first is Cloud, Retool’s Software as a Service (SaaS), while the second is Retool Self-hosted. Retool Self-hosted allows customers to install the Retool Platform in their preferred cloud provider (e.g., AWS, Microsoft Azure, Google Compute Platform) either in a Virtual Machine or, for enterprise deployments, Kubernetes. This document will guide you in configuring Retool to support small and enterprise teams.
Environments
Environments in the software development lifecycle represent infrastructure configured to support different stages of the development process. Each organization will have unique environment configurations. For example, smaller development teams may have a Sandbox and Production environment; larger teams may have a Development, Test, Staging, and Production environment. The purpose of environments is to create a physical separation of new development features, perform appropriate testing on different data sets, and promote these features to end-users using the production environment only when these features have passed.
Smaller Teams (Cloud-only)
Smaller development teams typically start with Retool Enterprise Cloud as their deployment option. In this scenario, Retool only provides customers with a single organization.
Spaces
To support multiple environments that are separated from one another, Retool introduced a feature called Retool Spaces. Retool Spaces allows an organization to create multiple workspaces with unique domain names. For example, a small development team may opt for a Sandbox and Production spaces. Within Retool, the administrator would go to Settings > Spaces and configure two spaces with the following domain names:
- dev.
organization_name.retool.com - prod.
organization_name.retool.com
Source Code Management
A mono-repo approach can be considered in Enterprise Cloud installations that leverage spaces to define environments. This approach uses a single repository to manage multiple apps and workflows organized under folders. Using this, both spaces would use the same repository and main branch.
Resources
In a single instance configuration, it is recommended that admins leverage Retool Environments. This feature allows for defining variations of a resource with unique properties for Sandbox and Production environments. For example, a REST API Resource can have distinct Sandbox and Production values for the endpoint, authentication parameters, and more.
Releases
To control the specific commit that is published and viewable by end users, Retool SCM can be combined with Retool Releases.
Retool Releases save the current state of an App for a draft or live version. This allows an admin to control which commit is made live versus only using the latest commit.
Enterprise Teams (Self-hosted)
Enterprise Teams typically operate with more governance/deployment policies. Customers that deploy Retool in their Public Cloud or On-premises should configure one Retool Platform Instance for each environment. If customers use a development, testing, and production environment, they will have three separate instances of Retool. This is meant to properly govern Retool deployments and the associated users/permission groups.
Spaces
Enterprise teams may use spaces to segregate different teams’ development work . At the highest level is the Admin space. Under this space, an administrator can create team spaces. For example, a team1.<domain>.com space and a team2.<domain>.com space. Within each space, you have a unique DNS and can either reuse or configure a unique Git repository, SSO provider, permissions, users, and database that can then develop unique apps, workflows, queries, and more.
Source Code Management
In Self-hosted installations leveraging spaces, teams can configure each space to connect to a distinct repository’s main branch.
Resources
In Self-hosted installations, each instance will have resources configured to connect with development, testing, and production services. For example, the development Retool instance will only have access to development services (e.g., databases, APIs, GraphQL endpoints). In contrast, testing and production will point to their respective testing and production services. This physical separation of downstream services keeps data aligned with the environment. It allows administrators to enforce specific governance controls, especially with production data, where information often includes personally identifiable information (PII).
Releases (Single instance only)
Retool Releases allow teams to mark a specific Git commit as the live version. This process must be performed on each instance separately (development, testing, production).
Appendix: Multi-tenancy in Retool
A specialized use case for enterprises employing Retool is in supporting multi-tenant solutions. In the first scenario using Retool Cloud, we have a development space, a staging space, and a customer production spaces (e.g., Customer A, Customer...), as shown in the following figure. Each space is synchronized with the main branch and updated accordingly. Development will use feature branches to test out new functionality and perform a PR and merge upon completion.
In the second scenario using Retool self-hosted, we have a development instance (e.g., Development VPC), a staging instance (e.g., Staging VPC), and a production instance (e.g., Production VPC), as shown in the following figure. The production instance also employs two customer spaces that external customers leverage independently. When changes to App A and Workflow A are merged into the main branch of the Git repository, the latest commit is deployed to development, staging, and both production spaces.
