Skip to content

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

Expand .env.example with Global Context and Local Development sections (#66625)

Nemanja Glumac2164c3bb2047
diff --git a/.env.example b/.env.example
index 83d4494cd1c..4ff1de51962 100644
--- a/.env.example
+++ b/.env.example
@@ -15,10 +15,34 @@
#
# Full Metabase environment configuration reference:
# https://www.metabase.com/docs/latest/configuring-metabase/environment-variables
+#
+# ⚠️ Make sure the same var is not exported multiple times in different contexts.
+
+
+# ==============================================================================
+# 1. GLOBAL CONTEXT
+# ==============================================================================
+#
+# Shared credentials and tokens used across multiple dev workflows.
+
+# GitHub - For gh CLI, API access, and CI integrations
+# https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
+# GITHUB_TOKEN=your-PAT
+
+# AWS - For S3, Athena, Redshift, and other AWS services
+# https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html
+# AWS_ACCESS_KEY_ID=your-access-key
+# AWS_SECRET_ACCESS_KEY=your-secret-key
+# AWS_REGION=us-east-1
+
+# Docker Hub - Avoid rate limits when pulling images
+# https://docs.docker.com/security/for-developers/access-tokens/
+# DOCKER_USERNAME=your-username
+# DOCKER_PASSWORD=your-access-token
# ==============================================================================
-# 1. E2E / CYPRESS TESTING
+# 2. E2E / CYPRESS TESTING
# ==============================================================================
#
# Configuration for running Cypress end-to-end tests locally.
@@ -30,7 +54,7 @@
# You don't _have to_ export any of these vars (except for the tokens below).
# Things will still work.
-# 1.1. E2E Application Database (H2 required)
+# 2.1. E2E Application Database (H2 required)
# ------------------------------------------------------------------------------
# Whether to run the enterprise or the open-source Metabase version
@@ -42,7 +66,7 @@ MB_DB_FILE="./e2e/tmp/cypress-test.db"
# Where does Cypress go to look for the application?
MB_JETTY_PORT=4000
-# 1.2 E2E Local Runner Setup
+# 2.2 E2E Local Runner Setup
# ------------------------------------------------------------------------------
# Whether to run true e2e test suite, or SDK component tests (e2e | component)
@@ -61,7 +85,7 @@ GENERATE_SNAPSHOTS="true"
# Hint: build the JAR with ./bin/build.sh
# JAR_PATH="target/uberjar/metabase.jar"
-# 1.3 E2E Tokens
+# 2.3 E2E Tokens
# ------------------------------------------------------------------------------
#
# These make sense for Metabase core devs only
@@ -72,7 +96,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"
-# 1.4 E2E Misc.
+# 2.4 E2E Misc.
# ------------------------------------------------------------------------------
# To make Node.js match the instance tz
@@ -82,3 +106,55 @@ 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"
+
+# Slack for testing alerts and pulses
+# https://api.slack.com/messaging/webhooks
+SLACK_WEBHOOK_URL="op://qzcmvvcryrgijigzl2f6xlabhu/SLACK_WEBHOOK_URL/password"
+
+# 3.3 Feature Flags & Tokens
+# ------------------------------------------------------------------------------
+
+# Use staging server for license validation (avoids hitting production)
+METASTORE_DEV_SERVER_URL="https://token-check.staging.metabase.com"
+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"