Skip to main content
🛠 This page is for engineering teams self-hosting their own Lightdash instance. If you want to set up scheduled deliveries, go to the Scheduled deliveries guide.
Images can be requested on Slack unfurl or using our Scheduler If you are running Lightdash on self-hosting, you will also have to run this headless browser on your infrastructure.

​
How it works

When Lightdash needs to generate an image, it will open a new socket connection to the headless browser on ws://HEADLESS_BROWSER_HOST:HEADLESS_BROWSER_PORT Then using playwright we will browse the chart/dashboard on lightdash on SITE_URL We load the chart/dashboard on the browser and then a screenshot when it finishes loading Then we store that image in S3 (if enabled) or locally and then return the image URL. If the image was requested by Slack unfurl, we will unfurl the image using the Slack API. If the image was requested by Scheduler, we will send the image to the destination(s) (email or Slack)

​
Configure headless browser on lightdash

Lightdash uses Browserless for headless browser functionality. We recommend using the ghcr.io/browserless/chromium image with version v2.24.3, which is the version used in Lightdash Cloud deployments.
In order to make this work, there are a few key ENV variables that need to be configured correctly.
  • HEADLESS_BROWSER_HOST : If you’re running docker, this could be headless-browser, or localhost if you’re running it locally (or with network:host)
  • HEADLESS_BROWSER_PORT : Optional port for headless browser, defaults to 3001
  • SITE_URL : The URL for your Lightdash instance.
This SITE_URL variable (eg: https://eu1.lightdash.cloud) needs to be accessible from this headless browser service, either by a local connection, or via Internet. Otherwise it will not be able to open a page and generate the image.This means that if you are using docker locally, make sure the headless browser pod can reach the lightdash pod. Or follow the docker documentation to enable network:host

​
Timeouts and retries

If you’re exporting large dashboards via scheduled deliveries or Slack, you may need to tune timeout and retry settings. There are two layers of configuration: the Browserless container and the Lightdash backend.

​
Browserless container

Set these environment variables on the headless browser pod/container (the ghcr.io/browserless/chromium image):
VariableDefaultDescription
TIMEOUT30000Maximum time (ms) Browserless allows a browser session to run before terminating it. Increase this if large dashboards time out during export. A value of 120000 (2 minutes) works well for most cases.

​
Lightdash backend

Set these environment variables on the Lightdash backend (the main app or scheduler worker):
VariableDefaultDescription
HEADLESS_BROWSER_MAX_SCREENSHOT_RETRIES5Number of times Lightdash retries a failed screenshot before giving up.
HEADLESS_BROWSER_RETRY_BASE_DELAY_MS3000Base delay (ms) between screenshot retries. Uses exponential backoff.
SCHEDULER_JOB_TIMEOUT600000 (10 min)Maximum time (ms) for any scheduler job (including screenshot exports) to complete.

​
Troubleshooting large dashboard exports

If scheduled deliveries fail for large dashboards, try the following in order:
  1. Increase TIMEOUT on the Browserless container to at least 120000 (2 minutes). This is the most common fix.
  2. Check that SITE_URL is reachable from the headless browser container. The browser needs to load the full dashboard page, including all chart queries.
  3. If exports still fail intermittently, increase HEADLESS_BROWSER_MAX_SCREENSHOT_RETRIES to give it more attempts.
  4. If jobs are timing out entirely, increase SCHEDULER_JOB_TIMEOUT. The default of 10 minutes should be sufficient for most dashboards.