Skip to main content
Ragen stores every file you upload — documents, attachments, and parsed assets — using a pluggable storage backend. By default, files land on the local filesystem so a fresh installation works with no cloud account. When you are ready to run more than one replica or deploy to production, switching to S3-compatible object storage takes four environment variables.

​
Local Storage

When STORAGE_PROVIDER is unset or set to local, Ragen writes files to the path defined by STORAGE_LOCAL_PATH.
.env
Local storage is well suited for single-instance development and testing, or for a single-node self-hosted deployment backed by a persistent mounted volume.
Use S3 for any deployment that runs more than one container replica. With local storage, the worker writes uploaded files to its own container’s disk and the web application cannot read them. A container restart will also lose any files that are not on a mounted volume. Ragen logs a startup warning when STORAGE_PROVIDER=local is combined with TARGET_ENV=production or staging.

​
S3-Compatible Storage

Set STORAGE_PROVIDER=s3 to use any S3-compatible object store. Ragen uses the S3_ prefix for all storage credentials — intentionally different from AWS_ — so you can run Bedrock or KMS at the same time without the two credential sets conflicting.
All variables in this section use the S3_ prefix, not AWS_. The AWS_ prefix is reserved for real AWS services like Bedrock and KMS. This means you can use Scaleway Object Storage for files while simultaneously using AWS Bedrock for model calls, without either credential set interfering with the other.

​
Required Variables

​
Optional Variables

​
Configuration by Provider

Leave S3_ENDPOINT_URL unset to use AWS’s default regional endpoint.
.env

​
Compatible Providers

AWS S3

The reference implementation. Leave S3_ENDPOINT_URL unset.

Cloudflare R2

Zero egress fees. Set S3_REGION=auto and your account endpoint URL.

Scaleway Object Storage

S3-compatible European object storage. Requires S3_FORCE_PATH_STYLE=1.

MinIO

Self-hosted S3-compatible storage. Requires S3_FORCE_PATH_STYLE=1.

Ceph

Distributed object storage for on-premise deployments. Requires S3_FORCE_PATH_STYLE=1.

LocalStack

Local AWS emulation for development and testing.