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):
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. SetS3_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.
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
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 coverss3: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.