Manage Settings Using Environmental Variables

Rocket.Chat allows you to manage workspace settings using environment variables instead of updating them through the admin UI or database. This approach is useful for automating deployments and maintaining consistent configurations across environments.

This guide explains how to configure settings with environment variables and outlines the supported data types.

Get a setting ID

To manage a setting using an environment variable, you need its setting ID.

Hover over a setting name in Administration > Workspace > Settings to view its ID in the tooltip.

Set environment variables

Each deployment method provides its own way to define environment variables. Refer to the appropriate guide:

1. Docker: Refer to Set Rocket.Chat deployment environment variable on Docker.

2. Kubernetes: Visit the Set Rocket.Chat deployment environment variable on Kubernetes guide.

3. Podman: Go to Set Rocket.Chat deployment environment variable on Podman.

The examples in this guide follow the Docker setup.

Configure settings with environment variables

Using environment variables in Rocket.Chat, you can:

• Set initial values for settings

• Override existing values

• Block settings from being changed

• Hide settings

The following sections describe each option.

Set the initial value for a setting

To define a setting value when the server starts for the first time, use:

SETTING_ID=VALUE

For example:

FileUpload_Storage_Type: GoogleCloudStorage

This applies only if the setting has not been configured previously in the UI or database. If the setting already has a value, use Overwrite the setting value.

Overwrite the setting value

To overwrite an existing setting value, prefix the setting ID with OVERWRITE_SETTING_. For example:

OVERWRITE_SETTING_FileUpload_Storage_Type: GoogleCloudStorage

Block settings

To prevent a setting from being changed through the UI or API, use SETTINGS_BLOCKED with a comma-separated list of setting IDs. For example:

SETTINGS_BLOCKED: FileUpload_Storage_Type,FileUpload_GoogleStorage_AccessId,FileUpload_GoogleStorage_Secret

To unblock any setting, remove it from the list and restart your Rocket.Chat server.

Hide settings

To hide sensitive settings from appearing in the workspace UI, use the SETTINGS_HIDDEN variable with a comma-separated list of setting IDs you want to hide: For example:

SETTINGS_HIDDEN: FileUpload_GoogleStorage_AccessId,FileUpload_GoogleStorage_Secret

Use this command with extreme caution. Avoid hiding settings required by the Rocket.Chat client, such as FileUpload_Storage_Type, as this can break functionality.

Setting metadata and data types

To use environment variables effectively, it helps to understand the structure of each setting. Each setting includes metadata like its ID, type, default value, and visibility. When setting values via environment variables, you must use the correct data type—e.g., string, boolean, number, etc.

Basic settings

Group settings

Enterprise settings

Color settings

Action settings

Code settings

Asset settings

SelectOption settings

Editor settings

Date settings

Statistics settings

Environment variables provide a controlled way to manage workspace settings during deployment. Use them to define initial values, enforce overrides, and restrict or hide settings where necessary. Always ensure that values match the expected data type.