Environment variables

🛠 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:

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).
Set LD_SETUP_PROJECTS to a single-element array containing that object.
Remove the legacy LD_SETUP_PROJECT_* and LD_SETUP_GITHUB_* variables from your deployment.

Introduction

Explore and analyze

Build with AI

Build your semantic layer

Workspace and user management

Integrations

Lightdash SDK

Embedding

Self-hosting and deployment

Contact

​Athena

​Snowflake

​SMTP

​SSO

​S3

​Persistent download URLs

​Cache

​Logging

​Prometheus

​Security

​Analytics & Event Tracking

​AI Analyst

​Minimum Required Setup

​OpenAI Configuration

​Anthropic Configuration

​Azure AI Configuration

​OpenRouter Configuration

​AWS Bedrock Configuration

​Supported Models

​Slack Integration

​GitHub Integration

​Microsoft Teams Integration

​Google Cloud Platform

​Embedding

​Custom roles

​Service account

​SCIM

​Sentry

​Intercom & Pylon

​Kubernetes

​Organization appearance

​Initialize instance

​Update instance

​Initialize multiple projects

​Required companion variables

​Schema

​Databricks warehouse fields

​GitHub dbt connection fields

​Example

​Databricks M2M OAuth example

​Validation

​Migrating from LD_SETUP_PROJECT_*

Athena

Snowflake

SMTP

SSO

S3

Persistent download URLs

Cache

Logging

Prometheus

Security

Analytics & Event Tracking

AI Analyst

Minimum Required Setup

OpenAI Configuration

Anthropic Configuration

Azure AI Configuration

OpenRouter Configuration

AWS Bedrock Configuration

Supported Models

Slack Integration

GitHub Integration

Microsoft Teams Integration

Google Cloud Platform

Embedding

Custom roles

Service account

SCIM

Sentry

Intercom & Pylon

Kubernetes

Organization appearance

Initialize instance

Update instance

Initialize multiple projects

Required companion variables

Schema

Databricks warehouse fields

GitHub dbt connection fields

Example

Databricks M2M OAuth example

Validation

Migrating from `LD_SETUP_PROJECT_*`