Enterprise on-prem setup

Guide for deploying Lightdash Enterprise Edition on your own infrastructure

This guide covers the setup requirements and best practices for deploying Lightdash Enterprise Edition on-premises.

Prerequisites

• Postgres database with the pgvector extension installed

Accessing the Lightdash image

The Lightdash image is available on DockerHub. You can pull a specific version (recommended) or use latest.

docker pull lightdash/lightdash:0.2248.3

Recommended version strategy

We publish frequent releases, and we don’t currently provide an LTS (long-term support) or “stable” tag for self-hosted deployments.

Our recommendation:

• Use a pinned version in production (e.g. lightdash/lightdash:0.2248.3) rather than latest
• Pinning makes deployments repeatable and avoids unexpected changes

Treat upgrades as a controlled rollout:

1. Upgrade in staging first
2. Run your normal validation (SSO, connections, dbt refreshes, scheduled jobs, embeds, critical dashboards)
3. Roll out to production when you’re comfortable

License key

A license key is required for Enterprise Edition features. Set it via the LIGHTDASH_LICENSE_KEY environment variable. Your license key will be shared by the Lightdash team via 1Password.

License validation requires outbound access to https://api.keygen.sh.

For detailed configuration instructions, see Enterprise License Keys.

After activating your license key

Once your license key is active, most Enterprise features are controlled by environment variables. To enable a specific feature, you’ll need to set the corresponding variable:

Feature	Environment variable	Documentation
Custom roles	CUSTOM_ROLES_ENABLED=true	Custom roles
AI agents	AI_AGENTS_ENABLED=true	AI agents
Caching	RESULTS_CACHE_ENABLED=true	Caching
Embedding	EMBEDDING_ENABLED=true	Embedding

You can search “enterprise” on the environment variables page to see all variables that require an Enterprise license key.

If you need help enabling features or troubleshooting your deployment, contact the Lightdash team.

Migration from OSS

If you’re migrating from the open-source version to Enterprise Edition:

1. Migrate to a commercial version matching your current OSS version
2. Once a single container is running the commercial version, the connected database will be upgraded to include the commercial schemas
3. Any other OSS containers will fail on restart but can be run temporarily
4. Roll out the commercial version to all containers as soon as the first container successfully migrates