Azure Blob Storage

Production Setup

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

1. Sign in to Azure:

   • Open the Azure Portal 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:

# 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:

version: 1.3.5
cache: true
fileStrategy: "azure_blob"

fileStrategies:
  avatar: "firebase"
  image: "firebase"
  document: "azure_blob"

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_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. Managed Identity provides a secure alternative by eliminating the need for long-term credentials.

Local Development with Azurite

For local development and testing, you can use Azurite, an Azure Storage emulator that provides a local environment for testing your Azure Blob Storage integration without needing an actual Azure account.

1. Set Up Azurite

You can run Azurite in several ways:

Option A: Using VS Code Extension (Recommended for Development)

1. Install the Azurite extension for VS Code
2. Open the command palette (Ctrl+Shift+P or Cmd+Shift+P)
3. Search for and select "Azurite: Start"

This will start Azurite in the background with default settings.

Option B: Using Docker

docker run -p 10000:10000 -p 10001:10001 -p 10002:10002 mcr.microsoft.com/azure-storage/azurite

Option C: Using npm

npm install -g azurite
azurite --silent --location /path/to/azurite/workspace --debug /path/to/debug/log

2. Configure Environment Variables for Local Development

Add the following environment variables to your .env file:

# Azurite connection string for local development
AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;"
AZURE_STORAGE_PUBLIC_ACCESS=true
AZURE_CONTAINER_NAME=files

Notes:

• The AccountKey value is the default development key used by Azurite
• The connection uses http protocol instead of https for local development
• The BlobEndpoint points to the local Azurite instance running on port 10000

3. Verify the Connection

To verify that your application can connect to the local Azurite instance:

1. Start your LibreChat application
2. Attempt to upload a file through the interface
3. Check the Azurite logs to confirm the connection and operations

If you're using the VS Code extension, you can view the Azurite logs in the Output panel by selecting "Azurite Blob" from the dropdown.