Docs env var info (#43150)

enterprise/backend/src/metabase_enterprise/audit_db.clj

@@ -209,7 +209,7 @@
   :visibility :internal
   :setter     :none
   :audit      :never
-  :doc        false)
+  :doc        "Setting this environment variable to false can also come in handy when migrating environments, as it can simplify the migration process.")
 
 (def ^:constant SKIP_CHECKSUM_FLAG
   "If `last-analytics-checksum` is set to this value, we will skip calculating checksums entirely and *always* reload the

enterprise/backend/src/metabase_enterprise/llm/settings.clj

@@ -7,12 +7,14 @@
   (deferred-tru "The OpenAI Model (e.g. 'gpt-4', 'gpt-3.5-turbo')")
   :visibility :settings-manager
   :default "gpt-4-turbo-preview"
-  :export? false)
+  :export? false
+  :doc "This feature is experimental.")
 
 (defsetting ee-openai-api-key
   (deferred-tru "The OpenAI API Key used in Metabase Enterprise.")
   :visibility :settings-manager
-  :export? false)
+  :export? false
+  :doc "This feature is experimental.")
 
 (defsetting ee-ai-features-enabled
   (deferred-tru "Enable AI features.")
@@ -22,4 +24,5 @@
   :export? false
   :setter (fn [new-value]
             (when (some? (ee-openai-api-key))
-              (setting/set-value-of-type! :boolean :ee-ai-features-enabled new-value))))
+              (setting/set-value-of-type! :boolean :ee-ai-features-enabled new-value)))
+  :doc "This feature is experimental.")

enterprise/backend/src/metabase_enterprise/sso/integrations/sso_settings.clj

@@ -221,7 +221,8 @@ on your IdP, this usually looks something like `http://www.example.com/141xkex60
   :feature :sso-jwt
   :audit   :getter
   :setter  (comp (partial setting/set-value-of-type! :json :jwt-group-mappings)
-                 (partial mu/validate-throw validate-group-mappings)))
+                 (partial mu/validate-throw validate-group-mappings))
+  :doc "JSON object containing JWT to Metabase group mappings, where keys are JWT groups and values are lists of Metabase groups IDs.")
 
 (defsetting jwt-configured
   (deferred-tru "Are the mandatory JWT settings configured?")
@@ -242,7 +243,9 @@ on your IdP, this usually looks something like `http://www.example.com/141xkex60
   :getter  (fn []
              (if (jwt-configured)
                (setting/get-value-of-type :boolean :jwt-enabled)
-               false)))
+               false))
+  :doc "When set to true, will enable JWT authentication with the options configured in the MB_JWT_* variables.
+        This is for JWT SSO authentication, and has nothing to do with Static embedding, which is MB_EMBEDDING_SECRET_KEY.")
 
 (define-multi-setting-impl integrations.common/send-new-sso-user-admin-email? :ee
   :getter (fn [] (setting/get-value-of-type :boolean :send-new-sso-user-admin-email?))

src/metabase/cmd/resources/other-env-vars.md

@@ -257,13 +257,6 @@ Default: `200000`
 
 Maximum idle time for a connection, in milliseconds.
 
-### `MB_JETTY_MAXQUEUED`
-
-Type: integer<br>
-Default: _"FIX ME"_
-
-Maximum number of requests to be queued when all threads are busy.
-
 ### `MB_JETTY_MAXTHREADS`
 
 Type: integer<br>

src/metabase/driver/util.clj

@@ -124,7 +124,10 @@
   ;; Don't set the timeout too low -- I've had Circle fail when the timeout was 1000ms on *one* occasion.
   :default    (if config/is-test?
                 3000
-                10000))
+                10000)
+  :doc "Timeout in milliseconds for connecting to databases, both Metabase application database and data connections.
+        In case you're connecting via an SSH tunnel and run into a timeout, you might consider increasing this value
+        as the connections via tunnels have more overhead than connections without.")
 
 (defn- connection-error? [^Throwable throwable]
   (and (some? throwable)

src/metabase/models/login_history.clj

@@ -48,7 +48,9 @@
   :type       :boolean
   :visibility :internal
   :setter     :none
-  :default    true)
+  :default    true
+  :doc "This variable also controls the geocoding service that Metabase uses to know the location of your logged in users.
+        Setting this variable to false also disables this reverse geocoding functionality.")
 
 (def LoginHistory
   "Used to be the toucan1 model name defined using [[toucan.models/defmodel]], now it's a reference to the toucan2 model name.

src/metabase/public_settings.clj

@@ -322,7 +322,9 @@
   :visibility :internal
   :type       :string
   :feature    :whitelabel
-  :audit      :getter)
+  :audit      :getter
+  :doc "The base URL where dashboard notitification links will point to instead of the Metabase base URL.
+        Only applicable for users who utilize interactive embedding and subscriptions.")
 
 (defsetting deprecation-notice-version
   (deferred-tru "Metabase version for which a notice about usage of deprecated features has been shown.")
@@ -709,7 +711,10 @@ See [fonts](../configuring-metabase/fonts.md).")
   :type       :boolean
   :visibility :public
   :default    nil
-  :audit      :getter)
+  :audit      :getter
+  :doc "The user login session will always expire after the amount of time defined in MAX_SESSION_AGE (by default 2 weeks).
+        This overrides the “Remember me” checkbox when logging in.
+        Also see the Changing session expiration documentation page.")
 
 (defsetting version
   "Metabase's version info"
@@ -893,7 +898,9 @@ See [fonts](../configuring-metabase/fonts.md).")
                 (let [value (setting/get-value-of-type :positive-integer :attachment-table-row-limit)]
                   (if-not (pos-int? value)
                     20
-                    value))))
+                    value)))
+  :doc "Range: 1-100. To limit the total number of rows included in the file attachment
+        for an email dashboard subscription, use MB_UNAGGREGATED_QUERY_ROW_LIMIT.")
 
 ;; This is used by the embedding homepage
 (defsetting example-dashboard-id

src/metabase/query_processor/middleware/constraints.clj

@@ -33,7 +33,10 @@
   :export?        true
   :type           :integer
   :database-local :allowed
-  :audit          :getter)
+  :audit          :getter
+  :doc "Must be less than 1048575, and less than the number configured in MB_AGGREGATED_QUERY_ROW_LIMIT.
+        This environment variable also affects how many rows Metabase returns in dashboard subscription attachments.
+        See also MB_AGGREGATED_QUERY_ROW_LIMIT.")
 
 (setting/defsetting aggregated-query-row-limit
   (deferred-tru "Maximum number of rows to return for aggregated queries via the API.")
@@ -41,7 +44,10 @@
   :export?        true
   :type           :integer
   :database-local :allowed
-  :audit          :getter)
+  :audit          :getter
+  :doc "Must be less than 1048575. This environment variable also affects how many rows Metabase includes in dashboard subscription attachments.
+  This environment variable also affects how many rows Metabase includes in dashboard subscription attachments.
+  See also MB_UNAGGREGATED_QUERY_ROW_LIMIT.")
 
 (defn default-query-constraints
   "Default map of constraints that we apply on dataset queries executed by the api."

src/metabase/server/middleware/auth.clj

@@ -33,7 +33,10 @@
 
 (defsetting api-key
   "When set, this API key is required for all API requests."
-  :visibility :internal)
+  :visibility :internal
+  :doc "Middleware that enforces validation of the client via the request header X-Metabase-Apikey.
+        If the header is available, then it’s validated against MB_API_KEY.
+        When it matches, the request continues; otherwise it’s blocked with a 403 Forbidden response.")
 
 (defn static-api-key
   "We don't want to change the name of the setting from `MB_API_KEY`, but we want to differentiate this static key from

src/metabase/server/middleware/session.clj

@@ -104,8 +104,9 @@
                                 {:possible-values possible-session-cookie-samesite-values
                                  :session-cookie-samesite normalized-value
                                  :http-status 400})))))
-  :doc "See [Embedding Metabase in a different domain](../embedding/interactive-embedding.md#embedding-metabase-in-a-different-domain). Related to [MB_EMBEDDING_APP_ORIGIN](#mb_embedding_app_origin). Read more about [interactive Embedding](../embedding/interactive-embedding.md). Learn more about [SameSite cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite).
-")
+  :doc "See [Embedding Metabase in a different domain](../embedding/interactive-embedding.md#embedding-metabase-in-a-different-domain).
+        Related to [MB_EMBEDDING_APP_ORIGIN](#mb_embedding_app_origin). Read more about [interactive Embedding](../embedding/interactive-embedding.md).
+        Learn more about [SameSite cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite).")
 
 (defmulti default-session-cookie-attributes
   "The appropriate cookie attributes to persist a newly created Session to `response`."

src/metabase/task/truncate_audit_tables.clj

@@ -60,7 +60,15 @@
                       min-retention-days)
 
                     :else
-                    env-var-value))))
+                    env-var-value)))
+  :doc "Sets the maximum number of days Metabase preserves rows for the following application database tables:
+
+- `query_execution`
+- `audit_log`
+- `view_log`
+
+Twice a day, Metabase will delete rows older than this threshold. The minimum value is 30 days (Metabase will treat entered values of 1 to 29 the same as 30).
+If set to 0, Metabase will keep all rows.")
 
 (defn- truncate-table!
   "Given a model, deletes all rows older than the configured threshold"

test/metabase/cmd/env_var_dox_test.clj

@@ -13,7 +13,7 @@
                                ns-set))
 
 (def admin-email-docs "### `MB_ADMIN_EMAIL`\n\n- Type: string\n- Default: `null`\n- [Configuration file name](./config-file.md): `admin-email`\n\nThe email address users should be referred to if they encounter a problem.")
-(def aggregated-query-row-limit-docs "### `MB_AGGREGATED_QUERY_ROW_LIMIT`\n\n- Type: integer\n- Default: `10000`\n- [Exported as](../installation-and-operation/serialization.md): `aggregated-query-row-limit`.\n- [Configuration file name](./config-file.md): `aggregated-query-row-limit`\n\nMaximum number of rows to return for aggregated queries via the API.")
+(def aggregated-query-row-limit-docs "### `MB_AGGREGATED_QUERY_ROW_LIMIT`\n\n- Type: integer\n- Default: `10000`\n- [Exported as](../installation-and-operation/serialization.md): `aggregated-query-row-limit`.\n- [Configuration file name](./config-file.md): `aggregated-query-row-limit`\n\nMaximum number of rows to return for aggregated queries via the API.\n\nMust be less than 1048575. This environment variable also affects how many rows Metabase includes in dashboard subscription attachments.\n  This environment variable also affects how many rows Metabase includes in dashboard subscription attachments.\n  See also MB_UNAGGREGATED_QUERY_ROW_LIMIT.")
 
 (def expected-docs (str/join "\n\n"
                              [admin-email-docs