mirror of
https://github.com/LibreChat-AI/librechat.ai.git
synced 2026-03-27 10:48:32 +07:00
feat: Add Azure Blob Storage and Amazon S3 CDN setup documentation and update metadata (#256)
* feat: Add Azure Blob Storage CDN setup documentation and update metadata * feat: Add Amazon S3 CDN setup documentation and update existing CDN options * feat: Enhance Amazon S3 CDN setup documentation with IRSA support for Kubernetes * feat: Update Azure Blob Storage setup documentation to include Managed Identity authentication options
This commit is contained in:
Ruben Talstra
@@ -6,6 +6,7 @@ export default {
|
||||
mongodb: 'MongoDB',
|
||||
pre_configured_ai: 'AI Providers',
|
||||
tools: 'Tools and Plugins',
|
||||
cdn: 'CDN',
|
||||
azure: 'Azure OpenAI',
|
||||
docker_override: 'Docker Override',
|
||||
mod_system: 'Automated Moderation',
|
||||
|
||||
6
pages/docs/configuration/cdn/_meta.ts
Normal file
6
pages/docs/configuration/cdn/_meta.ts
Normal file
@@ -0,0 +1,6 @@
|
||||
export default {
|
||||
index: 'Intro',
|
||||
s3: 'Amazon S3 CDN',
|
||||
azure: 'Azure Blob Storage CDN',
|
||||
firebase: 'Firebase CDN',
|
||||
}
|
||||
105
pages/docs/configuration/cdn/azure.mdx
Normal file
105
pages/docs/configuration/cdn/azure.mdx
Normal file
@@ -0,0 +1,105 @@
|
||||
---
|
||||
title: Azure Blob Storage CDN
|
||||
description: This document provides instructions for setting up Azure Blob Storage CDN for LibreChat
|
||||
---
|
||||
|
||||
# Azure Blob Storage CDN 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.
|
||||
|
||||
## 1. Create an Azure Storage Account
|
||||
|
||||
1. **Sign in to Azure:**
|
||||
- Open the [Azure Portal](https://portal.azure.com/) and sign in with your Microsoft account.
|
||||
|
||||
2. **Create a Storage Account:**
|
||||
- Click on **"Create a resource"** and search for **"Storage account"**.
|
||||
- Click **"Create"** and fill in the required details:
|
||||
- **Subscription & Resource Group:** Choose your subscription and either select an existing resource group or create a new one.
|
||||
- **Storage Account Name:** Enter a unique name (e.g., `mylibrechatstorage`).
|
||||
- **Region:** Select the region closest to your users.
|
||||
- **Performance & Redundancy:** Choose the performance tier and redundancy level that best suit your needs.
|
||||
- Click **"Review + Create"** and then **"Create"**. Wait until the deployment completes.
|
||||
|
||||
## 2. Set Up Authentication
|
||||
|
||||
You have two options for authenticating with your Azure Storage Account:
|
||||
|
||||
### Option A: Using a Connection String
|
||||
|
||||
1. **Navigate to Access Keys:**
|
||||
- In your newly created storage account, go to **"Access keys"** in the sidebar.
|
||||
|
||||
2. **Copy Connection String:**
|
||||
- Copy one of the connection strings provided. This string includes the credentials required to connect to your Blob Storage account.
|
||||
|
||||
### Option B: Using Managed Identity
|
||||
|
||||
If your LibreChat application is running on an Azure service that supports Managed Identity (such as an Azure VM, App Service, or AKS), you can use that instead of a connection string.
|
||||
|
||||
1. **Assign Managed Identity:**
|
||||
- Ensure your Azure resource (VM, App Service, or AKS) has a system-assigned or user-assigned Managed Identity enabled.
|
||||
|
||||
2. **Grant Storage Permissions:**
|
||||
- In your storage account, assign the **Storage Blob Data Contributor** (or a similarly scoped role) to your Managed Identity. This allows your application to access Blob Storage without a connection string.
|
||||
|
||||
## 3. Update Your Environment Variables
|
||||
|
||||
Create or update your `.env` file in your project’s root with the following configuration:
|
||||
|
||||
```bash filename=".env"
|
||||
# Option A: Using a Connection String
|
||||
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=yourAccountKey;EndpointSuffix=core.windows.net
|
||||
|
||||
# Option B: Using Managed Identity (do not set the connection string if using Managed Identity)
|
||||
AZURE_STORAGE_ACCOUNT_NAME=yourAccountName
|
||||
|
||||
AZURE_STORAGE_PUBLIC_ACCESS=false
|
||||
AZURE_CONTAINER_NAME=files
|
||||
```
|
||||
|
||||
- **AZURE_STORAGE_CONNECTION_STRING:** Set this if you are using Option A.
|
||||
- **AZURE_STORAGE_ACCOUNT_NAME:** Set this if you are using Option B (Managed Identity). Do not set both.
|
||||
- **AZURE_STORAGE_PUBLIC_ACCESS:** Set to `false` if you do not want your blobs to be publicly accessible by default. Set to `true` if you need public access (for example, for publicly viewable images).
|
||||
- **AZURE_CONTAINER_NAME:** This is the container name your application will use (e.g., `files`). The application will automatically create this container if it doesn’t exist.
|
||||
|
||||
## 4. Configure LibreChat to Use Azure Blob Storage
|
||||
|
||||
Update your LibreChat configuration file (`librechat.yaml`) to specify that the application should use Azure Blob Storage for file handling:
|
||||
|
||||
```yaml filename="librechat.yaml"
|
||||
version: 1.0.8
|
||||
cache: true
|
||||
fileStrategy: "azure"
|
||||
```
|
||||
|
||||
This setting tells LibreChat to use the Azure Blob Storage implementation provided in your code.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
1. **Create a Storage Account:**
|
||||
Sign in to the Azure Portal, create a storage account, and wait for deployment to finish.
|
||||
|
||||
2. **Set Up Authentication:**
|
||||
- **Option A:** Retrieve the connection string from **"Access keys"** in your storage account.
|
||||
- **Option B:** Use Managed Identity by enabling it on your Azure resource and granting it appropriate storage permissions.
|
||||
|
||||
3. **Update Environment Variables:**
|
||||
In your `.env` file, set either:
|
||||
- `AZURE_STORAGE_CONNECTION_STRING` (for Option A), or
|
||||
- `AZURE_STORAGE_ACCOUNT_NAME` (for Option B), along with:
|
||||
- `AZURE_STORAGE_PUBLIC_ACCESS` and
|
||||
- `AZURE_CONTAINER_NAME`.
|
||||
|
||||
4. **Configure LibreChat:**
|
||||
Set `fileStrategy` to `"azure"` 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.
|
||||
|
||||
---
|
||||
|
||||
<Callout type="info" title="Note">
|
||||
Always ensure that your connection string remains secure and never commit it to a public repository. Adjust the public access setting as needed based on your application’s security requirements.
|
||||
</Callout>
|
||||
21
pages/docs/configuration/cdn/index.mdx
Normal file
21
pages/docs/configuration/cdn/index.mdx
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
title: CDN
|
||||
description: CDN setup instructions
|
||||
---
|
||||
|
||||
# CDN
|
||||
|
||||
<Callout type="info" title="Note">
|
||||
This guide covers the setup instructions for three CDN options. Choose the one that best meets your deployment requirements.
|
||||
</Callout>
|
||||
|
||||
## Setup Instructions:
|
||||
|
||||
### Amazon S3 CDN
|
||||
- [Amazon S3 CDN](/docs/configuration/cdn/s3)
|
||||
|
||||
### Azure Blob Storage CDN
|
||||
- [Azure Blob Storage CDN](/docs/configuration/cdn/azure)
|
||||
|
||||
### Firebase CDN
|
||||
- [Firebase CDN](/docs/configuration/cdn/firebase)
|
||||
134
pages/docs/configuration/cdn/s3.mdx
Normal file
134
pages/docs/configuration/cdn/s3.mdx
Normal file
@@ -0,0 +1,134 @@
|
||||
---
|
||||
title: Amazon S3 CDN
|
||||
description: This document provides instructions for setting up Amazon S3 as a CDN for LibreChat.
|
||||
---
|
||||
|
||||
# Amazon S3 CDN Setup
|
||||
|
||||
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.
|
||||
|
||||
## 1. Create an AWS Account and Configure an IAM User (or Use IRSA)
|
||||
|
||||
### Option A: Using an IAM User with Explicit Credentials
|
||||
|
||||
1. **Sign in to AWS:**
|
||||
- Open the [AWS Management Console](https://aws.amazon.com/console/) and sign in with your account.
|
||||
|
||||
2. **Create or Use an Existing IAM User:**
|
||||
- Navigate to the **IAM (Identity and Access Management)** section.
|
||||
- Create a new IAM user with **Programmatic Access** or select an existing one.
|
||||
- Attach an appropriate policy (for example, `AmazonS3FullAccess` or a custom policy with limited S3 permissions).
|
||||
- After creating the user, you will receive an **AWS_ACCESS_KEY_ID** and **AWS_SECRET_ACCESS_KEY**. Store these securely.
|
||||
|
||||
### Option B: Using IRSA (IAM Roles for Service Accounts) in Kubernetes
|
||||
|
||||
If you are deploying LibreChat on Kubernetes (e.g. on EKS), you can use IRSA to assign AWS permissions to your pods without having to provide explicit credentials. To use IRSA:
|
||||
|
||||
1. **Create a Trust Policy** for your EKS service account (example below):
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Effect": "Allow",
|
||||
"Principal": {
|
||||
"Federated": "arn:aws:iam::{AWS_ACCOUNT}:oidc-provider/oidc.eks.us-east-1.amazonaws.com/id/{EKS_OIDC}"
|
||||
},
|
||||
"Action": "sts:AssumeRoleWithWebIdentity",
|
||||
"Condition": {
|
||||
"StringEquals": {
|
||||
"oidc.eks.us-east-1.amazonaws.com/id/{EKS_OIDC}:sub": "system:serviceaccount:librechat:librechat",
|
||||
"oidc.eks.us-east-1.amazonaws.com/id/{EKS_OIDC}:aud": "sts.amazonaws.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
2. **Create a Policy** that grants necessary S3 permissions (example below):
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "VisualEditor0",
|
||||
"Effect": "Allow",
|
||||
"Action": [
|
||||
"s3:PutObject",
|
||||
"s3:GetObjectAcl",
|
||||
"s3:GetObject",
|
||||
"s3:ListBucket"
|
||||
],
|
||||
"Resource": [
|
||||
"arn:aws:s3:::my-example-librechat-bucket/*",
|
||||
"arn:aws:s3:::my-example-librechat-bucket"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
3. **Annotate your Kubernetes ServiceAccount:**
|
||||
Ensure your LibreChat pods use a service account annotated for IRSA. This way, the AWS SDK in your application (using our updated S3 initialization code) will automatically use the temporary credentials provided by IRSA without needing the environment variables for AWS credentials.
|
||||
|
||||
## 2. Create an S3 Bucket
|
||||
|
||||
1. **Open the S3 Console:**
|
||||
- Go to the [Amazon S3 console](https://s3.console.aws.amazon.com/s3/).
|
||||
|
||||
2. **Create a New Bucket:**
|
||||
- Click **"Create bucket"**.
|
||||
- **Bucket Name:** Enter a unique name (e.g., `mylibrechatbucket`).
|
||||
- **Region:** Select the AWS region closest to your users (for example, `us-east-1` or `eu-west-1`).
|
||||
- **Configure Options:** Set other options as needed, then click **"Create bucket"**.
|
||||
|
||||
## 3. Update Your Environment Variables
|
||||
|
||||
If you are **not** using IRSA, create or update your `.env` file in your project’s root directory with the following configuration:
|
||||
|
||||
```bash filename=".env"
|
||||
AWS_ACCESS_KEY_ID=your_access_key_id
|
||||
AWS_SECRET_ACCESS_KEY=your_secret_access_key
|
||||
AWS_REGION=your_selected_region
|
||||
AWS_BUCKET_NAME=your_bucket_name
|
||||
```
|
||||
|
||||
- **AWS_ACCESS_KEY_ID:** Your IAM user's access key.
|
||||
- **AWS_SECRET_ACCESS_KEY:** Your IAM user's secret key.
|
||||
- **AWS_REGION:** The AWS region where your S3 bucket is located.
|
||||
- **AWS_BUCKET_NAME:** The name of the S3 bucket you created.
|
||||
|
||||
If you are using **IRSA** on Kubernetes, you do **not** need to set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` in your environment. The AWS SDK will automatically obtain temporary credentials via the service account assigned to your pod. Ensure that `AWS_REGION` and `AWS_BUCKET_NAME` are still provided.
|
||||
|
||||
## 4. Configure LibreChat to Use Amazon S3
|
||||
|
||||
Update your LibreChat configuration file (`librechat.yaml`) to specify that the application should use Amazon S3 for file handling:
|
||||
|
||||
```yaml filename="librechat.yaml"
|
||||
version: 1.0.8
|
||||
cache: true
|
||||
fileStrategy: "s3"
|
||||
```
|
||||
|
||||
This setting tells LibreChat to use the S3 implementation provided in your code.
|
||||
|
||||
## Summary
|
||||
|
||||
1. **Create an AWS Account & IAM User (or configure IRSA):**
|
||||
- For traditional deployments, create an IAM user with programmatic access and obtain your access keys.
|
||||
- For Kubernetes deployments (e.g., on EKS), set up IRSA so that your pods automatically obtain temporary credentials.
|
||||
|
||||
2. **Create an S3 Bucket:**
|
||||
- Use the Amazon S3 console to create a bucket, choosing a unique name and region.
|
||||
|
||||
3. **Update Environment Variables:**
|
||||
- For non-IRSA: set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, and `AWS_BUCKET_NAME` in your `.env` file.
|
||||
- For IRSA: set only `AWS_REGION` and `AWS_BUCKET_NAME`; ensure your pod’s service account is correctly annotated.
|
||||
|
||||
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.
|
||||
|
||||
<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.
|
||||
</Callout>
|
||||
Reference in New Issue
Block a user