Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

docs: improve .env.example docs (#67545)

Jakub Chodorowiczd0327d0b4b2c
diff --git a/.env.example b/.env.example
index c19ce16edfa..e271ad702ad 100644
--- a/.env.example
+++ b/.env.example
@@ -40,9 +40,60 @@
# DOCKER_USERNAME=your-username
# DOCKER_PASSWORD=your-access-token
+# ==============================================================================
+# 2. LOCAL METABASE DEVELOPMENT
+# ==============================================================================
+#
+# Settings for running Metabase locally. Most have sensible defaults—only
+# configure what you need.
+
+# 2.1 Application Database
+# ------------------------------------------------------------------------------
+# Where Metabase stores its own data (dashboards, users, settings, etc.).
+# https://www.metabase.com/docs/latest/installation-and-operation/configuring-application-database
+
+# Option A: Individual connection parameters
+# MB_DB_TYPE="postgres"
+# MB_DB_HOST="localhost"
+# MB_DB_PORT=5432
+# MB_DB_DBNAME="metabase"
+# MB_DB_USER="<username>"
+# MB_DB_PASS="<password>"
+
+# Option B: Single connection URI (overrides individual params)
+# MB_DB_CONNECTION_URI="jdbc:postgresql://localhost:5432/metabase?user=<username>&password=<password>"
+
+# 2.2 Server & Integrations
+# ------------------------------------------------------------------------------
+# https://www.metabase.com/docs/latest/configuring-metabase/customizing-jetty-webserver
+
+# Jetty server (defaults: localhost:3000)
+# MB_JETTY_HOST="localhost"
+# MB_JETTY_PORT=3000
+
+# SMTP for testing email notifications (use with maildev/maildev container)
+MB_EMAIL_SMTP_HOST="localhost"
+MB_EMAIL_SMTP_PORT=1025
+MB_EMAIL_SMTP_USERNAME="admin"
+MB_EMAIL_SMTP_PASSWORD="admin"
+
+# 2.3 Feature Flags & Tokens
+# ------------------------------------------------------------------------------
+
+# Use staging server for license validation (avoids hitting production)
+METASTORE_DEV_SERVER_URL="https://token-check.staging.metabase.com"
+
+# Metabase license token
+# Uncomment this line only when running local dev and NEVER when running Cypress
+# Tests need to start from zero, and set different tokens programmatically (on-demand)
+# MB_PREMIUM_EMBEDDING_TOKEN="op://Shared/Metabase License Dev Tokens/Licenses/MB_ALL_FEATURES_TOKEN"
+
+# Skip embedding SDK build for faster frontend compilation
+# SKIP_EMBEDDING_SDK="true"
+
# ==============================================================================
-# 2. E2E / CYPRESS TESTING
+# 3. E2E / CYPRESS TESTING
# ==============================================================================
#
# Configuration for running Cypress end-to-end tests locally.
@@ -54,19 +105,20 @@
# You don't _have to_ export any of these vars (except for the tokens below).
# Things will still work.
-# 2.1. E2E Application Database (H2 required)
+# 3.1. E2E Application Database (H2 required)
# ------------------------------------------------------------------------------
# Whether to run the enterprise or the open-source Metabase version
MB_EDITION="ee"
# Which file to use for the ephemeral testing application database?
-MB_DB_FILE="./e2e/tmp/cypress-test.db"
+# MB_DB_FILE="./e2e/tmp/cypress-test.db"
-# Where does Cypress go to look for the application?
-MB_JETTY_PORT=4000
+# Where does Cypress go to look for the application? (defaults: localhost:4000)
+# MB_JETTY_HOST="localhost"
+# MB_JETTY_PORT=4000
-# 2.2 E2E Local Runner Setup
+# 3.2 E2E Local Runner Setup
# ------------------------------------------------------------------------------
# Whether to run true e2e test suite, or SDK component tests (e2e | component)
@@ -85,7 +137,7 @@ GENERATE_SNAPSHOTS="true"
# Hint: build the JAR with ./bin/build.sh
# JAR_PATH="target/uberjar/metabase.jar"
-# 2.3 E2E Tokens
+# 3.3 E2E Tokens
# ------------------------------------------------------------------------------
#
# These make sense for Metabase core devs only
@@ -96,7 +148,7 @@ CYPRESS_MB_STARTER_CLOUD_TOKEN="op://Shared/Metabase License Dev Tokens/Licenses
CYPRESS_MB_PRO_CLOUD_TOKEN="op://Shared/Metabase License Dev Tokens/Licenses/MB_PRO_CLOUD_TOKEN"
CYPRESS_MB_PRO_SELF_HOSTED_TOKEN="op://Shared/Metabase License Dev Tokens/Licenses/MB_PRO_SELF_HOSTED_TOKEN"
-# 2.4 E2E Misc.
+# 3.4 E2E Misc.
# ------------------------------------------------------------------------------
# To make Node.js match the instance tz
@@ -106,55 +158,3 @@ TZ="US/Pacific"
# DO NOT USE Docker Desktop. Use Orbstack instead. Metabase will fail to connect
# to the dockerized Mongo QA database otherwise.
EXPERIMENTAL_DOCKER_DESKTOP_FORCE_QEMU=1
-
-
-# ==============================================================================
-# 3. LOCAL METABASE DEVELOPMENT
-# ==============================================================================
-#
-# Settings for running Metabase locally. Most have sensible defaults—only
-# configure what you need.
-
-# 3.1 Application Database
-# ------------------------------------------------------------------------------
-# Where Metabase stores its own data (dashboards, users, settings, etc.).
-# https://www.metabase.com/docs/latest/installation-and-operation/configuring-application-database
-
-# Option A: Individual connection parameters
-# MB_DB_TYPE="postgres"
-# MB_DB_HOST="localhost"
-# MB_DB_PORT=5432
-# MB_DB_DBNAME="metabase"
-# MB_DB_USER="<username>"
-# MB_DB_PASS="<password>"
-
-# Option B: Single connection URI (overrides individual params)
-# MB_DB_CONNECTION_URI="jdbc:postgresql://localhost:5432/metabase?user=<username>&password=<password>"
-
-# 3.2 Server & Integrations
-# ------------------------------------------------------------------------------
-# https://www.metabase.com/docs/latest/configuring-metabase/customizing-jetty-webserver
-
-# Jetty server (defaults: localhost:3000)
-# MB_JETTY_HOST="localhost"
-# MB_JETTY_PORT=3000
-
-# SMTP for testing email notifications (use with maildev/maildev container)
-MB_EMAIL_SMTP_HOST="localhost"
-MB_EMAIL_SMTP_PORT=1025
-MB_EMAIL_SMTP_USERNAME="admin"
-MB_EMAIL_SMTP_PASSWORD="admin"
-
-# 3.3 Feature Flags & Tokens
-# ------------------------------------------------------------------------------
-
-# Use staging server for license validation (avoids hitting production)
-METASTORE_DEV_SERVER_URL="https://token-check.staging.metabase.com"
-
-# Metabase license token
-# Uncomment this line only when running local dev and NEVER when running Cypress
-# Tests need to start from zero, and set different tokens programmatically (on-demand)
-# MB_PREMIUM_EMBEDDING_TOKEN="op://Shared/Metabase License Dev Tokens/Licenses/MB_ALL_FEATURES_TOKEN"
-
-# Skip embedding SDK build for faster frontend compilation
-# SKIP_EMBEDDING_SDK="true"