From fc658122958b2eb8fa35d5775045f8249b8e9578 Mon Sep 17 00:00:00 2001 From: Charlie Dowler Date: Thu, 12 Feb 2026 13:56:12 +0000 Subject: [PATCH 1/5] 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/5] 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/5] 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 From 8038f7cee271850bd3f2060c6a9d7d0cdb76ca43 Mon Sep 17 00:00:00 2001 From: Charlie Dowler Date: Fri, 13 Feb 2026 10:52:55 +0000 Subject: [PATCH 4/5] docs: restructure persistent download URLs into standalone section Move env vars out of the S3 table into a dedicated section with its own table for better readability and discoverability. Co-Authored-By: Claude Opus 4.6 --- .../customize-deployment/environment-variables.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/self-host/customize-deployment/environment-variables.mdx b/self-host/customize-deployment/environment-variables.mdx index e82ff0b1..1e74212c 100644 --- a/self-host/customize-deployment/environment-variables.mdx +++ b/self-host/customize-deployment/environment-variables.mdx @@ -137,15 +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 +## 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 enabled, 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 — so the underlying URL never goes stale and download links survive IAM credential rotation. -- 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 +| Variable | Description | +| :------------------------------------------- | :----------------------------------------------------------------------- | +| `PERSISTENT_DOWNLOAD_URLS_ENABLED` | Enables persistent download URLs (default=false) | +| `PERSISTENT_DOWNLOAD_URL_EXPIRATION_SECONDS` | How long the persistent URL remains accessible (default=259200, 3 days) | ## Cache From 71ed808290c46570a01814b84c3021884750d915 Mon Sep 17 00:00:00 2001 From: Charlie Dowler Date: Fri, 13 Feb 2026 11:07:35 +0000 Subject: [PATCH 5/5] docs: clarify S3_EXPIRATION_TIME is ignored with persistent URLs When persistent download URLs are enabled, S3_EXPIRATION_TIME is ignored and each redirect generates a signed URL that expires after 5 minutes. 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 1e74212c..a8c99ad2 100644 --- a/self-host/customize-deployment/environment-variables.mdx +++ b/self-host/customize-deployment/environment-variables.mdx @@ -145,7 +145,7 @@ When enabled, CSV and dashboard ZIP exports return a stable Lightdash-hosted URL | Variable | Description | | :------------------------------------------- | :----------------------------------------------------------------------- | | `PERSISTENT_DOWNLOAD_URLS_ENABLED` | Enables persistent download URLs (default=false) | -| `PERSISTENT_DOWNLOAD_URL_EXPIRATION_SECONDS` | How long the persistent URL remains accessible (default=259200, 3 days) | +| `PERSISTENT_DOWNLOAD_URL_EXPIRATION_SECONDS` | How long the persistent URL remains accessible (default=259200, 3 days). When persistent URLs are enabled, `S3_EXPIRATION_TIME` is ignored and each redirect generates a signed URL that expires after 5 minutes. | ## Cache