librechat.ai/content/docs/configuration/cdn/s3.mdx

---
title: Amazon S3 CDN
icon: Warehouse
description: This document provides instructions for setting up Amazon S3 as a CDN 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.

## 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",
        "s3:DeleteObject"
      ],
      "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_ENDPOINT_URL=your_endpoint_url
```

- **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.
- **AWS_ENDPOINT_URL:** (Optional) The custom AWS endpoint URL

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.3.4
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>