Skip to main content
When you upload images, videos, or audio files in Volta — whether attaching them to a post or pulling them into the media library — those files need to be stored somewhere. Volta supports two storage backends: the local filesystem for simple setups, and Cloudflare R2 for scalable, cloud-hosted storage. You choose your provider by setting STORAGE_PROVIDER in your .env file.

​
Local Storage (Default)

By default, Volta stores all uploaded media in a local ./uploads/ directory relative to the project root. The backend serves these files directly. 
STORAGE_PROVIDER=local
UPLOAD_DIRECTORY=./uploads
The uploads/ directory is created automatically during installation. No additional configuration is needed.
Local storage is perfectly fine for development environments and small self-hosted teams. If you’re running Volta on a single server with a manageable amount of media, local storage keeps things simple with no external dependencies.
If you’re using local storage in production, make sure to back up your uploads/ directory regularly alongside your PostgreSQL database. Media files are not stored in the database — a database backup alone won’t capture your uploaded files.
For production deployments — especially those with multiple server instances or significant media volume — Cloudflare R2 is the recommended storage backend. R2 is S3-compatible object storage with no egress fees. 
STORAGE_PROVIDER=cloudflare
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_ACCESS_KEY=your-access-key
CLOUDFLARE_SECRET_ACCESS_KEY=your-secret-access-key
CLOUDFLARE_BUCKETNAME=your-bucket-name
CLOUDFLARE_BUCKET_URL=https://your-bucket-url.r2.cloudflarestorage.com/
CLOUDFLARE_REGION=auto

​
Setting Up Cloudflare R2

1

Create an R2 bucket

Log into the Cloudflare dashboard, go to R2 Object Storage, and click Create bucket. Give it a name (e.g. volta-media).
2

Configure public access (optional)

If you want Volta-served media to be publicly accessible (e.g. for embedding images in posts), enable Public access on the bucket and note the public bucket URL.
3

Create an API token

In the R2 section, click Manage R2 API tokens → Create API token. Grant the token Object Read & Write permissions scoped to your bucket. Copy the Access Key ID and Secret Access Key — these are only shown once.
4

Find your Account ID

Your Cloudflare Account ID is shown in the right sidebar of any Cloudflare dashboard page under Account Home.
5

Add the variables to your .env

Fill in all six CLOUDFLARE_* variables in your .env file using the values from the steps above. Set CLOUDFLARE_REGION=auto (this is always correct for R2).
6

Restart Volta

Restart your Volta instance for the new storage configuration to take effect. Newly uploaded files will go to R2 immediately.

​
Variable Reference

VariableDescription
CLOUDFLARE_ACCOUNT_IDYour Cloudflare account ID (found in the dashboard sidebar)
CLOUDFLARE_ACCESS_KEYR2 API token Access Key ID
CLOUDFLARE_SECRET_ACCESS_KEYR2 API token Secret Access Key
CLOUDFLARE_BUCKETNAMEThe name of your R2 bucket
CLOUDFLARE_BUCKET_URLPublic or private URL for the bucket (ends with /)
CLOUDFLARE_REGIONAlways auto for R2

​
Switching Storage Providers

You can switch from local storage to R2 (or vice versa) at any time by updating your .env and restarting Volta. Files uploaded before the switch are not automatically migrated — they remain on the old storage backend. If you want to move existing files, you’ll need to copy them manually (e.g. from ./uploads/ to your R2 bucket) and ensure the file paths are consistent.