RocketChat / RocketChat/Rocket.Chat

DOC: settings-via-env-vars somewhat lacking

Open
#19,860 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
46.1k
Forks
13.9k
Avg merge
3d 3h
Merged PRs (30d)
130

Description

Description:

( Documentation issue, probably)

We are using env-variables to configure rocket.chat. We noticed that after first start, changing the env variables and restarting the Rocker.Chat won't apply the new values, which is a bit different compared to any other services we are using. Apparently, this document has some stuff missing that could explain how people are supposed to configure Rocket.Chat: https://docs.rocket.chat/guides/administrator-guides/settings-via-env-vars

The doc says "To set a setting you need only to add the env var SETTING_ID=VALUE when starting the server." and then "You can overwrite any setting by setting an environment variable prefixed with: OVERWRITE_SETTING_". We are not quite sure what gets overwritten and why would we want to overwrite anything? This forum post does probably answer the question:
https://forums.rocket.chat/t/server-configuration-version-control-best-practice/238

Why can't we just change the value of the original environment variable - like in any other service? Are we really supposed to first configure rocket.chat using the "plain" environment variables - and if we later need to change the values, we should change the environment variables to start with ""OVERWRITE_SETTING_". Reading the docs, it's a bit hard to find out what's the reasoning for this exceptional way of configuring Rocket.Chat.

As a fix the documentation could at least be enhanced to explain the stuff that the forum post did.

Steps to reproduce:
  1. probably not needed for a documentation issue
Expected behavior:

probably not needed for a documentation issue

Actual behavior:

probably not needed for a documentation issue

Server Setup Information:
  • Version of Rocket.Chat Server: probably not needed for a documentation issue
  • Operating System: probably not needed for a documentation issue
  • Deployment Method: probably not needed for a documentation issue
  • Number of Running Instances: probably not needed for a documentation issue
  • DB Replicaset Oplog: probably not needed for a documentation issue
  • NodeJS Version: probably not needed for a documentation issue
  • MongoDB Version: probably not needed for a documentation issue
Client Setup Information
  • Desktop App or Browser Version: probably not needed for a documentation issue
  • Operating System: probably not needed for a documentation issue
Additional context
Relevant logs:

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the settings-via-env-vars guide linked in the issue, then read the referenced forum post to understand the distinction between regular environment variables and OVERWRITE_SETTING_. Update the guide to explain why values may not change after restart, when each form should be used, and how the documented behavior should be verified.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.