Storage Configuration

Chatwoot stores uploaded files, attachments, and avatars using Active Storage. You can configure storage to use local disk or cloud storage providers.

Storage Service Selection

ACTIVE_STORAGE_SERVICE

string

required

The storage service to use for file uploads.Options:

local - Store files on local disk
amazon - Amazon S3
google - Google Cloud Storage (GCS)
microsoft - Azure Storage
s3_compatible - S3-compatible services (DigitalOcean Spaces, Minio, etc.)

Default: local

DIRECT_UPLOADS_ENABLED

boolean

Enable direct uploads to cloud storage using signed URLs.When enabled, files are uploaded directly from the browser to your cloud storage, reducing server load.Requirements:

Proper CORS configuration on your cloud storage bucket
See Active Storage CORS Configuration

Default: false

Local Storage

Store files on the local filesystem. Suitable for single-server deployments. Configuration:

ACTIVE_STORAGE_SERVICE=local

Storage location: <rails-root>/storage/

Local storage is not recommended for multi-server deployments or containerized environments where data persistence is required. Use cloud storage instead.

Amazon S3

Store files in Amazon S3 buckets.

Configuration Variables

S3_BUCKET_NAME

string

required

Name of your S3 bucket.Example: chatwoot-uploads

AWS_ACCESS_KEY_ID

string

required

AWS access key ID with permissions to access the S3 bucket.

AWS_SECRET_ACCESS_KEY

string

required

AWS secret access key corresponding to the access key ID.

AWS_REGION

string

required

AWS region where your S3 bucket is located.Examples:

us-east-1
eu-west-1
ap-southeast-1

Example Configuration

ACTIVE_STORAGE_SERVICE=amazon
S3_BUCKET_NAME=my-chatwoot-uploads
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_REGION=us-east-1

S3 Bucket Setup

Create an S3 bucket in your AWS account
Configure bucket permissions:
- Create an IAM user with S3 access
- Attach a policy with s3:PutObject, s3:GetObject, s3:DeleteObject permissions
If using direct uploads, configure CORS:

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
    "AllowedOrigins": ["https://your-chatwoot-domain.com"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3000
  }
]

IAM Policy Example

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

For detailed S3 setup instructions, see Configuring S3 Bucket as Cloud Storage

Google Cloud Storage (GCS)

Store files in Google Cloud Storage buckets.

Configuration Variables

GCS_PROJECT

string

required

Google Cloud project ID.Example: my-project-12345

GCS_CREDENTIALS

string

required

Google Cloud service account credentials in JSON format.Note: This should be the entire JSON key file content, not a file path.Format: {"type":"service_account","project_id":"...","private_key":"..."}

GCS_BUCKET

string

required

Name of your GCS bucket.Example: chatwoot-uploads

Example Configuration

ACTIVE_STORAGE_SERVICE=google
GCS_PROJECT=my-project-12345
GCS_BUCKET=chatwoot-uploads
GCS_CREDENTIALS='{"type":"service_account","project_id":"my-project-12345","private_key_id":"...","private_key":"...","client_email":"..."}'

GCS Bucket Setup

Create a GCS bucket in your Google Cloud project
Create a service account with Storage Object Admin role
Generate and download a JSON key for the service account
Configure CORS if using direct uploads:

[
  {
    "origin": ["https://your-chatwoot-domain.com"],
    "method": ["GET", "PUT", "POST", "DELETE"],
    "responseHeader": ["Content-Type", "ETag"],
    "maxAgeSeconds": 3000
  }
]

Apply CORS configuration:

gsutil cors set cors.json gs://your-bucket-name

Never commit your GCS credentials JSON to version control. Use environment variables or secrets management.

Azure Storage

Store files in Azure Storage containers.

Configuration Variables

AZURE_STORAGE_ACCOUNT_NAME

string

required

Azure Storage account name.Example: chatwootstorage

AZURE_STORAGE_ACCESS_KEY

string

required

Azure Storage account access key.

AZURE_STORAGE_CONTAINER

string

required

Name of the Azure Storage container.Example: uploads

Example Configuration

ACTIVE_STORAGE_SERVICE=microsoft
AZURE_STORAGE_ACCOUNT_NAME=chatwootstorage
AZURE_STORAGE_ACCESS_KEY=your-access-key-here
AZURE_STORAGE_CONTAINER=uploads

Azure Storage Setup

Create a storage account in Azure Portal
Create a container within the storage account
Get the access key from “Access keys” section
Configure CORS if using direct uploads:

CORS rules:

Allowed origins: https://your-chatwoot-domain.com
Allowed methods: GET, PUT, POST, DELETE, OPTIONS
Allowed headers: *
Exposed headers: ETag, Content-Type
Max age: 3000

S3-Compatible Storage

Use S3-compatible services like DigitalOcean Spaces, Minio, Wasabi, or other providers.

Configuration Variables

STORAGE_BUCKET_NAME

string

required

Name of your storage bucket.Example: chatwoot-uploads

STORAGE_ACCESS_KEY_ID

string

required

Access key ID for the storage service.

STORAGE_SECRET_ACCESS_KEY

string

required

Secret access key for the storage service.

STORAGE_REGION

string

required

Region or location of your storage bucket.Examples:

us-east-1 (AWS-style)
nyc3 (DigitalOcean)
auto (Minio)

STORAGE_ENDPOINT

string

required

Custom endpoint URL for the S3-compatible service.Examples:

DigitalOcean Spaces: https://nyc3.digitaloceanspaces.com
Minio: https://minio.example.com
Wasabi: https://s3.wasabisys.com

STORAGE_FORCE_PATH_STYLE

boolean

Force path-style URLs instead of virtual-hosted-style.Note: Required for some S3-compatible services like Minio.Default: false

Example: DigitalOcean Spaces

ACTIVE_STORAGE_SERVICE=s3_compatible
STORAGE_BUCKET_NAME=chatwoot-uploads
STORAGE_ACCESS_KEY_ID=your-spaces-key
STORAGE_SECRET_ACCESS_KEY=your-spaces-secret
STORAGE_REGION=nyc3
STORAGE_ENDPOINT=https://nyc3.digitaloceanspaces.com
STORAGE_FORCE_PATH_STYLE=false

Example: Minio

ACTIVE_STORAGE_SERVICE=s3_compatible
STORAGE_BUCKET_NAME=chatwoot
STORAGE_ACCESS_KEY_ID=minioadmin
STORAGE_SECRET_ACCESS_KEY=minioadmin
STORAGE_REGION=us-east-1
STORAGE_ENDPOINT=http://minio:9000
STORAGE_FORCE_PATH_STYLE=true

Example: Wasabi

ACTIVE_STORAGE_SERVICE=s3_compatible
STORAGE_BUCKET_NAME=chatwoot-uploads
STORAGE_ACCESS_KEY_ID=your-wasabi-key
STORAGE_SECRET_ACCESS_KEY=your-wasabi-secret
STORAGE_REGION=us-east-1
STORAGE_ENDPOINT=https://s3.wasabisys.com
STORAGE_FORCE_PATH_STYLE=false

Storage Migration

If you need to migrate from one storage provider to another:

Configure the new storage provider
Update ACTIVE_STORAGE_SERVICE to the new provider
Use the Rails Active Storage migration task:

rails active_storage:migrate_to_new_service

Always backup your data before migrating storage providers.

Troubleshooting

Files not uploading

Verify storage credentials are correct
Check bucket/container exists and is accessible
Review Chatwoot logs for detailed error messages
Verify IAM/service account permissions

CORS errors with direct uploads

Ensure CORS is properly configured on your storage bucket
Verify allowed origins match your Chatwoot domain exactly
Check browser console for specific CORS error messages
Ensure HTTPS is used in production

Permission errors

Verify the IAM user or service account has required permissions
For S3: Ensure both bucket-level and object-level permissions
For GCS: Verify service account has Storage Object Admin role
For Azure: Check container access level and access key validity

Path-style vs virtual-hosted-style

Some S3-compatible services require STORAGE_FORCE_PATH_STYLE=true. If you see URL-related errors, try toggling this setting. Path-style: https://endpoint.com/bucket/object
Virtual-hosted-style: https://bucket.endpoint.com/object

Environment Variables - Complete environment variable reference
PostgreSQL Configuration - Database configuration

Deployment

Configuration

Operations

Storage Configuration

Storage Service Selection

Local Storage

Amazon S3

Configuration Variables

Example Configuration

S3 Bucket Setup

IAM Policy Example

Google Cloud Storage (GCS)

Configuration Variables

Example Configuration

GCS Bucket Setup

Azure Storage

Configuration Variables

Example Configuration

Azure Storage Setup

S3-Compatible Storage

Configuration Variables

Example: DigitalOcean Spaces

Example: Minio

Example: Wasabi

Storage Migration

Troubleshooting

Files not uploading

CORS errors with direct uploads

Permission errors

Path-style vs virtual-hosted-style

Build docs developers (and LLMs) love

Deployment

Configuration

Operations

Documentation Index

​Storage Service Selection

​Local Storage

​Amazon S3

​Configuration Variables

​Example Configuration

​S3 Bucket Setup

​IAM Policy Example

​Google Cloud Storage (GCS)

​Configuration Variables

​Example Configuration

​GCS Bucket Setup

​Azure Storage

​Configuration Variables

​Example Configuration

​Azure Storage Setup

​S3-Compatible Storage

​Configuration Variables

​Example: DigitalOcean Spaces

​Example: Minio

​Example: Wasabi

​Storage Migration

​Troubleshooting

​Files not uploading

​CORS errors with direct uploads

​Permission errors

​Path-style vs virtual-hosted-style

​Related Configuration

Build docs developers (and LLMs) love

Storage Service Selection

Local Storage

Amazon S3

Configuration Variables

Example Configuration

S3 Bucket Setup

IAM Policy Example

Google Cloud Storage (GCS)

Configuration Variables

Example Configuration

GCS Bucket Setup

Azure Storage

Configuration Variables

Example Configuration

Azure Storage Setup

S3-Compatible Storage

Configuration Variables

Example: DigitalOcean Spaces

Example: Minio

Example: Wasabi

Storage Migration

Troubleshooting

Files not uploading

CORS errors with direct uploads

Permission errors

Path-style vs virtual-hosted-style

Related Configuration