> ## Documentation Index
> Fetch the complete documentation index at: https://lightdash-mintlify-cccf65ca.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Enterprise on-prem setup

> Guide for deploying Lightdash Enterprise Edition on-prem, on prem, on premises, on-premises on your own infrastructure. FedRAMP ready.

This guide covers the setup requirements and best practices for deploying Lightdash Enterprise Edition on-prem (on prem, on-premises, on premises). Lightdash Enterprise supports FedRAMP-ready deployments for government and regulated industries.

## Prerequisites

* Postgres database with the `pgvector` extension installed

## Accessing the Lightdash image

The Lightdash image is available on [DockerHub](https://hub.docker.com/repository/docker/lightdash/lightdash/tags). You can pull a specific version (recommended) or use `latest`.

```bash theme={null}
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 **UAT / pre-production** first
2. Run your normal validation (SSO, connections, dbt refreshes, scheduled jobs, embeds, critical dashboards)
3. Roll out to **production** when you're comfortable

<Note>
  Your UAT / pre-production environment should mirror production as closely as possible so upgrade testing is meaningful:

  * **Same configuration and environment variables as production** — feature flags, SSO settings, SMTP, object storage, license key, scheduler/headless browser config, etc. Differences here are the most common reason an upgrade passes pre-prod but fails in production.
  * **A replica of your production Lightdash database** (the Postgres instance Lightdash uses for its application data, including `pgvector`) — not an empty or hand-seeded one. Real data volume, real migrations, and real project/role/embed state are what surface upgrade regressions.

  Refresh the database replica from production before each round of upgrade testing.
</Note>

## 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.

<Note>
  License validation requires outbound access to `https://api.keygen.sh`.
</Note>

For detailed configuration instructions, see [Enterprise License Keys](/self-host/customize-deployment/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](/references/workspace/custom-roles#custom-roles)                                        |
| AI agents                         | `AI_AGENTS_ENABLED=true`                 | [AI agents](/guides/ai-agents)                                                                         |
| Multi-agent Slack channels (Beta) | `SLACK_MULTI_AGENT_CHANNEL_ENABLED=true` | [Multi-agent Slack channels](/guides/ai-agents/getting-started#setting-up-a-multi-agent-slack-channel) |
| Caching                           | `RESULTS_CACHE_ENABLED=true`             | [Caching](/guides/developer/caching)                                                                   |
| Embedding                         | `EMBEDDING_ENABLED=true`                 | [Embedding](/references/embedding)                                                                     |
| MCP                               | `MCP_ENABLED=true`                       | [MCP integration](/self-host/customize-deployment/configure-mcp-for-lightdash)                         |

You can [search "enterprise" on the environment variables page](/self-host/customize-deployment/environment-variables) to see all variables that require an Enterprise license key.

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

## 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