Secret management using the file system

Some on-premise deployment systems, like Docker swarm and Docker secrets, require that secret values be read from the filesystem instead of being set directly through the environment variables. For instance, instead of setting a POSTGRES_PASSWORD in your environment, you may be required to point POSTGRES_PASSWORD_FILE to a text file that contains the required password. If that’s the case, Retool supports reading certain environment variables from the file system.

📘

This feature requires Retool version 2.66.10 or greater

🚧

You’ll still need the ability to set non-secret environment variables

At startup, Retool will look for the configured secret files and set them as environment variables for the running container, not the entire system.

To use this feature, first make sure to set the environment variable RETOOL_LOAD_FILE_SECRETS to true. Without this, Retool will not look to load secrets from the file system.

Next, pick the environment variable(s) that you want to configure. Instead of adding those secrets to the environment directly, you’ll add a path to the secret stored on the filesystem and append _FILE to the end of the environment variable name. For example, if you wanted to set the ENCRYPTION_KEY, you’d set ENCRYPTION_KEY_FILE to the path on the file system where the file exists.

# .env file
RETOOL_LOAD_FILE_SECRETS=true
ENCRYPTION_KEY_FILE=/path/to/key

When starting Retool, you’ll observe the following log lines:

RETOOL-CONFIG: RETOOL_LOAD_FILE_SECRETS is true, reading the following secrets from the filesystem
RETOOL-CONFIG: Setting ENCRYPTION_KEY via /path/to/key

If you see the above log messages, that means the listed environment variables were successfully set. If you see a different message, see Troubleshooting for next steps.

Managing your own secrets

Retool supports managing your own secrets using environment variables prefixed with RETOOL_EXPOSED. You can also manage these secrets using the file system. Instead of using the RETOOL_EXPOSED prefix, use RETOOL_FILE_EXPOSED. For example, if you wanted to allow your database password to be used by a resource, set RETOOL_FILE_EXPOSED_DB_PASSWORD to the path on the file system.

# .env file
RETOOL_LOAD_FILE_SECRETS=true
RETOOL_FILE_EXPOSED_DB_PASSWORD=/path/to/db/password
RETOOL-CONFIG: RETOOL_LOAD_FILE_SECRETS is true, reading the following secrets from the filesystem
RETOOL-CONFIG: Setting RETOOL_EXPOSED_DB_PASSWORD via /path/to/db/password

Troubleshooting

When using this feature, you may encounter the following error messages:

RETOOL-CONFIG: Error setting SECRET via SECRET_FILE: /path/to/secret_file does not exist

This means that the path provided in the SECRET_FILE environment variable does not exist. You should double check if the provided path is accessible to the container running Retool at build time.

RETOOL-CONFIG: Error setting SECRET via SECRET_FILE: /path/to/secret_file is a directory

This means that the path provided in the SECRET_FILE environment variable exists, but is not a file and therefore cannot be used to set the SECRET. Ensure that the path you’ve provided in the SECRET_FILE environment variable points to an actual file and not a directory.

Appendix: List of supported environment variables

This feature only works with the following environment variables which contain secret values:

  • CLIENT_SECRET
  • CUSTOM_API_KEY
  • CUSTOM_OAUTH2_SSO_CLIENT_SECRET
  • CUSTOM_OAUTH2_SSO_JWT_EMAIL_KEY
  • CUSTOM_OAUTH2_SSO_JWT_FIRST_NAME_KEY
  • CUSTOM_OAUTH2_SSO_JWT_LAST_NAME_KEY
  • CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY
  • DATABASE_API_BEARER_TOKEN
  • DB_API_PASSWORD
  • ENCRYPTION_KEY
  • GITHUB_APP_ID
  • GITHUB_APP_INSTALLATION_ID
  • GITHUB_APP_PRIVATE_KEY
  • GITHUB_SYNC_TOKEN
  • GOOGLE_API_KEY
  • GOOGLE_CLIENT_SECRET
  • INTEGRATIONS_BASECAMP_CLIENT_SECRET
  • INTEGRATIONS_BASECAMP_NEW_DOMAIN_CLIENT_SECRET
  • INTERCOM_IDENTITY_VERIFICATION_SECRET_KEY
  • JWT_SECRET
  • LICENSE_KEY
  • MAILGUN_API_KEY
  • OKTA_CLIENT_SECRET
  • PAGERDUTY_API_TOKEN
  • POSTGRES_PASSWORD
  • REDIS_PASSWORD
  • RETOOL_SALESFORCE_CONNECTED_APP_CLIENT_SECRET
  • RT_POSTGRES_PASSWORD
  • SANDBOX_LAMBDA_API_KEY
  • SCIM_AUTH_TOKEN
  • SLACK_API_TOKEN
  • STRIPE_SECRET_KEY
  • STRIPE_WEBHOOK_SECRET

Did this page help you?