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. If you want object storage without a cloud account, the repository’s Compose file can start one for you: RustFS.

​
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

​
Bundled object storage: RustFS

The repository’s docker-compose.yml includes RustFS, an S3-compatible object store, behind the opt-in s3 profile. It gives you object storage on your own machine, with no cloud account. To Ragen it is an ordinary S3 store: STORAGE_PROVIDER=s3, pointed at localhost.

​
With the installer

Answer RustFS — self-hosted object storage, started with the stack to the storage question in create-ragen-app. The installer then:
  • generates an access key and a secret;
  • writes them to .env for Compose, and the same pair to .env.local as the S3_* variables the apps read;
  • starts the s3 profile together with the rest of the stack.
If you run the installer again in the same directory, it keeps the keys already in .env, because the store holds your files under those keys.

​
By hand

Put the keys in two files: Compose reads .env, and the apps on the host read .env.local.
.env
.env.local
Then start the profile:
The profile starts three services:
Both files need the same key pair. If .env and .env.local disagree, every upload fails with a signature error. If .env has no RUSTFS_* keys at all, RustFS starts with default keys that are written in docker-compose.yml for anyone to read. That is fine for a trial, but set your own keys before the store holds real documents.
Running the apps in containers too? With npm run ragen:up:everything, the apps reach RustFS by its service name, not by localhost. Put the S3_* variables in .env as well, and set S3_CONTAINER_ENDPOINT_URL=http://rustfs:9000. The full-app Compose file uses it in place of S3_ENDPOINT_URL. The installer writes both for you.
The bucket-init service always creates a bucket named ragen, so keep S3_BUCKET_NAME=ragen unless you create a different bucket yourself.

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

RustFS

Bundled with the repository’s Compose file, behind the s3 profile. Requires S3_FORCE_PATH_STYLE=true.

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.