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

# Self-Host Lightdash

Lightdash is MIT licensed and open source. You can self-host Lightdash on your own infrastructure.

This guide is designed for DevOps Engineers that are familiar with Docker, Kubernetes, and are comfortable configuring environment variables, SMTP credentials, and database connections. If you're unsure whether to self-host please read our guide on [Lightdash Cloud vs. Self-Hosted](/self-host/lightdash-cloud-vs-self-hosted).

## Prerequisites for self-hosting

* Access to a kubernetes cluster and [kubectl](https://kubernetes.io/docs/tasks/tools/) installed
* [Helm](https://helm.sh/docs/intro/quickstart/)
* Docker

## Self-host Lightdash on Kubernetes

The following steps will create a Lightdash instance and a postgres database to store your metadata (note: this is separate to your data warehouse with your analytics data).

We recommend using kubernetes + helm but you can alternatively follow these guides for a minimum deployment without kubernetes:

* [Docker compose](/self-host/self-host-lightdash-docker-compose)
* [Restack](/self-host/self-host-lightdash-restack)

To deploy Lightdash on your Kubernetes cluster you can use our community maintained Helm chart: [https://github.com/lightdash/helm-charts](https://github.com/lightdash/helm-charts). This will get you started with the simplest configuration possible. At the end of this guide you can find a list of configuration options to customise your Lightdash instance and make it production ready.

### 1. Add the Lightdash Helm repository

```bash
helm repo add lightdash https://lightdash.github.io/helm-charts
```

### 2. Create a namespace for Lightdash

```bash
kubectl create namespace lightdash
```

### 3. Create a minimum configuration for 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).
* `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.

Example `values.yaml` file containing our configuration:

```yaml
# values.yaml
secrets:
  LIGHTDASH_SECRET: notverysecret
  S3_ACCESS_KEY: secret # not required if using IAM role
  S3_SECRET_KEY: secret # not required if using IAM role

configMap:
  SITE_URL: https://lightdash.mycompany.com
  S3_REGION: us
  S3_BUCKET: lightdash
  S3_ENDPOINT: https://storage.provider.com

service:
  type: NodePort
```

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

```bash
helm install lightdash lightdash/lightdash -n lightdash -f values.yaml
```

### 4 (alternative). Install Lightdash with kubectl

If you prefer not to manage your deployment with helm, you can generate the kubernetes manifests and apply them using `kubectl`.

```bash
helm template lightdash lightdash/lightdash -n lightdash -f values.yaml > lightdash.yaml
kubectl apply -f lightdash.yaml
```

Visit your `SITE_URL` to access Lightdash!

## Configure Lightdash for production

Now you have a working Lightdash instance, you can customise it to your needs. The following docs cover the most common configuration options, including those we recommend before going to production:

**Required configuration**

* [Configure Lightdash to use external object storage](/self-host/customize-deployment/configure-lightdash-to-use-external-object-storage)

**Recommended for production usage**

* [Secure Lightdash with HTTPS](/self-host/customize-deployment/secure-lightdash-with-https)
* [Configure Lightdash to use an external database](/self-host/customize-deployment/configure-lightdash-to-use-an-external-database)
* [Configure SMTP for email notifications](/self-host/customize-deployment/configure-smtp-for-lightdash-email-notifications)
* [Resource recommendations](/self-host/customize-deployment/recommended-resources/)

**Optional configuration**

* [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)
* [Configure environment variables for Lightdash](/self-host/customize-deployment/environment-variables)
* [Enable headless browser for Lightdash](/self-host/customize-deployment/enable-headless-browser-for-lightdash)
* [Configure Logging for Lightdash](/self-host/customize-deployment/configure-logging-for-lightdash)
* [Configure Prometheus metrics for Lightdash](/self-host/customize-deployment/configure-prometheus-metrics-for-self-hosted-lightdash)