centersl/librechat.ai
1
0
Fork 0
mirror of https://github.com/LibreChat-AI/librechat.ai.git synced 2026-03-27 10:48:32 +07:00
Code Issues Packages Projects Releases Wiki Activity

refactor: update CDN documentation for clarity and accuracy

Browse Source 
- Renamed Azure Blob Storage and Amazon S3 sections to reflect their role as file storage backends rather than CDNs.
- Enhanced descriptions to clarify that Azure Blob Storage and S3 do not serve files through a CDN, while Firebase is the only true CDN option.
- Added warnings regarding the limitations of presigned URLs for S3 and emphasized the need for stable URLs for images and avatars.
- Updated the main CDN index to better outline the differences between file storage and CDN options, improving user guidance for setup.
This commit is contained in:
Danny Avila
2026-02-20 19:36:18 -05:00
parent 737f04c331
commit 347f15c62f
6 changed files with 67 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
content/docs/configuration/cdn/azure.mdx
View File

@@ -1,7 +1,7 @@
---
title: Azure Blob Storage CDN
title: Azure Blob Storage
icon: Cloud
description: This document provides instructions for setting up Azure Blob Storage CDN for LibreChat
description: This document provides instructions for setting up Azure Blob Storage for LibreChat
---
{/* Adding a table of contents for better navigation */}
@@ -15,7 +15,7 @@ description: This document provides instructions for setting up Azure Blob Stora
## Production Setup
Azure Blob Storage offers scalable, secure object storage that can be used as a CDN for your static assets such as images, CSS, and JavaScript. Follow these steps to configure your Azure Blob Storage for LibreChat.
Azure Blob Storage offers scalable, secure object storage for files in LibreChat. Follow these steps to configure your Azure Blob Storage.
## 1. Create an Azure Storage Account
@@ -83,7 +83,18 @@ cache: true
fileStrategy: "azure_blob"
```
This setting tells LibreChat to use the Azure Blob Storage implementation provided in your code.
<Callout type="warning" title="Azure Blob Storage is object storage, not a CDN">
Azure Blob Storage stores and serves files directly from origin — it is not a CDN. Images and avatars are best served through a CDN for optimal performance and global delivery. Currently, [Firebase](/docs/configuration/cdn/firebase) is the only CDN-backed storage option.
You can use `fileStrategies` to route only avatars and images to Firebase while keeping documents on Azure Blob Storage:
```yaml filename="librechat.yaml"
fileStrategies:
avatar: "firebase"
image: "firebase"
document: "azure_blob"
```
</Callout>
---
@@ -106,7 +117,7 @@ In your `.env` file, set either:
4. **Configure LibreChat:**
Set `fileStrategy` to `"azure_blob"` in your `librechat.yaml` configuration file.
With these steps, your LibreChat application will automatically create the container (if it doesn't exist) and manage file uploads, downloads, and deletions using Azure Blob Storage as your CDN. Managed Identity provides a secure alternative by eliminating the need for long-term credentials.
With these steps, your LibreChat application will automatically create the container (if it doesn't exist) and manage file uploads, downloads, and deletions using Azure Blob Storage. Managed Identity provides a secure alternative by eliminating the need for long-term credentials.
## Local Development with Azurite

4
content/docs/configuration/cdn/firebase.mdx
View File

@@ -1,10 +1,10 @@
---
title: Firebase CDN
icon: Flame
description: This document provides instructions for setting up Firebase CDN for LibreChat
description: This document provides instructions for setting up Firebase Storage as a CDN for LibreChat
---
Firebase CDN (Content Delivery Network) is a feature of the Firebase platform that allows you to host and serve static assets, such as HTML, CSS, JavaScript, images, and videos, from a network of edge locations around the world.
Firebase Storage integrates with Firebase Hosting's global CDN, allowing you to serve files stored in Firebase Storage through edge locations around the world. This makes it the only true CDN-backed file storage option in LibreChat.
## Steps to Set Up Firebase

20
content/docs/configuration/cdn/index.mdx
View File

@@ -1,20 +1,22 @@
---
title: CDN
title: File Storage & CDN
icon: BookOpen
description: CDN setup instructions
description: File storage and CDN setup instructions
---
<Callout type="info" title="Note">
This guide covers the setup instructions for three CDN options. Choose the one that best meets your deployment requirements.
LibreChat supports multiple file storage backends and one CDN option. Amazon S3 and Azure Blob Storage are object/file storage solutions, while Firebase is the only true CDN option with global edge delivery. Choose the one that best meets your deployment requirements.
</Callout>
## Setup Instructions:
## File Storage
### Amazon S3 CDN
- [Amazon S3 CDN](/docs/configuration/cdn/s3)
### Amazon S3
- [Amazon S3](/docs/configuration/cdn/s3)
### Azure Blob Storage CDN
- [Azure Blob Storage CDN](/docs/configuration/cdn/azure)
### Azure Blob Storage
- [Azure Blob Storage](/docs/configuration/cdn/azure)
### Firebase CDN
## CDN
### Firebase
- [Firebase CDN](/docs/configuration/cdn/firebase)

2
content/docs/configuration/cdn/meta.json
View File

@@ -1,5 +1,5 @@
{
"title": "CDN & File Storage",
"title": "File Storage & CDN",
"icon": "HardDrive",
"pages": [
"index",

25
content/docs/configuration/cdn/s3.mdx
View File

@@ -1,10 +1,10 @@
---
title: Amazon S3 CDN
title: Amazon S3
icon: Warehouse
description: This document provides instructions for setting up Amazon S3 as a CDN for LibreChat.
description: This document provides instructions for setting up Amazon S3 as a file storage backend for LibreChat.
---
Amazon S3 is a scalable, secure object storage service that can be used as a CDN for your static assets (such as images, CSS, and JavaScript) in LibreChat. Follow these steps to configure your S3 bucket.
Amazon S3 is a scalable, secure object storage service that can be used as a file storage backend for LibreChat. Follow these steps to configure your S3 bucket.
## 1. Create an AWS Account and Configure an IAM User (or Use IRSA)
@@ -111,7 +111,22 @@ cache: true
fileStrategy: "s3"
```
This setting tells LibreChat to use the S3 implementation provided in your code.
<Callout type="warning" title="S3 presigned URLs expire — images and avatars will break">
S3 does not serve files through a CDN. LibreChat accesses S3 files via **presigned URLs**, which are temporary signed tokens with a configurable expiry (`S3_URL_EXPIRY_SECONDS`). AWS caps presigned URL lifetime at 7 days for IAM user credentials, and just a few hours when using temporary credentials (STS/IAM roles such as IRSA). Once a URL expires, the image or avatar it references will appear broken in the UI until the page is refreshed and a new URL is generated.
The refresh logic in LibreChat is not applied consistently — for example, the agent list endpoint returns stored (potentially stale) URLs, while the single-agent endpoint refreshes them. This causes visible broken avatar images in the model selector and chat UI. See the [related discussion](https://github.com/danny-avila/LibreChat/discussions/10280#discussioncomment-14803903) for full context.
**S3 is well-suited for document storage** (PDFs, text files, code) where short-lived presigned download URLs are appropriate. For images and avatars that need to render persistently across the UI, use [Firebase](/docs/configuration/cdn/firebase) or configure `fileStrategies` to route only those types to a CDN-backed strategy:
```yaml filename="librechat.yaml"
fileStrategies:
avatar: "firebase"
image: "firebase"
document: "s3"
```
CloudFront (Amazon's CDN for S3, which eliminates presigned URLs entirely) is planned and in active development.
</Callout>
## Summary
@@ -129,7 +144,7 @@ This setting tells LibreChat to use the S3 implementation provided in your code.
4. **Configure LibreChat:**
- Set `fileStrategy` to `"s3"` in your `librechat.yaml` configuration file.
With these steps, your LibreChat application will use Amazon S3 to handle file uploads, downloads, and deletions, leveraging S3 as your CDN for static assets. Additionally, with IRSA support, your application can run securely on Kubernetes without embedding long-term AWS credentials.
With these steps, your LibreChat application will use Amazon S3 to handle file uploads, downloads, and deletions. Additionally, with IRSA support, your application can run securely on Kubernetes without embedding long-term AWS credentials.
<Callout type="info" title="Note">
Always ensure your AWS credentials remain secure. Do not commit them to a public repository. Adjust IAM policies to follow the principle of least privilege as needed.

29
content/docs/configuration/librechat_yaml/object_structure/config.mdx
View File

@@ -33,12 +33,15 @@ icon: Settings
/>
- **Notes**:
- You can choose from several different CDNs to store files.
- Please refer to the [CDN documentation](/docs/configuration/cdn) for more details
- `"firebase"` is currently the only option that serves files through a true CDN (Content Delivery Network), which means images and avatars are delivered from edge locations globally. S3 and Azure Blob Storage are object storage backends — files are accessible but not CDN-served by default.
- S3 serves files via **presigned URLs** (temporary signed tokens) that expire. Once expired, any image or avatar referencing that URL will appear broken in the UI. This makes S3 unsuitable as a primary strategy for visual assets. See the [related discussion](https://github.com/danny-avila/LibreChat/discussions/10280#discussioncomment-14803903) for details.
- CloudFront (CDN for S3) is planned and in active development.
- For best performance of images and avatars, use `"firebase"` or configure `fileStrategies` to route `avatar` and `image` to a CDN-backed strategy.
- Please refer to the [File Storage & CDN documentation](/docs/configuration/cdn) for setup details
## fileStrategies
Allows granular control over file storage strategies for different file types.
Allows granular control over file storage strategies for different file types.
- **Available Strategies**: "local" | "firebase" | "s3" | "azure_blob"
<OptionTable
@@ -52,8 +55,8 @@ Allows granular control over file storage strategies for different file types.
<OptionTable
options={[
['default', 'String', 'Fallback storage strategy when specific type is not defined. Defaults to "local".', ''],
['avatar', 'String', 'Storage strategy for user and agent avatar images.', ''],
['image', 'String', 'Storage strategy for images uploaded in chats.', ''],
['avatar', 'String', 'Storage strategy for user and agent avatar images. Recommended to use a CDN-backed strategy (`"firebase"`) for best performance.', ''],
['image', 'String', 'Storage strategy for images uploaded in chats. Recommended to use a CDN-backed strategy (`"firebase"`) for best performance.', ''],
['document', 'String', 'Storage strategy for document uploads (PDFs, text files, etc.).', ''],
]}
/>
@@ -61,8 +64,10 @@ Allows granular control over file storage strategies for different file types.
- **Notes**:
- This setting takes precedence over the single `fileStrategy` option
- If a specific file type is not configured, it falls back to `default`, then to `fileStrategy`, and finally to `"local"`
- You can mix strategies based on your needs (e.g., S3 for avatars, local for documents)
- Please refer to the [CDN documentation](/docs/configuration/cdn) for setup details for each storage provider
- Images and avatars need persistent, stable URLs to render correctly across the UI. S3 presigned URLs expire (AWS cap: 7 days for IAM users, hours for STS/role-based credentials), causing broken images in the model selector and chat UI. See the [related discussion](https://github.com/danny-avila/LibreChat/discussions/10280#discussioncomment-14803903) for full context. Use `"firebase"` (the only current CDN-backed strategy) for `avatar` and `image` to avoid this.
- CloudFront support for S3 is in active development and will eliminate presigned URL limitations.
- S3 and Azure Blob Storage are well-suited for `document` storage, where short-lived presigned download URLs are appropriate.
- Please refer to the [File Storage & CDN documentation](/docs/configuration/cdn) for setup details for each storage provider
**Examples:**
@@ -73,18 +78,18 @@ fileStrategies:
```
```yaml filename="fileStrategies - Mixed strategies"
# Mix storage strategies based on file type
# Route images and avatars to CDN, keep documents in object storage
fileStrategies:
avatar: "s3" # Fast global access for avatars
image: "firebase" # Automatic image optimization
document: "local" # Keep documents on-premise for compliance
avatar: "firebase" # CDN delivery for avatars
image: "firebase" # CDN delivery for generated/uploaded images
document: "s3" # Object storage for documents
```
```yaml filename="fileStrategies - Partial configuration"
# Only configure specific types, others use default
fileStrategies:
default: "local"
avatar: "s3" # Only avatars use S3, everything else is local
avatar: "firebase" # Only avatars use Firebase CDN, everything else is local
```
## filteredTools