lightdash · owlas · Aug 20, 2025
diff --git a/docs.json b/docs.json
@@ -187,6 +187,7 @@
               {
                 "group": "Customize deployment",
                 "pages": [
+                  "self-host/customize-deployment/enterprise-license-keys",
                   "self-host/customize-deployment/configure-a-slack-app-for-lightdash",
                   "self-host/customize-deployment/configure-github-for-lightdash",
                   "self-host/customize-deployment/configure-lightdash-to-use-an-external-database",

diff --git a/self-host/customize-deployment/enterprise-license-keys.mdx b/self-host/customize-deployment/enterprise-license-keys.mdx
@@ -0,0 +1,85 @@
+---
+title: "Enterprise License Keys"
+description: "Access enterprise features on self-hosted Lightdash instances"
+---
+
+Enterprise License Keys enable access to advanced Lightdash Enterprise Edition features on self-hosted instances. These features include enhanced security, performance optimizations, and advanced collaboration tools designed for large organizations.
+
+## Getting an Enterprise License Key
+
+To obtain an Enterprise License Key for your self-hosted Lightdash instance:
+
+1. **Contact our team** - [Schedule a call with our enterprise team](https://calendly.com/lightdash-cloud/enterprise?utm_source=docs&utm_medium=referral&utm_campaign=enterprise_licensing&utm_content=license_key_page) to discuss your requirements and get your license key.
+
+2. **Receive your license key** - Our team will provide you with a unique license key tailored to your organization's needs.
+
+## Configuring Your License Key
+
+Once you have received your Enterprise License Key, you need to configure it in your Lightdash deployment.
+
+### Using Environment Variables
+
+Add the following environment variable to your Lightdash configuration:
+
+```bash
+LIGHTDASH_LICENSE_KEY=your-enterprise-license-key-here
+```
+
+### Using Helm (Kubernetes)
+
+If you're deploying Lightdash on Kubernetes using Helm, add the license key to your `values.yaml` file:
+
+```yaml
+secrets:
+  LIGHTDASH_LICENSE_KEY: your-enterprise-license-key-here
+```
+
+Then update your Helm deployment:
+
+```bash
+helm upgrade lightdash lightdash/lightdash -n lightdash -f values.yaml
+```
+
+### Using Docker Compose
+
+For Docker Compose deployments, add the license key to your `docker-compose.yml` file:
+
+```yaml
+services:
+  lightdash:
+    environment:
+      - LIGHTDASH_LICENSE_KEY=your-enterprise-license-key-here
+```
+
+## Verifying Your License
+
+After configuring your license key and restarting Lightdash, you can verify that enterprise features are enabled by:
+
+1. Logging in as an admin user
+2. Navigating to Settings → Organization
+3. Checking for the "Enterprise Edition" badge
+
+## Enterprise Features
+
+With a valid Enterprise License Key, you'll have access to:
+
+- **Advanced authentication** - Enhanced SSO options and security controls
+- **Extended analytics** - Additional usage analytics and monitoring capabilities
+- **Priority support** - Direct access to our enterprise support team
+- **Advanced customization** - Additional configuration options for large deployments
+- **Performance optimizations** - Features designed for high-scale deployments
+
+## Troubleshooting
+
+If enterprise features are not available after configuring your license key:
+
+1. Verify the license key is correctly set in your environment variables
+2. Ensure Lightdash has been restarted after adding the license key
+3. Check the Lightdash logs for any license-related error messages
+4. Contact our [enterprise support team](https://calendly.com/lightdash-cloud/enterprise) for assistance
+
+## Related Documentation
+
+- [Environment Variables Reference](/self-host/customize-deployment/environment-variables)
+- [Self-Host Lightdash](/self-host/self-host-lightdash)
+- [Lightdash Cloud vs Self-Hosted](/self-host/lightdash-cloud-vs-self-hosted)
diff --git a/self-host/customize-deployment/environment-variables.mdx b/self-host/customize-deployment/environment-variables.mdx
@@ -38,7 +38,7 @@ This is a reference to all environment variables that can be used to configure a
 | `AUTH_ENABLE_OIDC_TO_EMAIL_LINKING`          | Enables/Disables linking OIDC identity to an existing user by email                                                                                                                                                                              |                                               |         `false`         |
 | `CUSTOM_VISUALIZATIONS_ENABLED`              | Enables/Disables custom chart functionality                                                                                                                                                                                                      |                                               |         `false`         |
 | `LIGHTDASH_MAX_PAYLOAD`                      | Maximum HTTP request body size                                                                                                                                                                                                                   |                                               |          `5mb`          |
-| `LIGHTDASH_LICENSE_KEY`                      | License key for Lightdash Enterprise Edition. [Talk to us about Lightdash Enterprise Edition](https://calendly.com/lightdash-cloud/enterprise?utm_source=docs&utm_medium=referral&utm_campaign=enterprise_licensing&utm_content=license_key_cta) |                                               |                         |
+| `LIGHTDASH_LICENSE_KEY`                      | License key for Lightdash Enterprise Edition. See [Enterprise License Keys](/self-host/customize-deployment/enterprise-license-keys) for details. [Get your license key](https://calendly.com/lightdash-cloud/enterprise?utm_source=docs&utm_medium=referral&utm_campaign=enterprise_licensing&utm_content=license_key_cta) |                                               |                         |
 | `HEADLESS_BROWSER_HOST`                      | Hostname for the headless browser                                                                                                                                                                                                                |                                               |            —            |
 | `HEADLESS_BROWSER_PORT`                      | Port for the headless browser                                                                                                                                                                                                                    |                                               |         `3001`          |
 | `ALLOW_MULTIPLE_ORGS`                        | If set to `true`, new users registering on Lightdash will have their own organization, separated from others                                                                                                                                     |                                               |         `false`         |

diff --git a/self-host/lightdash-cloud-vs-self-hosted.mdx b/self-host/lightdash-cloud-vs-self-hosted.mdx
@@ -24,6 +24,6 @@ Unless you have a specific need to self-host, we recommend using Lightdash Cloud
 
 There are a few reasons why you might want to self-host Lightdash:
 
-* You're a large enterprise and want to run a proof-of-concept on your own infrastructure. This can be a great way to get your hands on Lightdash, while your infosec team approves the use of Lightdash Cloud.
+* You're a large enterprise and want to run a proof-of-concept on your own infrastructure. This can be a great way to get your hands on Lightdash, while your infosec team approves the use of Lightdash Cloud. For enterprise features on self-hosted instances, see our [Enterprise License Keys](/self-host/customize-deployment/enterprise-license-keys) documentation.
 * You're a hobbyist and want to run Lightdash on your own infrastructure.
 * You want to customise Lightdash to your specific needs.
diff --git a/self-host/self-host-lightdash.mdx b/self-host/self-host-lightdash.mdx
@@ -40,9 +40,16 @@ kubectl create namespace lightdash
 At minimum you should configure:
 
 * `secrets.LIGHTDASH_SECRET` - this variable is used by Lightdash to encrypt data at rest in the database. You must keep this secret. If this is lost, you will not be able to access your data in Lightdash.
-* `config.S3_REGION`, `config.S3_BUCKET`, `config.S3_ENDPOINT`, `secrets.S3_ACCESS_KEY` and `secrets.S3_SECRET_KEY` - These variables are for configuring external object storage with S3. For detailed information, refer to the [external object storage documentation](/self-host/customize-deployment/configure-lightdash-to-use-external-object-storage).
+* `configMap.S3_REGION`, `configMap.S3_BUCKET`, `configMap.S3_ENDPOINT`, `secrets.S3_ACCESS_KEY` and `secrets.S3_SECRET_KEY` - These variables are for configuring external object storage with S3. For detailed information, refer to the [external object storage documentation](/self-host/customize-deployment/configure-lightdash-to-use-external-object-storage).
 * `service.type` - by default the Lightdash UI and API is exposed on a `ClusterIP` service. This means that it is only accessible from within the Kubernetes cluster. If you want to access Lightdash from outside the cluster, you can change this to `LoadBalancer` or `NodePort`. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types) for more information.
-* `config.SITE_URL` - if you know the URL that Lightdash will be accessible at, you can set this variable. This will ensure that all links in Lightdash are correct. If you don't know the URL yet, you can leave this blank and update it later.
+* `configMap.SITE_URL` - if you know the URL that Lightdash will be accessible at, you can set this variable. This will ensure that all links in Lightdash are correct. If you don't know the URL yet, you can leave this blank and update it later.
+
+When setting up and configuring your Lightdash instance, you'll likely need to configure many additional environment variables. The Helm chart supports three ways to set environment variables:
+* `configMap` - for non-sensitive configuration values
+* `secrets` - for sensitive values like passwords and API keys
+* `extraEnv` - for additional environment variables not covered by the chart's built-in options
+
+For a complete list of available environment variables, see the [environment variables documentation](/self-host/customize-deployment/environment-variables). For detailed Helm chart configuration options, refer to the [Lightdash Helm charts repository](https://github.com/lightdash/helm-charts).
 
 Example `values.yaml` file containing our configuration:
 
@@ -52,17 +59,36 @@ secrets:
   LIGHTDASH_SECRET: notverysecret
   S3_ACCESS_KEY: secret # not required if using IAM role
   S3_SECRET_KEY: secret # not required if using IAM role
+  # LIGHTDASH_LICENSE_KEY: your-enterprise-license-key # Optional: for Enterprise Edition features
 
 configMap:
   SITE_URL: https://lightdash.mycompany.com
   S3_REGION: us
   S3_BUCKET: lightdash
   S3_ENDPOINT: https://storage.provider.com
 
+# Additional environment variables not covered by configMap or secrets
+extraEnv:
+  - name: CUSTOM_ENV_VAR
+    value: "custom-value"
+  - name: ANOTHER_CONFIG
+    value: "another-value"
+
 service:
   type: NodePort
 ```
 
+#### Enterprise License Key (Optional)
+
+If you have a Lightdash Enterprise license, you can enable enterprise features by adding your license key to the configuration:
+
+```yaml
+secrets:
+  LIGHTDASH_LICENSE_KEY: your-enterprise-license-key-here
+```
+
+To obtain an Enterprise License Key, [contact our team](https://calendly.com/lightdash-cloud/enterprise?utm_source=docs&utm_medium=referral&utm_campaign=enterprise_licensing&utm_content=self_host_config). For more details, see our [Enterprise License Keys documentation](/self-host/customize-deployment/enterprise-license-keys).
+
 ### 4. Install Lightdash with helm
 
 Create a new helm release called `lightdash` using the `lightdash/lightdash` helm chart. In this example we're also using the namespace `-n lightdash`. Finally we apply our minimum configuration from above using `-f values.yaml`.
@@ -99,6 +125,7 @@ Now you have a working Lightdash instance, you can customise it to your needs. T
 
 **Optional configuration**
 
+* [Enterprise License Keys](/self-host/customize-deployment/enterprise-license-keys)
 * [Use SSO login for self-hosted Lightdash](/self-host/customize-deployment/use-sso-login-for-self-hosted-lightdash)
 * [Enable scheduler in self-hosted Lightdash](/self-host/customize-deployment/enable-scheduler-in-self-hosted-lightdash)
 * [Configure a Slack App for Lightdash](/self-host/customize-deployment/configure-a-slack-app-for-lightdash)