Understanding Retool Environment Variables

Environment variables in Retool are more than just configuration settings. They serve as the gatekeepers of your application's security. By storing key-value pairs, they shield sensitive information like API keys and database credentials from the source code, making it significantly more challenging for potential threats to access them.

How Environment Variables Configure and Secure Self-Hosted Retool Deployments

In self-hosted Retool deployments, environment variables are pivotal in configuring the application and ensuring its security. They empower administrators to establish crucial configurations such as database connections, authentication methods, and API rate limits without embedding these details into the application's code.

This setup guarantees the management of sensitive data securely and effectively. Retool's support for using these variables to centralize and control access to sensitive information, which is stored encrypted in Retool's database, is a testament to their importance in the configuration process.

For more detailed information, visit Retool's official documentation on environment variables and managing configuration variables.

Check out the “ALLOW_SAME_ORIGIN_OPTION” under retool environment variables from the following section.

ALLOW_SAME_ORIGIN_OPTION

The ALLOW_SAME_ORIGIN_OPTION environment variable in Retool enables the allow-same-origin flag in the sandbox attribute of iframes. When you set the flag, it allows iframe-based components, such as custom components, to use features like LocalStorage and cookies, which are restricted when the flag is not set. By default, ALLOW_SAME_ORIGIN_OPTION is set to false to maintain a higher level of security by limiting the capabilities of JavaScript running within iframes.

Interaction with SANDBOX_DOMAIN for Iframe Security

When ALLOW_SAME_ORIGIN_OPTION is enabled (true), it is crucial to configure the SANDBOX_DOMAIN environment variable. SANDBOX_DOMAIN specifies an alternative domain for running JavaScript in a sandboxed environment, isolating it from the main domain. This setup prevents potentially malicious code in iframes from accessing sensitive information in the base domain.

If SANDBOX_DOMAIN is not set, enabling ALLOW_SAME_ORIGIN_OPTION can pose a security risk by allowing the iframe-based JavaScript to run in the same origin as the main application, potentially exposing the application to cross-origin attacks.

For more detailed information, you can visit Retool's documentation on environment variables and sandbox domain configuration.

Also, check out how to build the Retool Portals app.

Learn more about API_CALLS_PER_MIN under retool environment variables from the following section.

API_CALLS_PER_MIN

The API_CALLS_PER_MIN environment variable in Retool sets a rate limit for API requests. By default, Retool uses a point-based system where each API endpoint request consumes a certain number of points, with a default limit set at 300 points per 60-second window. If you exceed this limit, the system will block any subsequent API calls for the next 60 seconds to prevent system overload and ensure fair usage across all users.

Customizing the Rate Limit

To adjust the rate limit, you can customize the API_CALLS_PER_MIN environment variable. Increasing this value allows for more API requests per minute, which can be helpful for applications requiring frequent data interactions. Conversely, lowering the value can help manage resource consumption and control traffic to your API endpoints. This flexibility ensures that your Retool deployment can be tailored to match your specific performance and resource management needs.

For more information, visit retool.com or contact Toolpioneers for further support.

Now, Check Out More Details on BASE_DOMAIN in the following section.

BASE_DOMAIN

The BASE_DOMAIN environment variable in Retool specifies the full URL of your Retool deployment. This URL is essential for user-related actions such as password resets and invitations. Setting the BASE_DOMAIN ensures that all email communications and links direct users to the correct domain, providing a seamless and consistent user experience.

Handling Automatic Determination Failures Behind Proxies

Sometimes, especially when your Retool deployment is behind a proxy server, the system may fail to determine the base domain automatically. When this happens, it is crucial to manually set the BASE_DOMAIN variable to ensure proper routing of requests and correct functioning of user-related features. By explicitly defining the BASE_DOMAIN, you can avoid issues related to incorrect URL generation and ensure the reliable operation of your Retool instance.

For additional information on BASE_DOMAIN, check out retool documentation.

Expand your knowledge of CUSTOM_API_KEY under retool environment variables from the following section.

CUSTOM_API_KEY

The CUSTOM_API_KEY environment variable in Retool allows you to override the default API keys generated by Retool. It can be useful for integrating with external systems or APIs that require specific API keys for authentication and access control. By setting a custom API key, you can ensure that your application uses the correct credentials, enhancing security and simplifying API management.

Example Configuration

To configure the CUSTOM_API_KEY environment variable, add it to your Retool environment settings. Here’s an example of how to set it up:

CUSTOM_API_KEY=your_custom_api_key_here

Replace your_custom_api_key_here with the actual API key you want to use. This configuration ensures that all API calls from your Retool application use the specified custom API key, overriding the default one generated by Retool.

The following section includes more information on CUSTOM_RETOOL_SANDBOX_RESTRICTIONS under retool environment variables.

CUSTOM_RETOOL_SANDBOX_RESTRICTIONS

The CUSTOM_RETOOL_SANDBOX_RESTRICTIONS environment variable in Retool allows you to configure specific restrictions for the JavaScript sandbox environment within your applications. When you specify space-separated values, you define which capabilities are enabled within the sandbox. Common restrictions you can configure include:

allow-downloads: Allow files to be downloaded from within the sandbox.
allow-popups: Permit the opening of pop-up windows.
allow-modals: Enable modal dialogs within the sandbox.

Example configuration:

CUSTOM_RETOOL_SANDBOX_RESTRICTIONS=allow-downloads allow-popups allow-modals

Security Implications of Sandbox Modifications

Modifying the JavaScript sandbox restrictions can have significant security implications. The sandbox environment isolates potentially harmful scripts, preventing them from accessing critical resources or performing malicious actions. Loosening these restrictions (e.g., allowing downloads or pop-ups) increases the risk of exposing your application to security vulnerabilities, such as cross-site scripting (XSS) attacks or data exfiltration.

Therefore, it is crucial to carefully consider the necessity of each modification and understand the potential risks involved. Only apply the minimum necessary permissions to achieve the desired functionality, and continuously monitor and audit the security of your application to mitigate potential threats.

Also, check out how to use additionalScope in your queries.

Do you know about DEBUG in retool environment variables? Don’t worry. Scroll down to find more information.

DEBUG

The DEBUG environment variable in Retool enables verbose logging for troubleshooting and debugging purposes. When set, it provides detailed logs of the application's operations, which can be invaluable for identifying and resolving issues. This setting is particularly useful during the development and testing phases, allowing developers to gain deeper insights into the application's behavior and pinpoint problems quickly.

However, using this setting judiciously is important, as enabling verbose logging can generate a large volume of log data, potentially impacting performance and making it harder to sift through the logs.

To enable DEBUG logging, simply set the DEBUG environment variable to true:

DEBUG=true

For more detailed information on configuring environment variables in Retool, visit the Retool documentation on environment variables.

Learn more about public access and web widgets under retool environment variables from the following section.

Public Access and Web Widgets

How Environment Variables Configure and Secure Self-Hosted Retool Deployments

This section will cover all the details related to public access and web widgets and it will be quite useful for you.

DISABLE_IMAGE_PROXY for Disabling the Proxy for Public Apps

The DISABLE_IMAGE_PROXY environment variable in Retool disables the image proxy for public apps. By default, Retool proxies images to enhance security and control over content delivery. Disabling this proxy might be necessary for certain use cases requiring direct image access. However, it is important to understand the security implications, as it could expose the application to direct image loading from external sources.

DISABLE_INTERCOM to Remove Retool's Frontend Support Widget

Setting the DISABLE_INTERCOM environment variable to true will remove Retool’s Intercom frontend support widget from the user interface. This is useful for environments where the support widget is not needed or where you want to minimize the footprint of external services for security or performance reasons.

DISABLE_PUBLIC_PAGES to Restrict Public Access to Retool Apps

The DISABLE_PUBLIC_PAGES environment variable, when set to true, restricts public access to Retool applications. This ensures that only authenticated users can access the applications, thereby enhancing security by preventing unauthorized access to potentially sensitive tools and data.

DISABLE_FORWARDABLE_COOKIE_DECODED for Cookie Handling in Authentication

The DISABLE_FORWARDABLE_COOKIE_DECODED environment variable affects how cookies are handled in Retool for authentication purposes. When you set it, it ensures that it does not decode forwardable cookies, which can be an important security measure to prevent unauthorized access and maintain the integrity of authentication processes.

Learn more about domain and security settings from the following section.

Domain and Security Settings

This section covers detailed information on the domain and security settings in retool environment variables and their purpose.

DOMAINS for SAML Requests and SSL Certificates

The DOMAINS environment variable specifies the domain for SAML requests and SSL certificate configuration in Retool. This ensures that SAML authentication requests and SSL certificates are properly aligned with your deployment's domain, enhancing security and user authentication integrity.

HOST_HEADER_NAME for Handling Original Host in Spaces

HOST_HEADER_NAME manages the original host header in Retool Spaces. This variable is critical when your deployment is behind a proxy, as it ensures that the original host information is preserved and correctly handled by Retool, maintaining the accuracy of request routing and security.

HTML_ESCAPE_RETOOL_EXPRESSIONS to Mitigate XSS Risks

Setting HTML_ESCAPE_RETOOL_EXPRESSIONS to true enables the automatic escaping of HTML in Retool expressions. This measure is essential for mitigating cross-site scripting (XSS) risks, ensuring that any user-generated content or dynamic expressions do not introduce security vulnerabilities by injecting malicious code into your applications.

SANDBOX_DOMAIN for Safe JavaScript Execution

The SANDBOX_DOMAIN environment variable specifies an alternative domain for executing JavaScript in a sandboxed environment. This isolation is crucial for preventing potentially harmful scripts from accessing sensitive data or affecting the primary domain, enhancing overall security.

NODE_TLS_REJECT_UNAUTHORIZED for TLS Certificate Handling

The NODE_TLS_REJECT_UNAUTHORIZED variable determines how Retool handles TLS certificates. Setting this to 0 allows Retool to accept self-signed certificates, which can be helpful during development or testing phases. However, this should be set to 1 for production environments to enforce strict TLS certificate validation, ensuring secure and trusted connections.

For more detailed information, visit Retool’s documentation on environment variables and their specific guides on configuring SSO and security settings.

Retool docs: Environment variables reference, Authentication environment variables, Configure SSO with SAML authentication, Restrict SSO domains.

Check out more information on logging and analytics from the following section.

Logging and Analytics

This section will give you an overview of the logging and analytics.

LOG_AUDIT_EVENTS for Auditing User Actions

The LOG_AUDIT_EVENTS environment variable enables detailed logging of user actions within Retool. By setting this variable to true, you can capture and output all audit events to stdout. This is useful for monitoring and analyzing user behavior, ensuring compliance, and maintaining security standards. It is especially beneficial for enterprises that require comprehensive audit trails.

LOG_LEVEL for Defining Verbosity of Logs

The LOG_LEVEL environment variable allows you to specify the verbosity of logs in Retool. You can set it to different levels, such as info (default), verbose, or debug, depending on the amount of detail you need in your logs. This flexibility helps you adjust the level of detail for troubleshooting and monitoring purposes, ensuring you have the necessary information without overwhelming your logging system.

DISABLE_MEMORY_AND_CPU_USAGE_LOGGING to Control Resource Usage Logging

When set to true, the DISABLE_MEMORY_AND_CPU_USAGE_LOGGING variable disables the logging of CPU and memory usage. This can be useful in reducing the volume of logs and focusing on more critical logging information, especially in environments where resource usage is monitored by other means.

DISABLE_AUDIT_TRAILS_LOGGING for Audit Log Management

Setting the DISABLE_AUDIT_TRAILS_LOGGING variable to true disables all audit trail logging in Retool. This might be necessary in certain scenarios where audit logging is managed externally or where minimizing logging for performance is a priority. However, disabling audit logs should be done cautiously, considering the potential impact on security and compliance.

You can visit Retool's documentation for more detailed information on these environment variables.

Retool docs: View user audit logs, General environment variables, and Environment variables reference.

The following section will shed some light on proxy and network settings in retool environment variables.

Proxy and Network Configuration

Expand your knowledge of the proxy and network settings in retool environment variables.

HTTP_PROXY for Directing HTTP Traffic Through a Proxy

The HTTP_PROXY environment variable in Retool routes all HTTP traffic through a specified proxy server. Managing outbound connections is essential in environments where direct internet access is restricted or needs to be monitored. By setting this variable, you can ensure that all HTTP requests from your Retool instance are directed through the proxy, providing better control over network traffic and enhancing security.

NO_PROXY for Excluding Certain URLs from Proxying

The NO_PROXY environment variable allows you to specify a list of URLs that should bypass the proxy settings defined in HTTP_PROXY. This is useful for excluding internal or local addresses from routing through the proxy, ensuring efficient and direct access to specific resources without unnecessary routing.

Combining these two settings allows you to create a more flexible and controlled network configuration for your Retool deployment, ensuring that critical internal traffic is handled appropriately while maintaining overall security and management of external connections.

Expand your view on the performance and service management in the retool environment variable in detail from the following section.

Performance and Service Management

Learn how performance and service management lead to optimized performance in this section.

NUM_WORKERS to Set the Number of Worker Threads

The NUM_WORKERS environment variable in Retool determines the number of worker threads for the api container. This setting helps optimize performance by allowing you to allocate a specific number of threads based on the number of logical CPU cores available. Retool sets this value by default to the minimum number of CPU cores and 3, ensuring efficient resource usage. For example, setting NUM_WORKERS=4 would allocate four worker threads, which can improve the handling of concurrent requests.

SERVICE_TYPE for Specifying the Services a Container Runs

The SERVICE_TYPE environment variable allows you to define which services a Retool container will run. This is useful for customizing container roles within your infrastructure, especially in a microservices architecture. Acceptable values include MAIN_BACKEND, JOBS_RUNNER, DB_CONNECTOR, DB_SSH_CONNECTOR, WORKFLOW_BACKEND, and WORKFLOW_TEMPORAL_WORKER. For instance, setting SERVICE_TYPE=MAIN_BACKEND, JOBS_RUNNER configures the container to run only the main backend and job runner services, optimizing resource allocation and performance.

Configuring RETOOL_ENV for Different Environment Setups and Alerts

The RETOOL_ENV environment variable specifies the environment name for your Retool deployment. This is particularly useful for distinguishing between development, staging, and production environments. By setting RETOOL_ENV=production, you ensure that environment-specific configurations and alerts are appropriately managed, enhancing operational clarity and security.

Gain more insight on licensing and security keys from the upcoming section.

Licensing and Security Keys

Learn about how to obtain a license and security keys from this section.

LICENSE_KEY for Activating a Self-Hosted Retool Instance

The LICENSE_KEY environment variable is crucial for activating and running a self-hosted Retool instance. When you purchase a Retool license, you will receive this key, which you must set in your environment configuration to validate your instance. With this key, your Retool deployment will be operational, ensuring your installation is properly licensed and authenticated.

RETOOL_EXPOSED_{NAME} for Securely Storing Configuration Secrets

The RETOOL_EXPOSED_{NAME} environment variable securely stores sensitive configuration secrets, such as database passwords, API keys, and other critical credentials. By prefixing the variable name with RETOOL_EXPOSED_, you can make these secrets accessible within your Retool applications while keeping them out of the source code, enhancing security.

These environment variables help ensure that we handle sensitive information securely and efficiently, thus maintaining the integrity and security of our Retool deployments.

Check out the best practices and recommendations from the following section.

Best Practices and Recommendations

This section will guide you through the best practices and recommendations for successfully completing your task associated with the retool environment variable.

Security Considerations for Sandbox and Proxy Settings

Sandbox Security:

SANDBOX_DOMAIN: Configuring the SANDBOX_DOMAIN environment variable helps isolate JavaScript execution from the main domain, reducing the risk of cross-site scripting (XSS) attacks. This ensures that potentially harmful scripts run in a controlled environment, preventing unauthorized access to sensitive data.
CUSTOM_RETOOL_SANDBOX_RESTRICTIONS: Use this to specify necessary sandbox restrictions, such as allowing downloads or pop-ups. Only enable the minimum permissions required to maintain a secure environment.

Proxy Settings:

HTTP_PROXY and NO_PROXY: Properly configure these settings to manage outbound traffic securely. The NO_PROXY setting ensures that sensitive endpoints bypass the proxy.
Security Implications: Always validate and sanitize inputs to prevent proxy-related vulnerabilities. Ensure that proxy configurations do not expose internal services to the public internet.

Recommendations for Environment Variables Setup to Optimize Retool Performance

Optimizing Worker Threads:

NUM_WORKERS: Adjust the number of worker threads based on the available CPU cores to handle concurrent requests efficiently.

Environment Configuration:

RETOOL_ENV: This variable ensures that it correctly manages environment-specific configurations and alerts.

Service Management:

SERVICE_TYPE: Define the specific services a container should run to optimize resource usage and performance.

Logging and Monitoring:

LOG_LEVEL: Set an appropriate log level to balance the verbosity needed for debugging and performance impact.

Audit and Usage Logging:

DISABLE_MEMORY_AND_CPU_USAGE_LOGGING: Disable resource usage logging if external monitoring tools are in place to reduce logging overhead.