Cloud Storage Integrations

Overview

Open WebUI supports cloud storage backends for scalable file storage. Choose between local filesystem, Amazon S3, Google Cloud Storage, or Azure Blob Storage based on your deployment needs.

Storage Options

Local Storage

Default filesystem storage

Amazon S3

S3 and S3-compatible storage

Google Cloud Storage

GCS buckets

Azure Blob Storage

Azure Storage containers

Local Storage (Default)

Files are stored in the local filesystem.

Configuration

# Default - no configuration needed
STORAGE_PROVIDER=local
DATA_DIR=/app/backend/data

Directory Structure

data/
├── uploads/           # User-uploaded files
├── cache/             # Temporary cache
└── ...

Use Cases

Single-server deployments

Development environments

Small-scale production

Local storage is not recommended for:

Multi-node deployments
High-availability setups
Large file volumes

Amazon S3

Scalable object storage compatible with S3 API.

Installation

# Already included in requirements.txt
boto3==1.42.44

File: backend/requirements.txt:120

Configuration

STORAGE_PROVIDER=s3

# AWS Credentials
S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

# S3 Configuration
S3_BUCKET_NAME=open-webui-storage
S3_REGION_NAME=us-east-1
S3_ENDPOINT_URL=  # Optional, for S3-compatible services
S3_KEY_PREFIX=uploads/  # Optional prefix for all keys

# Advanced Options
S3_USE_ACCELERATE_ENDPOINT=false
S3_ADDRESSING_STYLE=auto  # auto, path, or virtual
S3_ENABLE_TAGGING=false

docker run -d -p 3000:8080 \
  -e STORAGE_PROVIDER=s3 \
  -e S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE \
  -e S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
  -e S3_BUCKET_NAME=open-webui-storage \
  -e S3_REGION_NAME=us-east-1 \
  -v open-webui:/app/backend/data \
  ghcr.io/open-webui/open-webui:main

apiVersion: v1
kind: Secret
metadata:
  name: s3-credentials
stringData:
  accessKeyId: AKIAIOSFODNN7EXAMPLE
  secretAccessKey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: storage-config
data:
  STORAGE_PROVIDER: "s3"
  S3_BUCKET_NAME: "open-webui-storage"
  S3_REGION_NAME: "us-east-1"

File: backend/open_webui/config.py:953

S3-Compatible Services

MinIO
Backblaze B2
DigitalOcean Spaces
Wasabi

STORAGE_PROVIDER=s3
S3_ENDPOINT_URL=http://minio:9000
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_BUCKET_NAME=open-webui
S3_ADDRESSING_STYLE=path

STORAGE_PROVIDER=s3
S3_ENDPOINT_URL=https://s3.us-west-002.backblazeb2.com
S3_ACCESS_KEY_ID=your-key-id
S3_SECRET_ACCESS_KEY=your-app-key
S3_BUCKET_NAME=your-bucket
S3_REGION_NAME=us-west-002

STORAGE_PROVIDER=s3
S3_ENDPOINT_URL=https://nyc3.digitaloceanspaces.com
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
S3_BUCKET_NAME=your-space-name
S3_REGION_NAME=nyc3

STORAGE_PROVIDER=s3
S3_ENDPOINT_URL=https://s3.wasabisys.com
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
S3_BUCKET_NAME=your-bucket
S3_REGION_NAME=us-east-1

IAM Policy

Minimum required permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::open-webui-storage",
        "arn:aws:s3:::open-webui-storage/*"
      ]
    }
  ]
}

With tagging enabled:

{
  "Effect": "Allow",
  "Action": [
    "s3:GetObject",
    "s3:PutObject",
    "s3:DeleteObject",
    "s3:ListBucket",
    "s3:PutObjectTagging",
    "s3:GetObjectTagging"
  ],
  "Resource": [
    "arn:aws:s3:::open-webui-storage",
    "arn:aws:s3:::open-webui-storage/*"
  ]
}

Advanced Features

Transfer Acceleration

S3_USE_ACCELERATE_ENDPOINT=true

Requires S3 Transfer Acceleration to be enabled on the bucket.File: backend/open_webui/config.py:961

Object Tagging

S3_ENABLE_TAGGING=true

Automatically tags objects with metadata for organization.File: backend/open_webui/config.py:965

Custom Key Prefix

S3_KEY_PREFIX=production/uploads/

Adds a prefix to all object keys for organization.File: backend/open_webui/config.py:959

Google Cloud Storage

Scalable object storage on Google Cloud Platform.

Installation

# Already included in requirements.txt
google-cloud-storage==3.9.0

File: backend/requirements.txt:112

Configuration

STORAGE_PROVIDER=gcs
GCS_BUCKET_NAME=open-webui-storage

# Authentication via JSON credentials
GOOGLE_APPLICATION_CREDENTIALS_JSON='{"type":"service_account",...}'

STORAGE_PROVIDER=gcs
GCS_BUCKET_NAME=open-webui-storage
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

docker run -d -p 3000:8080 \
  -e STORAGE_PROVIDER=gcs \
  -e GCS_BUCKET_NAME=open-webui-storage \
  -e GOOGLE_APPLICATION_CREDENTIALS_JSON='$(cat service-account.json)' \
  -v open-webui:/app/backend/data \
  ghcr.io/open-webui/open-webui:main

File: backend/open_webui/config.py:967

Service Account Setup

Create Service Account

In Google Cloud Console:

Navigate to IAM & Admin > Service Accounts
Create a new service account
Grant “Storage Object Admin” role

Generate Key

Click on the service account
Go to Keys tab
Add Key > Create new key
Choose JSON format

Configure Open WebUI

Use the JSON key content in GOOGLE_APPLICATION_CREDENTIALS_JSON

Required IAM Roles

roles/storage.objectAdmin (or custom role with these permissions):
- storage.objects.create
- storage.objects.delete
- storage.objects.get
- storage.objects.list

Bucket Configuration

Recommended bucket settings:

# Create bucket
gsutil mb -l us-central1 gs://open-webui-storage

# Set uniform bucket-level access
gsutil uniformbucketlevelaccess set on gs://open-webui-storage

# Optional: Enable versioning
gsutil versioning set on gs://open-webui-storage

Azure Blob Storage

Microsoft Azure’s object storage solution.

Installation

# Already included in requirements.txt
azure-storage-blob==12.28.0
azure-identity==1.25.1

File: backend/requirements.txt:103

Configuration

STORAGE_PROVIDER=azure

# Azure Storage Account
AZURE_STORAGE_ENDPOINT=https://mystorageaccount.blob.core.windows.net
AZURE_STORAGE_CONTAINER_NAME=open-webui
AZURE_STORAGE_KEY=your-storage-account-key

STORAGE_PROVIDER=azure
AZURE_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=mystorageaccount;AccountKey=your-key;EndpointSuffix=core.windows.net"
AZURE_STORAGE_CONTAINER_NAME=open-webui

STORAGE_PROVIDER=azure
AZURE_STORAGE_ENDPOINT=https://mystorageaccount.blob.core.windows.net
AZURE_STORAGE_CONTAINER_NAME=open-webui
# No key needed - uses managed identity

File: backend/open_webui/config.py:972

Authentication Methods

Storage Account Key
Managed Identity
SAS Token

AZURE_STORAGE_KEY=your-64-char-key==

Find in Azure Portal > Storage Account > Access Keys

# No key required
# Assign "Storage Blob Data Contributor" role to managed identity

Best for Azure VM, AKS, or App Service deployments

AZURE_STORAGE_SAS_TOKEN=?sv=2021-06-08&ss=b&srt=sco...

Generate in Azure Portal > Storage Account > Shared access signature

Container Setup

Create Storage Account

az storage account create \
  --name openwebuistorage \
  --resource-group open-webui-rg \
  --location eastus \
  --sku Standard_LRS

Create Container

az storage container create \
  --name open-webui \
  --account-name openwebuistorage

Configure Access

For managed identity:

az role assignment create \
  --role "Storage Blob Data Contributor" \
  --assignee <managed-identity-id> \
  --scope /subscriptions/<sub-id>/resourceGroups/open-webui-rg/providers/Microsoft.Storage/storageAccounts/openwebuistorage

Migration Between Storage Providers

Migrating storage providers requires manual file transfer. Plan for downtime during migration.

Migration Steps

Backup Current Storage

# For local storage
tar -czf backup.tar.gz /app/backend/data/uploads

# For S3
aws s3 sync s3://old-bucket ./backup/

Setup New Storage

Configure the new storage provider (create bucket/container, set permissions)

Transfer Files

aws s3 sync /app/backend/data/uploads s3://new-bucket/uploads/

gsutil -m rsync -r s3://old-bucket gs://new-bucket

azcopy sync "https://s3.amazonaws.com/old-bucket" \
  "https://mystorageaccount.blob.core.windows.net/container"

Update Configuration

# Update environment variables
STORAGE_PROVIDER=s3  # or gcs, azure
# Add provider-specific configuration

Restart and Verify

docker restart open-webui

# Test file upload and retrieval

Cost Optimization

Lifecycle Policies

Configure automatic archival or deletion of old files

Storage Classes

Use infrequent access tiers for rarely accessed files

Compression

Enable compression for text files before upload

Deduplication

Implement file hashing to avoid duplicate uploads

S3 Lifecycle Example

<LifecycleConfiguration>
  <Rule>
    <ID>MoveToIA</ID>
    <Status>Enabled</Status>
    <Transition>
      <Days>90</Days>
      <StorageClass>STANDARD_IA</StorageClass>
    </Transition>
  </Rule>
</LifecycleConfiguration>

Troubleshooting

Access Denied Errors

S3:

Verify IAM policy permissions
Check bucket policy
Ensure credentials are correct

GCS:

Verify service account has Storage Object Admin role
Check JSON credentials format
Ensure bucket exists and is accessible

Azure:

Verify storage account key or SAS token
Check container exists
Verify managed identity role assignment

Connection Timeout

Check network connectivity
Verify endpoint URL is correct
Check firewall rules
For S3: Verify region is correct

Upload Failures

Check file size limits
Verify sufficient permissions
Check storage quota
Review application logs

Best Practices

Security:
- Use IAM roles instead of access keys when possible
- Enable bucket/container encryption
- Restrict public access
- Rotate credentials regularly
Performance:
- Choose region close to your users/servers
- Enable CDN for frequently accessed files
- Use multipart uploads for large files
Reliability:
- Enable versioning
- Configure backup/replication
- Monitor storage metrics
- Set up alerts for failures
Cost:
- Use lifecycle policies
- Choose appropriate storage class
- Monitor and optimize access patterns
- Clean up unused files

References

AWS S3: docs.aws.amazon.com/s3
Google Cloud Storage: cloud.google.com/storage/docs
Azure Blob Storage: docs.microsoft.com/azure/storage/blobs

​Overview

​Storage Options

Local Storage

Amazon S3

Google Cloud Storage

Azure Blob Storage

​Local Storage (Default)

​Configuration

​Directory Structure

​Use Cases

​Amazon S3

​Installation

​Configuration

​S3-Compatible Services

​IAM Policy

​Advanced Features

​Google Cloud Storage

​Installation

​Configuration

​Service Account Setup

​Required IAM Roles

​Bucket Configuration

​Azure Blob Storage

​Installation

​Configuration

​Authentication Methods

​Container Setup

​Migration Between Storage Providers

​Migration Steps

​Cost Optimization

Lifecycle Policies

Storage Classes

Compression

Deduplication

​S3 Lifecycle Example

​Troubleshooting

​Best Practices

​References

Overview

Storage Options

Local Storage (Default)

Configuration

Directory Structure

Use Cases

Amazon S3

Installation

Configuration

S3-Compatible Services

IAM Policy

Advanced Features

Google Cloud Storage

Installation

Configuration

Service Account Setup

Required IAM Roles

Bucket Configuration

Azure Blob Storage

Installation

Configuration

Authentication Methods

Container Setup

Migration Between Storage Providers

Migration Steps

Cost Optimization

S3 Lifecycle Example

Troubleshooting

Best Practices

References