From dee2eb852ceb8773f8ed4e3c1ece60e5c93b38f8 Mon Sep 17 00:00:00 2001
From: Kyle Doherty <kdoh@users.noreply.github.com>
Date: Wed, 18 Mar 2020 14:48:12 -0700
Subject: [PATCH] Carry along - Add environment variables documentation
(#11550) (#11764)
* add environment variables
* Admin Panel > SuperAdmin
* simplify explanatory copy
Co-authored-by: Dustin Miller <dustin@sharepointexperts.com>
---
.../operations-guide/environment-variables.md | 61 +++++++++++++++++++
docs/operations-guide/start.md | 1 +
src/metabase/models/setting.clj | 6 +-
3 files changed, 65 insertions(+), 3 deletions(-)
create mode 100644 docs/operations-guide/environment-variables.md
diff --git a/docs/operations-guide/environment-variables.md b/docs/operations-guide/environment-variables.md
new file mode 100644
index 00000000000..1f3815ecf8a
--- /dev/null
+++ b/docs/operations-guide/environment-variables.md
@@ -0,0 +1,61 @@
+# Environment variables
+
+Most settings in Metabase can viewed and modified in the Admin Panel, or set via environment variables. The environment variables always take precedence.
+
+| Environment Variable | Type | Default at install | Description |
+| ------------------------------------------ | ---------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| MB_ABANDONMENT_EMAIL_SENT | boolean | `false` | Have we sent an abandonment email to the instance admin? |
+| MB_ADMIN_EMAIL | string | `null` | The email address users should be referred to if they encounter a problem. |
+| MB_ANON_TRACKING_ENABLED | boolean | `true` | Enable the collection of anonymous usage data in order to help Metabase improve. |
+| MB_BREAKOUT_BIN_WIDTH | double | `10.0` | When using the default binning strategy for a field of type Coordinate (such as Latitude and Longitude), this number will be used as the default bin width (in degrees). |
+| MB_BREAKOUT_BINS_NUM | integer | `8` | When using the default binning strategy and a number of bins is not provided, this number will be used as the default. |
+| MB_CHECK_FOR_UPDATES | boolean | `true` | Identify when new versions of Metabase are available. |
+| MB_CUSTOM_FORMATTING | JSON | `{}` | Object keyed by type, containing formatting settings |
+| MB_CUSTOM_GEOJSON | JSON | `{}` | JSON containing information about custom GeoJSON files for use in map visualizations instead of the default US State or World GeoJSON. |
+| MB_EMAIL_FROM_ADDRESS | string | `null` | Email address you want to use as the sender of Metabase. |
+| MB_EMAIL_SMTP_HOST | string | `null` | The address of the SMTP server that handles your emails. |
+| MB_EMAIL_SMTP_PASSWORD | string | `null` | SMTP password. |
+| MB_EMAIL_SMTP_PORT | int | `25` | The port your SMTP server uses for outgoing emails. |
+| MB_EMAIL_SMTP_SECURITY | string | `null` | SMTP secure connection protocol. (tls, ssl, starttls, or none) |
+| MB_EMAIL_SMTP_USERNAME | string | `null` | SMTP username. |
+| MB_EMBEDDING_SECRET_KEY | string | `null` | Secret key used to sign JSON Web Tokens for requests to `/api/embed` endpoints. |
+| MB_ENABLE_EMBEDDING | boolean | `false` | Allow admins to securely embed questions and dashboards within other applications? |
+| MB_ENABLE_NESTED_QUERIES | boolean | `true` | Allow using a saved question as the source for other queries? |
+| MB_ENABLE_PUBLIC_SHARING | boolean | `false` | Enable admins to create publicly viewable links (and embeddable iframes) for Questions and Dashboards? |
+| MB_ENABLE_QUERY_CACHING | boolean | `false` | Enabling caching will save the results of queries that take a long time to run. |
+| MB_ENABLE_XRAYS | boolean | `true` | Allow users to explore data using X-rays |
+| MB_FOLLOW_UP_EMAIL_SENT | boolean | `false` | Have we sent a follow up email to the instance admin? |
+| MB_GOOGLE_AUTH_AUTO_CREATE_ACCOUNTS_DOMAIN | string | `null` | When set, allow users to sign up on their own if their Google account email address is from this domain. |
+| MB_GOOGLE_AUTH_CLIENT_ID | string | `null` | Client ID for Google Auth SSO. If this is set, Google Auth is considered to be enabled. |
+| MB_HUMANIZATION_STRATEGY | string (`advanced`, `simple`, or `none`) | `"advanced"` | Metabase can attempt to transform your table and field names into more sensible, human-readable versions, e.g. "somehorriblename" becomes "Some Horrible Name". This doesn’t work all that well if the names are in a language other than English, however. Do you want us to take a guess? |
+| MB_LDAP_ATTRIBUTE_EMAIL | string | `"mail"` | Attribute to use for the users email. (usually 'mail', 'email' or 'userPrincipalName') |
+| MB_LDAP_ATTRIBUTE_FIRSTNAME | string | `"givenName"` | Attribute to use for the user's first name. (usually 'givenName') |
+| MB_LDAP_ATTRIBUTE_LASTNAME | string | `"sn"` | Attribute to use for the user's last name. (usually 'sn') |
+| MB_LDAP_BIND_DN | string | `null` | The Distinguished Name to bind as (if any), this user will be used to lookup information about other users. |
+| MB_LDAP_ENABLED | boolean | `false` | Enable LDAP authentication. |
+| MB_LDAP_GROUP_BASE | string | `null` | Search base for groups, not required if your LDAP directory provides a 'memberOf' overlay. (Will be searched recursively) |
+| MB_LDAP_GROUP_MAPPINGS | JSON | `{}` | JSON containing LDAP to Metabase group mappings. |
+| MB_LDAP_GROUP_SYNC | boolean | `false` | Enable group membership synchronization with LDAP. |
+| MB_LDAP_HOST | string | `null` | Server hostname. |
+| MB_LDAP_PASSWORD | string | `null` | The password to bind with for the lookup user. |
+| MB_LDAP_PORT | string | `"389"` | Server port, usually 389 or 636 if SSL is used. |
+| MB_LDAP_SECURITY | string | `"none"` | Use SSL, TLS or plain text. |
+| MB_LDAP_USER_BASE | string | `null` | Search base for users. (Will be searched recursively) |
+| MB_LDAP_USER_FILTER | string | `(&(objectClass=inetOrgPerson)(|(uid={login})(mail={login})))` | User lookup filter, the placeholder {login} will be replaced by the user supplied login. |
+| MB_MAP_TILE_SERVER_URL | string | `http://{s}.tile.openstreetmap.org/` `{z}/{x}/{y}.png` | The map tile server URL template used in map visualizations, for example from OpenStreetMaps or MapBox. |
+| MB_MAX_SIMULTANEOUS_QUERIES_PER_DB | integer | `15` | Maximum number of simultaneous queries to allow per connected Database. |
+| MB_METABOT_ENABLED | boolean | `false` | Enable MetaBot, which lets you search for and view your saved questions directly via Slack. |
+| MB_METABOT_INSTANCE_LAST_CHECKIN | string | `null` | Timestamp of the last time the active MetaBot instance checked in. |
+| MB_METABOT_INSTANCE_UUID | string | `null` | UUID of the active MetaBot instance (the Metabase process currently handling MetaBot duties.) |
+| MB_PREMIUM_EMBEDDING_TOKEN | string | `null` | Token for premium features. Go to the MetaStore to get yours! |
+| MB_QUERY_CACHING_MAX_KB | integer | `1000` | The maximum size of the cache, per saved question, in kilobytes: |
+| MB_QUERY_CACHING_MAX_TTL | integer | `8640000` (100 days, in seconds) | The absolute maximum time to keep any cached query results, in seconds. |
+| MB_QUERY_CACHING_MIN_TTL | integer | `60` | Metabase will cache all saved questions with an average query execution time longer than this many seconds: |
+| MB_QUERY_CACHING_TTL_RATIO | integer | `10` | To determine how long each saved question's cached result should stick around, we take the query's average execution time and multiply that by whatever you input here.So if a query takes on average 2 minutes to run, and you input 10 for your multiplier, its cache entry will persist for 20 minutes. |
+| MB_REPORT_TIMEZONE | string | `null` | Connection timezone to use when executing queries. Defaults to system timezone. |
+| MB_SITE_LOCALE | string | `"en"` | The default language for this Metabase instance. This only applies to emails, Pulses, etc. Users' browsers will specify the language used in the user interface. |
+| MB_SITE_NAME | string | `"Metabase"` | The name used for this instance of Metabase. |
+| MB_SITE_URL | string | `null` | The base URL of this Metabase instance, e.g. "http://metabase.my-company.com". |
+| MB_SLACK_TOKEN | string | `null` | Slack API bearer token obtained from https://api.slack.com/web#authentication |
+| MB_SOURCE_ADDRESS_HEADER | string | `X-Forwarded-For` | Identify the source of HTTP requests by this headers value, instead of its remote address. |
+| MB_SSL_CERTIFICATE_PUBLIC_KEY | string | `null` | Base-64 encoded public key for this sites SSL certificate.Specify this to enable HTTP Public Key Pinning.See http://mzl.la/1EnfqBf for more information. |
diff --git a/docs/operations-guide/start.md b/docs/operations-guide/start.md
index 0f1f848bc6f..6036d529e99 100644
--- a/docs/operations-guide/start.md
+++ b/docs/operations-guide/start.md
@@ -6,6 +6,7 @@ This guide contains detailed information about how to install and configure Meta
* [How to install Metabase](installing-metabase.md)
* [How to upgrade Metabase](upgrading-metabase.md)
+* [Configuring settings using environment variables](environment-variables.md)
* [Configuring the application database](configuring-application-database.md)
* [Connecting Metabase to databases in your organization](../administration-guide/01-managing-databases.md)
* [Migrating from using the H2 database to MySQL or Postgres](migrating-from-h2.md)
diff --git a/src/metabase/models/setting.clj b/src/metabase/models/setting.clj
index d07210ca18d..706b3329504 100644
--- a/src/metabase/models/setting.clj
+++ b/src/metabase/models/setting.clj
@@ -15,8 +15,8 @@
(require '[metabase.models.setting :as setting])
- (setting/get :mandrill-api-key) ; only returns values set explicitly from SuperAdmin
- (mandrill-api-key) ; returns value set in SuperAdmin, OR value of corresponding env var,
+ (setting/get :mandrill-api-key) ; only returns values set explicitly from the Admin Panel
+ (mandrill-api-key) ; returns value set in the Admin Panel, OR value of corresponding env var,
; OR the default value, if any (in that order)
(setting/set! :mandrill-api-key \"NEW_KEY\")
@@ -501,7 +501,7 @@
(mandrill-api-key new-value) ; update the value
(mandrill-api-key nil) ; delete the value
- A setting can be set from the SuperAdmin page or via the corresponding env var, eg. `MB_MANDRILL_API_KEY` for the
+ A setting can be set from the Admin Panel or via the corresponding env var, eg. `MB_MANDRILL_API_KEY` for the
example above.
You may optionally pass any of the OPTIONS below:
--
GitLab