Amazon S3

Amazon S3 è un servizio di archiviazione oggetti scalabile e sicuro che può essere utilizzato come backend di archiviazione file per LibreChat. Segui questi passaggi per configurare il tuo bucket S3.

1. Crea un account AWS e configura un utente IAM (o utilizza IRSA)

Opzione A: Utilizzo di un utente IAM con credenziali esplicite

1. Accedi ad AWS:

   • Apri la AWS Management Console e accedi con il tuo account.

2. Crea o utilizza un utente IAM esistente:

   • Passa alla sezione IAM (Identity and Access Management).
   • Crea un nuovo utente IAM con Programmatic Access o selezionane uno esistente.
   • Allega una policy appropriata (ad esempio, AmazonS3FullAccess o una policy personalizzata con autorizzazioni S3 limitate).
   • Dopo aver creato l'utente, riceverai un AWS_ACCESS_KEY_ID e una AWS_SECRET_ACCESS_KEY. Conservale in modo sicuro.

Opzione B: Utilizzo di IRSA (IAM Roles for Service Accounts) in Kubernetes

Se stai distribuendo LibreChat su Kubernetes (ad esempio su EKS), puoi utilizzare IRSA per assegnare autorizzazioni AWS ai tuoi pod senza dover fornire credenziali esplicite. Per utilizzare IRSA:

1. Crea una Trust Policy per il tuo service account EKS (esempio sotto):

   {
     "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. Crea una Policy che conceda le autorizzazioni S3 necessarie (esempio sotto):

{
  "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 il vostro ServiceAccount Kubernetes:
   Assicuratevi che i pod di LibreChat utilizzino un service account annotato per IRSA. In questo modo, l'SDK AWS nell'applicazione (utilizzando il nostro codice di inizializzazione S3 aggiornato) utilizzerà automaticamente le credenziali temporanee fornite da IRSA senza la necessità di variabili d'ambiente per le credenziali AWS.

2. Crea un bucket S3

1. Apri la console S3:

• Vai alla console Amazon S3.

2. Crea un nuovo bucket:

• Fai clic su "Create bucket".
• Nome del bucket: Inserisci un nome univoco (ad esempio, mylibrechatbucket).
• Regione: Seleziona la regione AWS più vicina ai tuoi utenti (ad esempio, us-east-1 o eu-west-1).
• Opzioni di configurazione: Imposta le altre opzioni come necessario, quindi fai clic su "Create bucket".

3. Aggiorna le tue variabili d'ambiente

Se non stai utilizzando IRSA, crea o aggiorna il tuo file .env nella directory principale del progetto con la seguente configurazione:

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=https://your_endpoint_url
# AWS_FORCE_PATH_STYLE=false

• AWS_ACCESS_KEY_ID: La chiave di accesso del tuo utente IAM.
• AWS_SECRET_ACCESS_KEY: La secret key del tuo utente IAM.
• AWS_REGION: La regione AWS in cui si trova il tuo bucket S3.
• AWS_BUCKET_NAME: Il nome del bucket S3 che hai creato.
• AWS_ENDPOINT_URL: (Opzionale) L'URL personalizzato dell'endpoint AWS. Richiesto per servizi compatibili con S3 come MinIO, Cloudflare R2, Hetzner Object Storage, Backblaze B2 e IDrive e2. Includere lo schema dell'URL, come https://a7g8.da.idrivee2-32.com; i valori senza http:// o https:// possono causare un errore Invalid URL durante lo streaming dei file.
• AWS_FORCE_PATH_STYLE: (Opzionale) Impostare su true per i provider che richiedono URL in stile percorso (endpoint/bucket/key) anziché in stile virtual-hosted (bucket.endpoint/key). Richiesto per Hetzner Object Storage, MinIO e provider simili i cui certificati SSL non coprono i sottodomini dei bucket. Non necessario per AWS S3 o Cloudflare R2. Predefinito: false.

Se stai utilizzando IRSA su Kubernetes, non è necessario impostare AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY nel tuo ambiente. L'SDK AWS otterrà automaticamente le credenziali temporanee tramite l'account di servizio assegnato al tuo pod. Assicurati che AWS_REGION e AWS_BUCKET_NAME siano comunque forniti.

4. Configurare LibreChat per utilizzare Amazon S3

Aggiorna il tuo file di configurazione LibreChat (librechat.yaml) per specificare che l'applicazione deve utilizzare Amazon S3 per la gestione dei file:

version: 1.3.11
cache: true
fileStrategy: 's3'

fileStrategies:
  avatar: 'cloudfront'
  image: 'cloudfront'
  document: 's3'

Riepilogo

1. Crea un account AWS e un utente IAM (o configura IRSA):

• Per le distribuzioni tradizionali, crea un utente IAM con accesso programmatico e ottieni le tue chiavi di accesso.
• Per le distribuzioni Kubernetes (ad esempio su EKS), configura IRSA in modo che i tuoi pod ottengano automaticamente credenziali temporanee.

2. Crea un bucket S3:

• Utilizza la console Amazon S3 per creare un bucket, scegliendo un nome univoco e una regione.

3. Aggiorna le variabili d'ambiente:

• Per non-IRSA: imposta AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION e AWS_BUCKET_NAME nel tuo file .env.
• Per IRSA: imposta solo AWS_REGION e AWS_BUCKET_NAME; assicurati che l'account di servizio del tuo pod sia annotato correttamente.

4. Configura LibreChat:

• Imposta fileStrategy su "s3" nel tuo file di configurazione librechat.yaml, oppure utilizza fileStrategies per mantenere i documenti su S3 inviando al contempo immagini e avatar tramite CloudFront.

Con questi passaggi, la tua applicazione LibreChat utilizzerà Amazon S3 per gestire il caricamento, il download e l'eliminazione dei file. Inoltre, grazie al supporto IRSA, la tua applicazione può essere eseguita in modo sicuro su Kubernetes senza incorporare credenziali AWS a lungo termine.