From fc658122958b2eb8fa35d5775045f8249b8e9578 Mon Sep 17 00:00:00 2001 From: Charlie Dowler Date: Thu, 12 Feb 2026 13:56:12 +0000 Subject: [PATCH 1/3] docs: add persistent download URL environment variables Document PERSISTENT_DOWNLOAD_URLS_ENABLED and PERSISTENT_DOWNLOAD_URL_EXPIRATION_SECONDS in the S3 section, with an explanatory subsection covering the two-layer expiration behavior and IAM credential rotation resilience. Co-Authored-By: Claude Opus 4.6 --- self-host/customize-deployment/environment-variables.mdx | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/self-host/customize-deployment/environment-variables.mdx b/self-host/customize-deployment/environment-variables.mdx index 6513f528..e82ff0b1 100644 --- a/self-host/customize-deployment/environment-variables.mdx +++ b/self-host/customize-deployment/environment-variables.mdx @@ -137,6 +137,15 @@ These variables allow you to configure [S3 Object Storage](/self-host/customize- | `RESULTS_S3_REGION` | Region where the S3 query storage bucket is located (default=S3_REGION) | | `RESULTS_S3_ACCESS_KEY` | Access key for authenticating with the S3 query storage bucket (default=S3_ACCESS_KEY) | | `RESULTS_S3_SECRET_KEY` | Secret key for authenticating with the S3 query storage bucket (default=S3_SECRET_KEY) | +| `PERSISTENT_DOWNLOAD_URLS_ENABLED` | Enables persistent download URLs for CSV and dashboard exports. When enabled, downloads return a stable Lightdash-hosted URL instead of a direct S3 signed URL. Each time the persistent URL is accessed, a fresh S3 signed URL is generated on the fly. (default=false) | +| `PERSISTENT_DOWNLOAD_URL_EXPIRATION_SECONDS` | How long persistent download URLs remain accessible before expiring. Each access within this window generates a fresh S3 signed URL. (default=259200, 3 days) | + +### Persistent download URLs + +When `PERSISTENT_DOWNLOAD_URLS_ENABLED` is set to `true`, CSV and dashboard ZIP exports return a stable Lightdash-hosted URL (e.g. `https://lightdash.example.com/api/v1/file/{id}`) instead of a direct S3 signed URL. Each time this URL is accessed, Lightdash generates a short-lived S3 signed URL and redirects to it. This means: + +- The underlying S3 URL never goes stale and download links survive IAM credential rotation +- The persistent URL itself remains accessible for the duration set by `PERSISTENT_DOWNLOAD_URL_EXPIRATION_SECONDS` (default: 3 days), after which it returns a "download link has expired" error ## Cache From a2e838c20c74d48a9cdb31e40f01ed267c40d38e Mon Sep 17 00:00:00 2001 From: Charlie Dowler Date: Thu, 12 Feb 2026 13:59:04 +0000 Subject: [PATCH 2/3] docs: remove redundant S3 signed URL mention Co-Authored-By: Claude Opus 4.6 --- self-host/customize-deployment/environment-variables.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/self-host/customize-deployment/environment-variables.mdx b/self-host/customize-deployment/environment-variables.mdx index e82ff0b1..63eefabb 100644 --- a/self-host/customize-deployment/environment-variables.mdx +++ b/self-host/customize-deployment/environment-variables.mdx @@ -142,7 +142,7 @@ These variables allow you to configure [S3 Object Storage](/self-host/customize- ### Persistent download URLs -When `PERSISTENT_DOWNLOAD_URLS_ENABLED` is set to `true`, CSV and dashboard ZIP exports return a stable Lightdash-hosted URL (e.g. `https://lightdash.example.com/api/v1/file/{id}`) instead of a direct S3 signed URL. Each time this URL is accessed, Lightdash generates a short-lived S3 signed URL and redirects to it. This means: +When `PERSISTENT_DOWNLOAD_URLS_ENABLED` is set to `true`, CSV and dashboard ZIP exports return a stable Lightdash-hosted URL (e.g. `https://lightdash.example.com/api/v1/file/{id}`) Each time this URL is accessed, Lightdash generates a short-lived S3 signed URL and redirects to it. This means: - The underlying S3 URL never goes stale and download links survive IAM credential rotation - The persistent URL itself remains accessible for the duration set by `PERSISTENT_DOWNLOAD_URL_EXPIRATION_SECONDS` (default: 3 days), after which it returns a "download link has expired" error From 951c56d02d9dc5acd9a84ab6a5150c7af41b4204 Mon Sep 17 00:00:00 2001 From: Charlie Dowler Date: Thu, 12 Feb 2026 14:00:50 +0000 Subject: [PATCH 3/3] docs: restore S3 signed URL mention for clarity Co-Authored-By: Claude Opus 4.6 --- self-host/customize-deployment/environment-variables.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/self-host/customize-deployment/environment-variables.mdx b/self-host/customize-deployment/environment-variables.mdx index 63eefabb..e82ff0b1 100644 --- a/self-host/customize-deployment/environment-variables.mdx +++ b/self-host/customize-deployment/environment-variables.mdx @@ -142,7 +142,7 @@ These variables allow you to configure [S3 Object Storage](/self-host/customize- ### Persistent download URLs -When `PERSISTENT_DOWNLOAD_URLS_ENABLED` is set to `true`, CSV and dashboard ZIP exports return a stable Lightdash-hosted URL (e.g. `https://lightdash.example.com/api/v1/file/{id}`) Each time this URL is accessed, Lightdash generates a short-lived S3 signed URL and redirects to it. This means: +When `PERSISTENT_DOWNLOAD_URLS_ENABLED` is set to `true`, CSV and dashboard ZIP exports return a stable Lightdash-hosted URL (e.g. `https://lightdash.example.com/api/v1/file/{id}`) instead of a direct S3 signed URL. Each time this URL is accessed, Lightdash generates a short-lived S3 signed URL and redirects to it. This means: - The underlying S3 URL never goes stale and download links survive IAM credential rotation - The persistent URL itself remains accessible for the duration set by `PERSISTENT_DOWNLOAD_URL_EXPIRATION_SECONDS` (default: 3 days), after which it returns a "download link has expired" error