Operate
File uploads and storage
Keep uploads in the database or in S3 and MinIO, with size and type limits.
Uploads live in the database by default, so one backup covers everything. Switch to S3 or any S3-compatible service, such as MinIO or Cloudflare R2, when files grow.
How uploads work
- Add a file or image field to a collection in Settings → Data model.
- Upload from the record editor in Studio, or through the API. The field stores a reference to an upload in the same workspace.
- Downloads require a signed-in user or a valid token. Generic files are served as attachments.
Limits
| Limit | Value |
|---|---|
| Size per file | 2 MiB |
| Image formats | PNG, JPEG, GIF, WebP |
| Image size | Up to 16 million pixels |
| Recent files in the picker | 50 |
Choose where files live
| Variable | Default | What it does |
|---|---|---|
STORAGE_DRIVER | database | database keeps files inside SQLite, PostgreSQL or MySQL. s3 sends them to a bucket. |
Use S3 or MinIO
Set STORAGE_DRIVER=s3 and these variables:
| Variable | Default | What it does |
|---|---|---|
S3_ENDPOINT | unset | Service URL, such as https://s3.us-east-1.amazonaws.com or http://minio:9000. |
S3_REGION | unset | Bucket region, such as us-east-1. Use auto for Cloudflare R2. |
S3_BUCKET | unset | Bucket name. Kanesh does not create it; create it first. |
S3_ACCESS_KEY_ID | unset | Access key with read and write rights on the bucket. |
S3_SECRET_ACCESS_KEY | unset | Secret for that key. Prefer a mounted secret over plain text. |
S3_FORCE_PATH_STYLE | false | true for MinIO and most S3-compatible services. |
Example for MinIO next to Kanesh in Compose:
STORAGE_DRIVER=s3
S3_ENDPOINT=http://minio:9000
S3_REGION=us-east-1
S3_BUCKET=kanesh-uploads
S3_ACCESS_KEY_ID=kanesh
S3_SECRET_ACCESS_KEY=CHANGE_ME
S3_FORCE_PATH_STYLE=trueKeep the bucket private. Kanesh checks permissions and serves every download itself, so files are never public by URL.
Note: Changing
STORAGE_DRIVERaffects new uploads. Existing files stay where they were saved and keep working.
Backups
- Database storage: backing up the database backs up every upload.
- S3 storage: back up the database and the bucket. Turn on bucket versioning to recover deleted or overwritten files.
Good to know
- CSV and JSON exports contain file IDs, not the files themselves.