Production deployment checklist

​

Tier 1 — Evaluation / PoC

• External PostgreSQL — postgresql.enabled: false even for a PoC; a small managed instance is fine, no HA or backup requirements yet
• S3-compatible object storage — required regardless; Lightdash fails to start without it
• Enterprise license key if you’re evaluating Enterprise features — needs outbound access to https://api.keygen.sh

• Deploy with the self-hosting guide
• Pin an image version - pin image.tag to the latest version
• Set SITE_URL to your final https:// URL before first boot
• Generate a strong LIGHTDASH_SECRET and store it somewhere durable - losing it means losing access to encrypted data
• SECURE_COOKIES and TRUST_PROXY both "true" behind your TLS-terminating load balancer
• Headless browser enabled (the chart default) - image previews, PDF exports, Slack unfurls
• HTTPS end-to-end via your ingress or load balancer
• AI Analyst — model provider key + pgvector in Postgres

​

Tier 2 — Scalable production deployment

​

Operations

• Choose upgrade strategy — pinned image tag, at least monthly cadence

​

Workers and scaling

• Data apps — sandboxes runtime, apps bucket, and a separate preview origin
• Dedicated workers - scheduler.enabled: true to enable scalable scheduled deliveries
• NATS + warehouse workers - nats.enabled: true and warehouseNatsWorker.enabled: true for handling large volumes of warehouse queries
• ≥ 2 backend replicas with pod anti-affinity and a pod disruption budget
• Size resource requests

​

Infrastructure dependencies

• Postgres HA, backups and point-in-time recovery on the external database from Tier 1, plus the pgvector extension if you use Enterprise AI features
• Bucket strategy and lifecycle rules - a dedicated bucket per purpose, with a 1-day lifecycle delete on the results bucket
• SMTP email
• Email deliverability - transactional provider, SPF/DKIM on the sender domain
• Load balancer settings - timeout ≥ 300s, health check on /api/v1/health, request body limit ≥ LIGHTDASH_MAX_PAYLOAD

​

Security and authentication

• SSO (Okta / Azure AD / Google / generic OIDC) with password authentication disabled
• Account linking and personal access token policy
• CSP enforcement and explicit CORS

​

Tier 3 — Optional features and observability

​

Enterprise features

• Pre-aggregations — pre-aggregate NATS workers + a dedicated S3 bucket
• SCIM provisioning from your IdP
• Results caching, embedding, service accounts, custom roles

​

Integrations (enable what you use)

• Slack — scheduled deliveries, unfurls, AI agents in Slack
• GitHub or GitLab — dbt repo write-back
• Google Sheets sync

​

Observability

• Prometheus metrics enabled, and scraped on every pod
• Structured JSON logging shipped to your log platform
• Alerts on HTTP error rate/latency, queue depth, and Postgres pool saturation

​

Architecture: what you’re deploying

• configMap.* — non-sensitive env vars, applied to backend and all workers
• secrets.* — sensitive env vars, rendered into a Kubernetes Secret (or bring your own via existingSecret)
• extraEnv / schedulerExtraEnv — raw env entries, including valueFrom.secretKeyRef

​

Core configuration

image:
  repository: lightdash/lightdash
  tag: "0.xxxx.x"        # ALWAYS pin. Upgrade deliberately (see Upgrades & operations)

configMap:
  SITE_URL: https://lightdash.yourcompany.com
  SECURE_COOKIES: "true"
  TRUST_PROXY: "true"          # you are behind a TLS-terminating LB/ingress
  LIGHTDASH_MODE: default
  LIGHTDASH_MAX_PAYLOAD: "40mb"   # default 5mb is too small for large dbt manifests

existingSecret: lightdash-secrets   # contains LIGHTDASH_SECRET, S3 keys, SMTP password, ...

• SITE_URL is required for invite emails, OAuth redirect URIs, Slack unfurls, and scheduled-delivery links. Changing it later means reconfiguring every OAuth integration.
• LIGHTDASH_SECRET must be changed and stored securely. It signs session cookies and encrypts data at rest in Postgres (warehouse credentials, tokens). You must set this
  • SECURE_COOKIES + TRUST_PROXY are both "false" by default — production behind HTTPS needs both "true" (see Secure Lightdash with HTTPS).
• Session length is controlled by COOKIES_MAX_AGE_HOURS (unset = session cookie). Set it to your security policy, e.g. "24".
• If backend pods can’t reach SITE_URL from inside the cluster (hairpin/NAT issues), set INTERNAL_LIGHTDASH_HOST to the in-cluster service URL — the headless browser and internal calls use it.

​

Secrets management

​

Headless browser

browserless-chrome:
  enabled: true
  replicaCount: 1              # scale with scheduled-delivery volume
  image:
    repository: ghcr.io/browserless/chromium
    tag: v2.49.0               # pin it; this is what Lightdash Cloud runs
  resources:
    requests: { cpu: "2", memory: 4Gi }
    limits: { memory: 4Gi }    # the memory-pressure guard below needs a limit to exist
  env:
    CONNECTION_TIMEOUT: "300000"   # 5 min; the chart default 180s truncates big dashboards
    TIMEOUT: "120000"              # per-session; raising this is the most common screenshot fix
    HEALTH: "true"                 # reject new sessions under memory pressure (HTTP 429)…
    MAX_MEMORY_PERCENT: "85"       # …instead of OOM-killing mid-screenshot

​

Upgrades and operations

• Pin image.tag and upgrade deliberately. There is no LTS tag. Lightdash versioning: patch = routine, minor = check release notes (may be backwards-incompatible), major = read the upgrade guide
• Upgrade cadence: at least monthly. Lightdash ships continuously; falling many minor versions behind makes the eventual migration jump riskier
• Upgrade path: bump image.tag → helm upgrade → the migrationJob hook migrates the database → rolling restart. Roll back the image only if the release notes say the migrations are backwards-compatible; otherwise restore the database backup
• Keep a UAT instance that mirrors production config, and rehearse upgrades there against a refreshed copy of the production database
• DR runbook: you need three things to rebuild an instance from scratch — the Postgres backup, the LIGHTDASH_SECRET, and your Helm values. Test that you can

​

Scheduler worker

scheduler:
  enabled: true
  replicas: 1            # scale up if deliveries queue at peak times
  concurrency: 3         # jobs per replica (sets SCHEDULER_CONCURRENCY)
  resources:
    requests:
      cpu: 500m
      memory: 1425Mi
      ephemeral-storage: 1Gi

​

Sizing and availability

replicaCount: 2

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 60   # backend only; workers scale via replicas

podAntiAffinity:
  enabled: true        # spreads each component across nodes (hard) and zones (soft)

podDisruptionBudget:
  enabled: true
  minAvailable: 1

​

PostgreSQL

• Managed Postgres (Cloud SQL / RDS / Azure Database) — version 14+ recommended (12 is the documented minimum)
• Extensions: uuid-ossp (required) and pgvector, required for Enterprise AI features (AI Analyst embeddings, verified answers)
• HA: regional/multi-AZ primary. Lightdash Cloud runs regional HA primaries with a cross-region replica for disaster recovery
• Backups: daily automated backups, point-in-time recovery enabled, ≥ 7 days of transaction logs, 7–31 retained backups
• SSD storage with auto-resize
• Sizing: 2 vCPU / 8 GB RAM is a solid single-org baseline; 4 vCPU / 16 GB+ for large orgs or heavy scheduler usage
• Connection budget: every backend/worker pod opens its own pool. Set PGMAXCONNECTIONS: "50" and PGMINCONNECTIONS: "0" in configMap, then make sure Postgres max_connections covers pods × PGMAXCONNECTIONS with headroom
• Query insights / slow-query logging enabled on the database side
• TLS to the database:

ssl:
  enabled: true                          # injects PGSSLMODE=verify-full + NODE_EXTRA_CA_CERTS
  configMapName: lightdash-db-ca         # your CA cert
  certFileName: ca.pem

migrationJob:
  enabled: true

​

Object storage

• Dedicated bucket per purpose, each with a scoped credential that can only touch its own bucket:
  • results/cache bucket — add a lifecycle rule deleting objects after 1 day (results are ephemeral; this keeps the bucket small and cheap)
  • pre-aggregations bucket (if using pre-aggs) — lifecycle delete after ~30 days
  • data-apps bucket (if using data apps) — persistent, no delete lifecycle
• Block all public access on every bucket
• Prefer IAM roles (IRSA on EKS, Workload Identity on GKE) over static keys — but note signed URLs are then capped at 7 days
• If users share download links that must outlive the signed-URL TTL (S3_EXPIRATION_TIME, default 3 days), enable PERSISTENT_DOWNLOAD_URLS_ENABLED: "true"

​

Email deliverability

• Use a transactional provider (SES, Postmark, SendGrid) — Lightdash Cloud sends through Postmark
• Set up SPF/DKIM for the sender domain so scheduled deliveries don’t land in spam
• Internal open relay without auth: set EMAIL_SMTP_USE_AUTH: "false"

​

Load balancer and networking

• Redirect HTTP → HTTPS, minimum TLS 1.2
• Backend/LB timeout ≥ 300s — long-running exports and queries will be killed by the common 30–60s defaults
• Health check on GET /api/v1/health
• Request body size limit at the ingress ≥ your LIGHTDASH_MAX_PAYLOAD (dbt manifests for big projects are tens of MB)
• Optional: IP allowlisting / WAF / rate limiting at the load balancer
• On GKE specifically, the chart can create a BackendConfig for you (backendConfig.create: true, backendConfig.spec) — this is how timeouts, CDN and Cloud Armor policies are attached on Lightdash Cloud

​

Authentication policy

configMap:
  AUTH_DISABLE_PASSWORD_AUTHENTICATION: "true"
  AUTH_ENABLE_OIDC_LINKING: "true"            # let existing accounts link an SSO identity
  AUTH_ENABLE_OIDC_TO_EMAIL_LINKING: "true"   # required for SCIM+SSO and LD_SETUP admin login

• PAT policy: PAT_ALLOWED_ORG_ROLES, PAT_MAX_EXPIRATION_TIME_IN_DAYS, or DISABLE_PAT
• Keep ALLOW_MULTIPLE_ORGS: "false" (default) for a single-company instance

​

Security hardening

• CSP enforcement: LIGHTDASH_CSP_REPORT_ONLY: "false" (default is report-only; enforce in production), plus LIGHTDASH_CSP_ALLOWED_DOMAINS for any extra origins you load from
• CORS: leave disabled unless embedding; if embedding, LIGHTDASH_CORS_ENABLED: "true" with an explicit LIGHTDASH_CORS_ALLOWED_DOMAINS list — never *
• Egress policy: Lightdash needs your warehouse, S3, SMTP, api.keygen.sh (license), your IdP, and any AI provider endpoints — everything else can be blocked
• NetworkPolicies: the chart only ships one for NATS (keep nats.networkPolicy.enabled: true, the default); add your own default-deny + allow rules for backend ↔ postgres/browserless/S3 if your cluster uses them
• podSecurityContext / securityContext: the chart sets none by default — add runAsNonRoot, drop capabilities per your Pod Security Standards baseline
• Soft delete for content recovery: SOFT_DELETE_ENABLED: "true" (+ SOFT_DELETE_RETENTION_DAYS, default 30)

​

Enterprise features

​

Enterprise feature flags

configMap:
  # Caching
  RESULTS_CACHE_ENABLED: "true"       # warehouse results cache in S3
  AUTOCOMPLETE_CACHE_ENABLED: "true"  # filter autocomplete cache
  CACHE_STALE_TIME_SECONDS: "86400"

  # Governance
  SERVICE_ACCOUNT_ENABLED: "true"
  CUSTOM_ROLES_ENABLED: "true"

  # Embedding (if embedding dashboards in your product)
  EMBEDDING_ENABLED: "true"
  LIGHTDASH_IFRAME_EMBEDDING_DOMAINS: "https://app.yourcompany.com"

​

AI Analyst

configMap:
  AI_COPILOT_ENABLED: "true"
  AI_DEFAULT_PROVIDER: "anthropic"     # openai | azure | anthropic | openrouter | bedrock
  AI_EMBEDDING_ENABLED: "true"         # verified answers (requires pgvector in Postgres)
  MCP_ENABLED: "true"                  # MCP endpoint at /api/v1/mcp with built-in OAuth

secrets:
  ANTHROPIC_API_KEY: ...               # or OPENAI_API_KEY / AZURE_AI_* / BEDROCK_*

• Azure OpenAI: AZURE_AI_API_KEY, AZURE_AI_ENDPOINT, AZURE_AI_API_VERSION, AZURE_AI_DEPLOYMENT_NAME; Bedrock: BEDROCK_REGION + credentials
• Routing through an internal LLM gateway (LiteLLM etc.): AI_DEFAULT_PROVIDER: openai + OPENAI_BASE_URL
• Guardrails: AI_COPILOT_MAX_QUERY_LIMIT (default 500), AI_COPILOT_ALLOWED_PROJECT_UUID to pilot on one project first
• MCP details: Configure MCP for Lightdash

​

Data apps

configMap:
  APPS_RUNTIME_ENABLED: "true"
  SANDBOX_PROVIDER: e2b
  APP_RUNTIME_PREVIEW_ORIGIN: https://lightdash-apps.yourcompany.com   # separate origin!

secrets:
  E2B_API_KEY: ...
  APPS_S3_BUCKET: yourco-lightdash-apps    # persistent bucket, no delete lifecycle
  APPS_S3_REGION: eu-west-1

​

Observability

configMap:
  # Structured logs for your log pipeline
  LIGHTDASH_LOG_LEVEL: info          # "audit" adds an audit trail of user actions
  LIGHTDASH_LOG_FORMAT: json
  LIGHTDASH_LOG_OUTPUTS: console

  # Prometheus metrics on :9090/metrics (all pods, backend + workers)
  LIGHTDASH_PROMETHEUS_ENABLED: "true"
  LIGHTDASH_PROMETHEUS_HTTP_METRICS_ENABLED: "true"

• Scrape port 9090 on all pods labelled app.kubernetes.io/name=lightdash (the chart doesn’t ship a ServiceMonitor/PodMonitoring — create one; Lightdash Cloud does exactly this, 30s interval)
• Metrics worth alerting on: HTTP p95/error rate (http_server_request_duration_seconds), queue depth / scheduler job failures, pg pool saturation, event-loop lag
• If you run NATS, its Prometheus exporter is on port 7777 (nats.promExporter.enabled: true)