You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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)
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)
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)
[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)
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, WARNERROR (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)
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 integration is the recommended option as it is the most tested and stable implementation.
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)
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)
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`).
(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.
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.
**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_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_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. Having more than one org or project can throw runtime errors and prevent the server from starting.
**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_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_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