Skip to content

environment-variables.mdx

Latest commit

 

History

History
727 lines (583 loc) · 79.5 KB

environment-variables.mdx

File metadata and controls

727 lines (583 loc) · 79.5 KB
title Environment variables
mode wide
🛠 This page is for engineering teams self-hosting their own Lightdash instance. If you want to configure any of these settings, please speak to the Lightdash team or your Lightdash administrators.

This is a reference to all environment variables that can be used to configure a Lightdash deployment.

Variable Description
PGHOST (Required) Hostname of postgres server to store Lightdash data
PGPORT (Required) Port of postgres server to store Lightdash data
PGUSER (Required) Username of postgres user to access postgres server to store Lightdash data
PGPASSWORD (Required) Password for PGUSER
PGDATABASE (Required) Database name inside postgres server to store Lightdash data
PGCONNECTIONURI Connection URI for postgres server to store Lightdash data in the format postgresql://user:password@host:port/db?params. This is an alternative to providing the previous PG variables.
PGMAXCONNECTIONS Maximum number of connections to the database
PGMINCONNECTIONS Minimum number of connections to the database
LIGHTDASH_SECRET (Required) Secret key used to secure various tokens in Lightdash. This must be fixed between deployments. If the secret changes, you won't have access to Lightdash data.
SECURE_COOKIES Only allows cookies to be stored over a https connection. We use cookies to keep you logged in. This is recommended to be set to true in production. (default=false)
COOKIES_MAX_AGE_HOURS How many hours a user session exists before the user is automatically signed out. For example if 24, then the user will be automatically after 24 hours of inactivity.
TRUST_PROXY This tells the Lightdash server that it can trust the X-Forwarded-Proto header it receives in requests. This is useful if you use SECURE_COOKIES=true behind a HTTPS terminated proxy that you can trust. (default=false)
SITE_URL Site url where Lightdash is being hosted. It should include the protocol. E.g https://lightdash.mycompany.com (default=http://localhost:8080)
INTERNAL_LIGHTDASH_HOST Internal Lightdash host for the Headless browser to send requests when your Lightdash instance is not accessible from the Internet. Needs to support https if SECURE_COOKIES=true (default=Same as SITE_URL)
STATIC_IP Server static IP so users can add the IP to their warehouse allow-list. (default=http://localhost:8080)
LIGHTDASH_QUERY_MAX_LIMIT Query max rows limit (default=5000)
LIGHTDASH_QUERY_DEFAULT_LIMIT Default number of rows to return in a query (default=500)
LIGHTDASH_QUERY_MAX_PAGE_SIZE Maximum page size for paginated queries (default=2500)
SCHEDULER_ENABLED Enables/Disables the scheduler worker that triggers the scheduled deliveries. (default=true)
SCHEDULER_CONCURRENCY How many scheduled delivery jobs can be processed concurrently. (default=3)
SCHEDULER_JOB_TIMEOUT After how many milliseconds the job should be timeout so the scheduler worker can pick other jobs. (default=600000, 10 minutes)
SCHEDULER_SCREENSHOT_TIMEOUT Timeout in milliseconds for taking screenshots
SCHEDULER_INCLUDE_TASKS Comma-separated list of scheduler tasks to include
SCHEDULER_EXCLUDE_TASKS Comma-separated list of scheduler tasks to exclude
LIGHTDASH_CSV_CELLS_LIMIT Max cells on CSV file exports (default=100000)
LIGHTDASH_CHART_VERSION_HISTORY_DAYS_LIMIT Configure how far back the chart versions history goes in days (default=3)
LIGHTDASH_PIVOT_TABLE_MAX_COLUMN_LIMIT Configure maximum number of columns in pivot table (default=200)
GROUPS_ENABLED Enables/Disables groups functionality (default=false)
CUSTOM_VISUALIZATIONS_ENABLED Enables/Disables custom chart functionality (default=false)
LIGHTDASH_MAX_PAYLOAD Maximum HTTP request body size (default=5mb)
LIGHTDASH_LICENSE_KEY License key for Lightdash Enterprise Edition. See Enterprise License Keys for details. Get your license key
HEADLESS_BROWSER_HOST Hostname for the headless browser
HEADLESS_BROWSER_PORT Port for the headless browser (default=3001)
ALLOW_MULTIPLE_ORGS If set to true, new users registering on Lightdash will have their own organization, separated from others (default=false)
LIGHTDASH_MODE Mode for Lightdash (default, demo, pr, etc.) (default=default)
DISABLE_PAT Disables Personal Access Tokens (default=false)
PAT_ALLOWED_ORG_ROLES Comma-separated list of organization roles allowed to use Personal Access Tokens (default=All roles)
PAT_MAX_EXPIRATION_TIME_IN_DAYS Maximum expiration time in days for Personal Access Tokens
MAX_DOWNLOADS_AS_CODE Maximum number of downloads as code (default=100)
EXTENDED_USAGE_ANALYTICS Enables extended usage analytics (default=false)
USE_SECURE_BROWSER Use secure WebSocket connections for headless browser (default=false)
DISABLE_DASHBOARD_COMMENTS Disables dashboard comments (default=false)
ORGANIZATION_WAREHOUSE_CREDENTIALS_ENABLED Enables organization warehouse settings (default=false)
HEADWAY_ENABLED Enables the Headway changelogs widget in the Lightdash menu (default=true)
SAVED_METRICS_TREE_ENABLED Enables Saved Trees in the Metrics Canvas view (default=false)

Lightdash also accepts all standard postgres environment variables

Athena

Variable Description
ATHENA_WAREHOUSE_IAM_ROLE_AUTH Set to true to enable IAM role authentication for Athena warehouse connections. When enabled, users can choose between Access Keys and IAM Role auth in the connection form. IAM Role auth uses the AWS default credential chain (e.g. ECS task role, EC2 instance profile) instead of explicit access keys. Default: false.

Snowflake

Variable Description
SNOWFLAKE_WAREHOUSE_ERROR_MESSAGE Custom error message displayed when users encounter Snowflake warehouse access errors. Use {warehouseName} as a placeholder for the actual warehouse name. Example: You don't have access to warehouse {warehouseName}. Please reach out to your admin.
SNOWFLAKE_UNAUTHORIZED_ERROR_MESSAGE Custom error message displayed when users encounter Snowflake authorization errors (e.g., "Object does not exist or not authorized"). Use {snowflakeTable} and {snowflakeSchema} as placeholders. Example: You don't have access to the {snowflakeTable} table. Please go to '{snowflakeSchema}' and request access.

SMTP

This is a reference to all the SMTP environment variables that can be used to configure a Lightdash email client.

Variable Description
EMAIL_SMTP_HOST (Required) Hostname of email server
EMAIL_SMTP_PORT Port of email server (default=587)
EMAIL_SMTP_SECURE Secure connection (default=true)
EMAIL_SMTP_USER (Required) Auth user
EMAIL_SMTP_PASSWORD Auth password [1]
EMAIL_SMTP_ACCESS_TOKEN Auth access token for Oauth2 authentication [1]
EMAIL_SMTP_ALLOW_INVALID_CERT Allow connection to TLS server with self-signed or invalid TLS certificate (default=false)
EMAIL_SMTP_SENDER_EMAIL (Required) The email address that sends emails
EMAIL_SMTP_SENDER_NAME The name of the email address that sends emails (default=Lightdash)
EMAIL_SMTP_IMAGE_INLINE_CID Embed images directly into emails as CID attachments instead of referencing external URLs. Useful for deployments behind firewalls where email clients cannot reach internal image URLs (default=false)

[1] EMAIL_SMTP_PASSWORD or EMAIL_SMTP_ACCESS_TOKEN needs to be provided

SSO

These variables enable you to control Single Sign On (SSO) functionality.

Variable Description
AUTH_DISABLE_PASSWORD_AUTHENTICATION If "true" disables signing in with plain passwords (default=false)
AUTH_ENABLE_GROUP_SYNC If "true" enables assigning SSO groups to Lightdash groups (default=false)
AUTH_ENABLE_OIDC_LINKING Enables linking a new OIDC identity to an existing user if they already have another OIDC with the same email (default=false)
AUTH_ENABLE_OIDC_TO_EMAIL_LINKING Enables linking OIDC identity to an existing user by email. Required when using SCIM with SSO (default=false)
AUTH_GOOGLE_OAUTH2_CLIENT_ID Required for Google SSO
AUTH_GOOGLE_OAUTH2_CLIENT_SECRET Required for Google SSO
AUTH_OKTA_OAUTH_CLIENT_ID Required for Okta SSO
AUTH_OKTA_OAUTH_CLIENT_SECRET Required for Okta SSO
AUTH_OKTA_OAUTH_ISSUER Required for Okta SSO
AUTH_OKTA_DOMAIN Required for Okta SSO
AUTH_OKTA_AUTHORIZATION_SERVER_ID Optional for Okta SSO with a custom authorization server
AUTH_OKTA_EXTRA_SCOPES Optional for Okta SSO scopes (e.g. groups) without a custom authorization server
AUTH_ONE_LOGIN_OAUTH_CLIENT_ID Required for One Login SSO
AUTH_ONE_LOGIN_OAUTH_CLIENT_SECRET Required for One Login SSO
AUTH_ONE_LOGIN_OAUTH_ISSUER Required for One Login SSO
AUTH_AZURE_AD_OAUTH_CLIENT_ID Required for Azure AD
AUTH_AZURE_AD_OAUTH_CLIENT_SECRET Required for Azure AD
AUTH_AZURE_AD_OAUTH_TENANT_ID Required for Azure AD
AUTH_AZURE_AD_OIDC_METADATA_ENDPOINT Optional for Azure AD
AUTH_AZURE_AD_X509_CERT_PATH Optional for Azure AD
AUTH_AZURE_AD_X509_CERT Optional for Azure AD
AUTH_AZURE_AD_PRIVATE_KEY_PATH Optional for Azure AD
AUTH_AZURE_AD_PRIVATE_KEY Optional for Azure AD
DATABRICKS_OAUTH_CLIENT_ID Client ID for Databricks OAuth
DATABRICKS_OAUTH_CLIENT_SECRET Client secret for Databricks OAuth (optional)
DATABRICKS_OAUTH_AUTHORIZATION_ENDPOINT Authorization endpoint URL for Databricks OAuth
DATABRICKS_OAUTH_TOKEN_ENDPOINT Token endpoint URL for Databricks OAuth

S3

These variables allow you to configure S3 Object Storage, which is required to self-host Lightdash.

Variable Description
S3_ENDPOINT (Required) S3 endpoint for storing results
S3_BUCKET (Required) Name of the S3 bucket for storing files
S3_REGION (Required) Region where the S3 bucket is located
S3_ACCESS_KEY Access key for authenticating with the S3 bucket
S3_SECRET_KEY Secret key for authenticating with the S3 bucket
S3_USE_CREDENTIALS_FROM Configures the credential provider chain for AWS S3 authentication if access key and secret is not provided. Supports: env (environment variables), token_file (token file credentials), ini (initialization file credentials), ecs (container metadata credentials), ec2 (instance metadata credentials). Multiple values can be specified in order of preference.
S3_EXPIRATION_TIME Expiration time for scheduled deliveries files (default=259200, 3d)
S3_FORCE_PATH_STYLE Force path style addressing, needed for MinIO setup e.g. http://your.s3.domain/BUCKET/KEY instead of http://BUCKET.your.s3.domain/KEY (default=false)
RESULTS_S3_BUCKET Name of the S3 bucket used for storing query results (default=S3_BUCKET)
RESULTS_S3_REGION Region where the S3 query storage bucket is located (default=S3_REGION)
RESULTS_S3_ACCESS_KEY Access key for authenticating with the S3 query storage bucket (default=S3_ACCESS_KEY)
RESULTS_S3_SECRET_KEY Secret key for authenticating with the S3 query storage bucket (default=S3_SECRET_KEY)

Persistent download URLs

When enabled, CSV and dashboard ZIP exports return a stable Lightdash-hosted URL (e.g. https://lightdash.example.com/api/v1/file/{id}) instead of a direct S3 signed URL. Each time this URL is accessed, Lightdash generates a short-lived S3 signed URL and redirects to it — so the underlying URL never goes stale and download links survive IAM credential rotation.

Variable Description
PERSISTENT_DOWNLOAD_URLS_ENABLED Enables persistent download URLs (default=false)
PERSISTENT_DOWNLOAD_URL_EXPIRATION_SECONDS How long the persistent URL remains accessible (default=259200, 3 days). When persistent URLs are enabled, S3_EXPIRATION_TIME is ignored and each redirect generates a signed URL that expires after 5 minutes.
PERSISTENT_DOWNLOAD_URL_EXPIRATION_SECONDS_EMAIL Override expiration for email download links. Falls back to PERSISTENT_DOWNLOAD_URL_EXPIRATION_SECONDS when not set.
PERSISTENT_DOWNLOAD_URL_EXPIRATION_SECONDS_SLACK Override expiration for Slack download links. Falls back to PERSISTENT_DOWNLOAD_URL_EXPIRATION_SECONDS when not set.
PERSISTENT_DOWNLOAD_URL_EXPIRATION_SECONDS_MSTEAMS Override expiration for MS Teams download links. Falls back to PERSISTENT_DOWNLOAD_URL_EXPIRATION_SECONDS when not set.

Cache

Note that you will need an Enterprise License Key for this functionality.
Variable Description
RESULTS_CACHE_ENABLED Enables caching for chart results (default=false)
AUTOCOMPLETE_CACHE_ENABLED Enables caching for filter autocomplete results (default=false)
CACHE_STALE_TIME_SECONDS Defines how long cached results remain valid before being considered stale (default=86400, 24h)
These variables are **deprecated**; use the `RESULTS_S3_*` versions instead.
Variable Description
RESULTS_CACHE_S3_BUCKET Deprecated - use RESULTS_S3_BUCKET (default=S3_BUCKET)
RESULTS_CACHE_S3_REGION Deprecated - use RESULTS_S3_REGION (default=S3_REGION)
RESULTS_CACHE_S3_ACCESS_KEY Deprecated - use RESULTS_S3_ACCESS_KEY (default=S3_ACCESS_KEY)
RESULTS_CACHE_S3_SECRET_KEY Deprecated - use RESULTS_S3_SECRET_KEY (default=S3_SECRET_KEY)

Logging

Variable Description
LIGHTDASH_LOG_LEVEL The minimum level of log messages to show. DEBUG, AUDIT, HTTP, INFO, WARN ERROR (default=INFO)
LIGHTDASH_LOG_FORMAT The format of log messages. PLAIN, PRETTY, JSON (default=pretty)
LIGHTDASH_LOG_OUTPUTS The outputs to send log messages to (default=console)
LIGHTDASH_LOG_CONSOLE_LEVEL The minimum level of log messages to display on the console (default=LIGHTDASH_LOG_LEVEL)
LIGHTDASH_LOG_CONSOLE_FORMAT The format of log messages on the console (default=LIGHTDASH_LOG_FORMAT)
LIGHTDASH_LOG_FILE_LEVEL The minimum level of log messages to write to the log file (default=LIGHTDASH_LOG_LEVEL)
LIGHTDASH_LOG_FILE_FORMAT The format of log messages in the log file (default=LIGHTDASH_LOG_FORMAT)
LIGHTDASH_LOG_FILE_PATH The path to the log file. Requires LIGHTDASH_LOG_OUTPUTS to include file to enable file output. (default=./logs/all.log)

Prometheus

Variable Description
LIGHTDASH_PROMETHEUS_ENABLED Enables/Disables Prometheus metrics endpoint (default=false)
LIGHTDASH_PROMETHEUS_PORT Port for Prometheus metrics endpoint (default=9090)
LIGHTDASH_PROMETHEUS_PATH Path for Prometheus metrics endpoint (default=/metrics)
LIGHTDASH_PROMETHEUS_PREFIX Prefix for metric names.
LIGHTDASH_GC_DURATION_BUCKETS Buckets for duration histogram in seconds. (default=0.001, 0.01, 0.1, 1, 2, 5)
LIGHTDASH_EVENT_LOOP_MONITORING_PRECISION Precision for event loop monitoring in milliseconds. Must be greater than zero. (default=10)
LIGHTDASH_PROMETHEUS_LABELS Labels to add to all metrics. Must be valid JSON

Security

Variable Description
LIGHTDASH_CSP_REPORT_ONLY Enables Content Security Policy (CSP) reporting only mode. This is recommended to be set to false in production. (default=true)
LIGHTDASH_CSP_ALLOWED_DOMAINS List of domains that are allowed to load resources from. Values must be separated by commas.
LIGHTDASH_CSP_REPORT_URI URI to send CSP violation reports to.
LIGHTDASH_CORS_ENABLED Enables Cross-Origin Resource Sharing (CORS) (default=false)
LIGHTDASH_CORS_ALLOWED_DOMAINS List of domains that are allowed to make cross-origin requests. Values must be separated by commas.

Analytics & Event Tracking

Variable Description
RUDDERSTACK_WRITE_KEY RudderStack key used to track events (by default Lightdash's key is used)
RUDDERSTACK_DATA_PLANE_URL RudderStack data plane URL to which events are tracked (by default Lightdash's data plane is used)
RUDDERSTACK_ANALYTICS_DISABLED Set to true to disable RudderStack analytics
POSTHOG_PROJECT_API_KEY API key for Posthog (by default Lightdash's key is used)
POSTHOG_FE_API_HOST Hostname for Posthog's front-end API
POSTHOG_BE_API_HOST Hostname for Posthog's back-end API

AI Analyst

These variables enable you to configure the AI Analyst functionality. Note that you will need an Enterprise Licence Key for this functionality.

Variable Description
AI_COPILOT_ENABLED Enables/Disables AI Analyst functionality (default=false)
ASK_AI_BUTTON_ENABLED Enables the "Ask AI" button in the interface for direct access to AI agents, when disabled agents can be acessed from /ai-agents route (default=false)
AI_EMBEDDING_ENABLED Enables AI embedding functionality for verified answers similarity matching (default=false)
AI_DEFAULT_PROVIDER Default AI provider to use (openai, azure, anthropic, openrouter, bedrock) (default=openai)
AI_DEFAULT_EMBEDDING_PROVIDER Default AI provider for embeddings (openai, bedrock, azure) (default=openai)
AI_COPILOT_DEBUG_LOGGING_ENABLED Enables debug logging for AI Copilot (default=false)
AI_COPILOT_TELEMETRY_ENABLED Enables telemetry for AI Copilot (default=false)
AI_COPILOT_REQUIRES_FEATURE_FLAG Requires a feature flag to use AI Copilot (default=false)
AI_COPILOT_MAX_QUERY_LIMIT Maximum number of rows returned in AI-generated queries (default=500)
AI_VERIFIED_ANSWER_SIMILARITY_THRESHOLD Similarity threshold (0-1) for verified answer matching (default=0.6)

The AI Analyst supports multiple providers for flexibility. Choose one of the provider configurations below based on your preferred AI service. OpenAI and Anthropic are the recommended providers as they are the most tested and stable.

Minimum Required Setup

To enable AI Analyst, set AI_COPILOT_ENABLED=true and provide an API key for AI_DEFAULT_PROVIDER (e.g., OPENAI_API_KEY for OpenAI, ANTHROPIC_API_KEY for Anthropic).

OpenAI Configuration

Variable Description
OPENAI_API_KEY (Required when using OpenAI) API key for OpenAI
OPENAI_MODEL_NAME OpenAI model name to use (default=gpt-5.2)
OPENAI_EMBEDDING_MODEL OpenAI embedding model for verified answers (default=text-embedding-3-small)
OPENAI_BASE_URL Optional base URL for OpenAI compatible API
OPENAI_AVAILABLE_MODELS Comma-separated list of models available in the model picker (default=All supported models)
**Using an OpenAI-compatible proxy (e.g. LiteLLM)**

If your organization uses an OpenAI-compatible proxy like LiteLLM, you can connect it to Lightdash by setting AI_DEFAULT_PROVIDER=openai and pointing OPENAI_BASE_URL to your proxy URL. For example:

  • AI_DEFAULT_PROVIDER=openai
  • OPENAI_API_KEY=<your-proxy-api-key>
  • OPENAI_BASE_URL=<your-proxy-url>
  • OPENAI_MODEL_NAME=<model-name-configured-in-your-proxy>

Make sure your proxy has the model names correctly mapped. For example, if you set OPENAI_MODEL_NAME=gpt-4o, your proxy needs to have that model routed to whatever underlying provider you're using. The same applies for the embedding model.

If you want to expose multiple models through the proxy, use OPENAI_AVAILABLE_MODELS with a comma-separated list of model names.

Anthropic Configuration

Variable Description
ANTHROPIC_API_KEY (Required when using Anthropic) API key for Anthropic
ANTHROPIC_MODEL_NAME Anthropic model name to use (default=claude-sonnet-4-5)
ANTHROPIC_AVAILABLE_MODELS Comma-separated list of models available in the model picker (default=All supported models)

Azure AI Configuration

Variable Description
AZURE_AI_API_KEY (Required when using Azure AI) API key for Azure AI
AZURE_AI_ENDPOINT (Required when using Azure AI) Endpoint for Azure AI
AZURE_AI_API_VERSION (Required when using Azure AI) API version for Azure AI
AZURE_AI_DEPLOYMENT_NAME (Required when using Azure AI) Deployment name for Azure AI
AZURE_EMBEDDING_DEPLOYMENT_NAME Deployment name for Azure embedding model (default=text-embedding-3-small)
AZURE_USE_DEPLOYMENT_BASED_URLS Use deployment-based URLs for Azure OpenAI API calls (default=true)

OpenRouter Configuration

Variable Description
OPENROUTER_API_KEY (Required when using OpenRouter) API key for OpenRouter
OPENROUTER_MODEL_NAME OpenRouter model name to use (default=openai/gpt-4.1-2025-04-14)
OPENROUTER_SORT_ORDER Provider sorting method (price, throughput, latency) (default=latency)
OPENROUTER_ALLOWED_PROVIDERS Comma-separated list of allowed providers (anthropic, openai, google) (default=openai)

AWS Bedrock Configuration

Variable Description
BEDROCK_API_KEY (Required if not using IAM credentials) API key for Bedrock (alternative to IAM credentials)
BEDROCK_ACCESS_KEY_ID (Required if not using API key) AWS access key ID for Bedrock
BEDROCK_SECRET_ACCESS_KEY (Required if using access key ID) AWS secret access key for Bedrock
BEDROCK_SESSION_TOKEN AWS session token (for temporary credentials)
BEDROCK_REGION (Required) AWS region for Bedrock
BEDROCK_MODEL_NAME Bedrock model name to use (default=claude-sonnet-4-5)
BEDROCK_EMBEDDING_MODEL Bedrock embedding model for verified answers (default=cohere.embed-english-v3)
BEDROCK_AVAILABLE_MODELS Comma-separated list of models available in the model picker (default=All supported models)

Supported Models

OpenAI: gpt-5.1, gpt-5.2 (default)

Anthropic: claude-sonnet-4-5, claude-haiku-4-5, claude-sonnet-4

AWS Bedrock: claude-sonnet-4-5, claude-haiku-4-5, claude-sonnet-4

Exact model snapshots are automatically assigned (e.g., `gpt-5.1` → `gpt-5.1-2025-11-13`). For Bedrock, the region prefix is also added based on `BEDROCK_REGION` (e.g., `claude-sonnet-4-5` → `us.anthropic.claude-sonnet-4-5-20250929-v1:0`).

Slack Integration

These variables enable you to configure the Slack integration.

Variable Description
SLACK_SIGNING_SECRET Required for Slack integration
SLACK_CLIENT_ID Required for Slack integration
SLACK_CLIENT_SECRET Required for Slack integration
SLACK_STATE_SECRET Required for Slack integration (default=slack-state-secret)
SLACK_APP_TOKEN App token for Slack
SLACK_PORT Port for Slack integration (default=4351)
SLACK_SOCKET_MODE Enable socket mode for Slack (default=false)
SLACK_CHANNELS_CACHED_TIME Time in milliseconds to cache Slack channels (default=600000, 10 minutes)
SLACK_SUPPORT_URL URL for Slack support
SLACK_MULTI_AGENT_CHANNEL_ENABLED Enables the multi-agent Slack channel (Beta) feature for the whole instance (default=false)

GitHub Integration

These variables enable you to configure Github integrations

Variable Description
GITHUB_PRIVATE_KEY (Required) GitHub private key for GitHub App authentication
GITHUB_APP_ID (Required) GitHub Application ID
GITHUB_CLIENT_ID (Required) GitHub OAuth client ID
GITHUB_CLIENT_SECRET (Required) GitHub OAuth client secret
GITHUB_APP_NAME (Required) Name of the GitHub App
GITHUB_REDIRECT_DOMAIN Domain for GitHub OAuth redirection

Microsoft Teams Integration

These variables enable you to configure Microsoft Teams integration.

Variable Description
MICROSOFT_TEAMS_ENABLED Enables Microsoft Teams integration (default=false)

Google Cloud Platform

These variables enable you to configure Google Cloud Platform integration.

Variable Description
GOOGLE_CLOUD_PROJECT_ID Google Cloud Platform project ID
GOOGLE_DRIVE_API_KEY Google Drive API key
AUTH_GOOGLE_ENABLED Enables Google authentication (default=false)
AUTH_ENABLE_GCLOUD_ADC Enables Google Cloud Application Default Credentials (default=false)

Embedding

Note that you will need an Enterprise Licence Key for this functionality.

Variable Description
EMBEDDING_ENABLED Enables embedding functionality (default=false)
EMBED_ALLOW_ALL_DASHBOARDS_BY_DEFAULT When creating new embeds, allow all dashboards by default (default=false)
EMBED_ALLOW_ALL_CHARTS_BY_DEFAULT When creating new embeds, allow all charts by default (default=false)
LIGHTDASH_IFRAME_EMBEDDING_DOMAINS List of domains that are allowed to embed Lightdash in an iframe. Values must be separated by commas.

Custom roles

Note that you will need an Enterprise Licence Key for this functionality.

Variable Description
CUSTOM_ROLES_ENABLED Enables creation of custom organization roles with configurable permission scopes beyond the default Admin, Developer, Editor, and Viewer roles. (default=false)

Service account

Note that you will need an Enterprise Licence Key for this functionality.

Variable Description
SERVICE_ACCOUNT_ENABLED Enables service account functionality (default=false)

SCIM

Note that you will need an Enterprise Licence Key for this functionality.

Variable Description
SCIM_ENABLED Enables SCIM (System for Cross-domain Identity Management) (default=false)

Sentry

These variables enable you to configure Sentry for error tracking.

Variable Description
SENTRY_DSN Sentry DSN for both frontend and backend
SENTRY_BE_DSN Sentry DSN for backend only
SENTRY_FE_DSN Sentry DSN for frontend only
SENTRY_BE_SECURITY_REPORT_URI URI for Sentry backend security reports
SENTRY_TRACES_SAMPLE_RATE Sample rate for Sentry traces (0.0 to 1.0) (default=0.1)
SENTRY_PROFILES_SAMPLE_RATE Sample rate for Sentry profiles (0.0 to 1.0) (default=0.2)
SENTRY_ANR_ENABLED Enables Sentry Application Not Responding detection (default=false)
SENTRY_ANR_CAPTURE_STACKTRACE Captures stacktrace for ANR events (default=false)
SENTRY_ANR_TIMEOUT Timeout in milliseconds for ANR detection

Intercom & Pylon

These variables enable you to configure Intercom and Pylon for customer support and feedback.

Variable Description
INTERCOM_APP_ID Intercom application ID
INTERCOM_APP_BASE Base URL for Intercom API (default=https://api-iam.intercom.io)
PYLON_APP_ID Pylon application ID
PYLON_IDENTITY_VERIFICATION_SECRET Secret for verifying Pylon identities

Kubernetes

These variables enable you to configure Kubernetes integration.

Variable Description
K8S_NODE_NAME Name of the Kubernetes node
K8S_POD_NAME Name of the Kubernetes pod
K8S_POD_NAMESPACE Namespace of the Kubernetes pod
LIGHTDASH_CLOUD_INSTANCE Identifier for Lightdash cloud instance

Organization appearance

These variables allow you to customize the default appearance settings for your Lightdash instance's organizations. This color palette will be set for all organizations in your instance. You can't choose another one while these env vars are set.

Variable Description
OVERRIDE_COLOR_PALETTE_NAME Name of the default color palette
OVERRIDE_COLOR_PALETTE_COLORS Comma-separated list of hex color codes for the default color palette (must be 20 colors)

Initialize instance

When a new Lightdash instance is created, and there are no orgs and projects. You can initialize a new org and project using ENV variables to simplify the deployment process.

**Initialization is skipped if you already have an organization and project.**

On subsequent restarts, only the update instance call is made. However, if you have multiple organizations or projects, the update will fail and the instance will not start. To safely restart without issues, remove the variables specified in the Update instance section below.

**Initialize instance is only available on Lightdash Enterprise plans.**

For more information on our plans, visit our pricing page.

Currently we only support Databricks project types and Github dbt configuration.
Variable Description
LD_SETUP_ADMIN_NAME Name of the admin user for initial setup (default=Admin User)
LD_SETUP_ADMIN_EMAIL (Required) Email of the admin user for initial setup
LD_SETUP_ORGANIZATION_UUID UUID of the organization to configure. Use when multiple organizations exist to target a specific one instead of requiring exactly one to exist.
LD_SETUP_ORGANIZATION_EMAIL_DOMAIN Comma-separated list of email domains for organization whitelisting
LD_SETUP_ORGANIZATION_DEFAULT_ROLE Default role for new organization members (default=viewer)
LD_SETUP_ORGANIZATION_NAME (Required) Name of the organization
LD_SETUP_ADMIN_API_KEY (Required) API key for the admin user, must start with ldpat_ prefix
LD_SETUP_API_KEY_EXPIRATION Number of days until API key expires (0 for no expiration) (default=30)
LD_SETUP_SERVICE_ACCOUNT_TOKEN (Required) A pre-set token for the service account, must start with ldsvc_ prefix
LD_SETUP_SERVICE_ACCOUNT_EXPIRATION Number of days until service account token expires (0 for no expiration) (default=30)
LD_SETUP_PROJECT_UUID UUID of the project to configure. Use when multiple projects exist to target a specific one instead of requiring exactly one to exist.
LD_SETUP_PROJECT_NAME (Required) Name of the project
LD_SETUP_PROJECT_CATALOG Catalog name for Databricks project
LD_SETUP_PROJECT_SCHEMA (Required) Schema/database name for the project
LD_SETUP_PROJECT_HOST (Required) Hostname for the Databricks server
LD_SETUP_PROJECT_HTTP_PATH (Required) HTTP path for Databricks connection
LD_SETUP_PROJECT_PAT (Required) Personal access token for Databricks
LD_SETUP_START_OF_WEEK Day to use as start of week (default=SUNDAY)
LD_SETUP_PROJECT_COMPUTE JSON string with Databricks compute configuration like {"name": "string", "httpPath": "string"}
LD_SETUP_DBT_VERSION Version of dbt to use (eg: v1.8) (default=latest)
LD_SETUP_GITHUB_PAT (Required) GitHub personal access token
LD_SETUP_GITHUB_REPOSITORY (Required) GitHub repository for dbt project
LD_SETUP_GITHUB_BRANCH (Required) GitHub branch for dbt project
LD_SETUP_GITHUB_PATH Subdirectory path within GitHub repository (default=/)
In order to login as the admin user using SSO, you must enable the following ENV variable too: 
AUTH_ENABLE_OIDC_TO_EMAIL_LINKING=true

This will alow you to link your SSO account with the email provided without using an invitation code.
This email will be trusted, and any user with an OIDC account with that email will access the admin user.

Update instance

On server start, we will check the following variables, and update some configuration of the organization or project. If multiple organizations or projects exist, you must set LD_SETUP_ORGANIZATION_UUID and/or LD_SETUP_PROJECT_UUID to target a specific one.

**Update instance is only available on Lightdash Enterprise plans.**

For more information on our plans, visit our pricing page.

Variable Description
LD_SETUP_ADMIN_EMAIL (Required if LD_SETUP_ADMIN_API_KEY is present) Email of the admin to update its Personal access token
LD_SETUP_ADMIN_API_KEY API key for the admin user, must start with ldpat_ prefix
LD_SETUP_ORGANIZATION_UUID UUID of the organization to update. Required when multiple organizations exist.
LD_SETUP_ORGANIZATION_EMAIL_DOMAIN Comma-separated list of email domains for organization whitelisting
LD_SETUP_ORGANIZATION_DEFAULT_ROLE Default role for new organization members (default=viewer)
LD_SETUP_PROJECT_UUID UUID of the project to update. Required when multiple projects exist.
LD_SETUP_PROJECT_HTTP_PATH HTTP path for Databricks connection
LD_SETUP_PROJECT_PAT Personal access token for Databricks
LD_SETUP_DBT_VERSION Version of dbt to use (eg: v1.8) (default=latest)
LD_SETUP_GITHUB_PAT GitHub personal access token
LD_SETUP_SERVICE_ACCOUNT_TOKEN A pre-set token for the service account, must start with ldsvc_ prefix

Initialize multiple projects

Set LD_SETUP_PROJECTS to a JSON array to provision multiple projects at once. This is a drop-in replacement for the single-project LD_SETUP_PROJECT_* variables described in Initialize instance — when LD_SETUP_PROJECTS is set, the legacy LD_SETUP_PROJECT_* and LD_SETUP_GITHUB_* variables are ignored.

On every boot, Lightdash matches each entry to an existing project by name: new names are created, existing names are updated in place.

Currently we only support Databricks project types and GitHub dbt configuration for multi-project setup. **Project names are the primary key.** Renaming an entry creates a new project rather than renaming the existing one — charts and dashboards will stay on the old project.

Required companion variables

The admin, organization, and API key variables from Initialize instance still apply. LD_SETUP_ADMIN_EMAIL is required — without it, LD_SETUP_PROJECTS is ignored.

Schema

LD_SETUP_PROJECTS must be a JSON array. Each entry has the following shape:

Field Required Description
name Yes Project name. Must be non-empty and unique within the array.
warehouseConnection Yes Object with a valid type and the fields required by that warehouse (see below).
dbtConnection Yes Object with a valid type and the fields required by that dbt connection (below).
dbtVersion No Version of dbt to use (eg: v1.8). Defaults to latest.
embed No Embed config: { "secret": "...", "allowAllDashboards": true }.

Databricks warehouse fields

Field Required Description
type Yes Must be "databricks".
serverHostName Yes Databricks host, no protocol. Example: dbc-xxxx.cloud.databricks.com.
httpPath Yes SQL warehouse HTTP path, e.g. /sql/1.0/warehouses/abc123.
database Yes Schema name. (Historical naming — this is the dbt schema, not the Unity Catalog.)
catalog No Unity Catalog name.
authenticationType No One of personal_access_token (default), oauth_m2m, oauth_u2m.
personalAccessToken If authenticationType=personal_access_token Databricks PAT (starts with dapi_).
oauthClientId If authenticationType=oauth_m2m Databricks Service Principal client ID (a UUID).
oauthClientSecret If authenticationType=oauth_m2m Databricks Service Principal client secret.
compute No Array of extra SQL warehouses: [{ "name": "...", "httpPath": "..." }].
startOfWeek No Day to use as start of week (default=SUNDAY).
dataTimezone No Project-level timezone override.

GitHub dbt connection fields

Field Required Description
type Yes Must be "github".
authorization_method Yes Use "personal_access_token".
personal_access_token Yes GitHub personal access token.
repository Yes Repository in org/repo format.
branch Yes Branch name to pull the dbt project from.
project_sub_path Yes Subdirectory path within the repo (use / for the root).
selector No dbt selector name to limit which models are compiled.

Example

export LD_SETUP_ADMIN_EMAIL="admin@example.com"
export LD_SETUP_PROJECTS='[
  {
    "name": "Sample Project Alpha",
    "warehouseConnection": {
      "type": "databricks",
      "serverHostName": "alpha.cloud.databricks.com",
      "httpPath": "/sql/1.0/warehouses/abc123",
      "database": "alpha_db",
      "personalAccessToken": "dapi_alpha_fake_token"
    },
    "dbtConnection": {
      "type": "github",
      "authorization_method": "personal_access_token",
      "personal_access_token": "ghp_fake_alpha_token",
      "repository": "myorg/alpha-repo",
      "branch": "main",
      "project_sub_path": "/"
    }
  },
  {
    "name": "Sample Project Beta",
    "warehouseConnection": {
      "type": "databricks",
      "serverHostName": "beta.cloud.databricks.com",
      "httpPath": "/sql/1.0/warehouses/def456",
      "database": "beta_db",
      "personalAccessToken": "dapi_beta_fake_token"
    },
    "dbtConnection": {
      "type": "github",
      "authorization_method": "personal_access_token",
      "personal_access_token": "ghp_fake_beta_token",
      "repository": "myorg/beta-repo",
      "branch": "main",
      "project_sub_path": "/"
    }
  }
]'
**Quote the whole value in single quotes** in your shell so that `$`, backticks, and double quotes inside the JSON are not re-interpreted. When injecting via a secret manager or Kubernetes `Secret`, no escaping is needed — just paste the JSON as-is.

Databricks M2M OAuth example

Use a Databricks Service Principal when you want non-interactive, machine-to-machine authentication instead of a PAT. Lightdash exchanges the client_id + client_secret for an access token automatically on the first compile and refreshes it as needed — no user interaction is required.

export LD_SETUP_ADMIN_EMAIL="admin@example.com"
export LD_SETUP_PROJECTS='[
  {
    "name": "Sales (Databricks M2M)",
    "warehouseConnection": {
      "type": "databricks",
      "serverHostName": "dbc-xxxx.cloud.databricks.com",
      "httpPath": "/sql/1.0/warehouses/abc123",
      "catalog": "lightdash_prod",
      "database": "sales",
      "authenticationType": "oauth_m2m",
      "oauthClientId": "00000000-0000-0000-0000-000000000000",
      "oauthClientSecret": "dose...secret..."
    },
    "dbtConnection": {
      "type": "github",
      "authorization_method": "personal_access_token",
      "personal_access_token": "ghp_...",
      "repository": "myorg/dbt-sales",
      "branch": "main",
      "project_sub_path": "/"
    }
  }
]'

If you already have an M2M Service Principal configured for dbt, the field names are different. Map your dbt profile fields to Lightdash's warehouseConnection like this:

profiles.yml (dbt) LD_SETUP_PROJECTS (Lightdash)
host serverHostName
http_path httpPath
catalog catalog
schema database
auth_type: oauth authenticationType: "oauth_m2m"
client_id oauthClientId
client_secret oauthClientSecret
M2M is non-interactive by design — Lightdash uses the OAuth client-credentials grant. No browser popup, no per-user sign-in. The Service Principal needs `CAN USE` on the SQL warehouse and the appropriate `SELECT`/`USE CATALOG`/`USE SCHEMA` grants on your data.

Validation

LD_SETUP_PROJECTS is parsed and validated at boot. Lightdash will fail to start with a descriptive error if any of the following are true:

Error Cause
Failed to parse LD_SETUP_PROJECTS The value is not valid JSON. Check your shell quoting.
Invalid LD_SETUP_PROJECTS: expected array The top-level JSON is not an array.
name: Project name cannot be empty An entry has a missing or empty name.
warehouseConnection: Required / dbtConnection: Required An entry is missing one of the two connection blocks.
Invalid warehouse type warehouseConnection.type is not a supported warehouse.
Invalid dbt connection type dbtConnection.type is not a supported dbt connection.
Duplicate project name "X" in LD_SETUP_PROJECTS Two entries share the same name.
Multiple projects found with name "X" Two pre-existing projects in the DB share the same name — rename one in the UI before redeploying.
**Credentials in `LD_SETUP_PROJECTS` are the source of truth on every boot.** If an admin rotates a PAT or OAuth secret in the UI, the next restart will overwrite it with the value from this variable. Keep the variable in sync with your secret manager, or omit a project from the array once you no longer want it managed via env.

Migrating from LD_SETUP_PROJECT_*

LD_SETUP_PROJECTS replaces the single-project LD_SETUP_PROJECT_NAME, LD_SETUP_PROJECT_HOST, LD_SETUP_PROJECT_HTTP_PATH, LD_SETUP_PROJECT_PAT, LD_SETUP_PROJECT_SCHEMA, LD_SETUP_PROJECT_CATALOG, LD_SETUP_PROJECT_COMPUTE, LD_SETUP_GITHUB_*, and LD_SETUP_DBT_VERSION variables. When both are set, LD_SETUP_PROJECTS takes precedence and the legacy variables are ignored.

To migrate:

  1. Move your existing project config into a JSON object (use the existing project's exact name so it is updated in place rather than recreated).
  2. Set LD_SETUP_PROJECTS to a single-element array containing that object.
  3. Remove the legacy LD_SETUP_PROJECT_* and LD_SETUP_GITHUB_* variables from your deployment.