Skip to main content

The two storage modes

Collabase stores uploaded files — attachments, images, banners — in one of two places: You do not need S3. Every standard installation runs on local disk and can stay there.

Compatible providers

Collabase works with any storage that speaks the S3 protocol. Tested and known-good setups:

Setting up the bucket

Create one private bucket for Collabase. Three rules matter:
  • The bucket must not be publicly readable. Collabase serves every file through the application, where access permissions are checked. A public bucket would let anyone bypass those checks with a direct link. Do not attach public-read policies or ACLs.
  • Create a dedicated access key for Collabase: do not reuse an admin key.
  • Grant only the three permissions Collabase needs, limited to that one bucket:
Collabase does not need s3:ListBucket, bucket administration rights, or access to any other bucket. A minimal policy (AWS and MinIO use the same format):
Optional but recommended: enable server-side encryption and object versioning on the bucket in your provider’s console. Collabase does not require either, but versioning gives you an undo for accidental deletions.

Configuration

Add these settings to your .env (Docker) or values file (Kubernetes): On Kubernetes, the same settings live under storage.* in the Helm values — see the Kubernetes installation guide.

Encrypt files with your own key

For a provider that shares one project between several customers, you can encrypt every file with a key only you hold. Set S3_SSE_CUSTOMER_KEY to a 256-bit key in base64 (44 characters ending in =). On Kubernetes, set storage.s3.sseCustomerKey: true and put the key under s3SseCustomerKey in your own secret.
Collabase and the provider never store this key. If you lose it, the files are lost. Keep a copy somewhere safe before you switch it on. Files stored without the key cannot be read once it is set, so use it from the start on a new bucket.
Some storage providers cannot copy a file that is encrypted with your key and answer the request with status 501. Collabase then copies the file through the application instead: it reads the file and writes it again. This works the same for you, but copying takes longer, in proportion to the size of the file.

Switching an existing installation to S3

Your existing files must be copied into the bucket once. Collabase ships a migration command that does this and is safe to re-run (already-copied files are skipped):
1

Prepare

Create the bucket and access key as described above. Do not change .env yet.
2

Preview the migration

This lists what would be copied without changing anything.
3

Run it

Run the same command without --dry-run. It copies all files and updates stored image links so they keep working from the bucket.
4

Switch the configuration

Add the STORAGE_DRIVER=s3 block to your .env, then restart:
5

Verify, then clean up

Open a few pages with attachments and images. When everything loads, the old local files under the Docker volumes are no longer used and can be removed at your leisure.

Troubleshooting

Uploads fail after switching. Check the access key and that the policy covers s3:PutObject on the bucket. The application log names the failing operation. Images load but new uploads fail. The key can read but not write — the policy is missing s3:PutObject. Everything fails against MinIO or a self-hosted service. Make sure S3_FORCE_PATH_STYLE is true (the default) and the endpoint includes the scheme, for example https://minio.internal:9000. The health check lists storage. /api/health names storage as degraded when the bucket does not answer within three seconds. The application keeps running; check the endpoint, the bucket name and the network path. I need help. Open a ticket at collabase.featurebase.app with the output of a support bundle: bash deployment/docker/install.sh support-bundle. See also Inbound mailbox.
Last modified on November 13, 2026