S3-compatible storage

Trestle can place file objects in a private S3-compatible bucket while retaining the same authenticated file API and database metadata boundary as local storage.

Configuration

TRESTLE_STORAGE_BACKEND=s3
TRESTLE_S3_ENDPOINT=https://objects.example.com
TRESTLE_S3_REGION=us-east-1
TRESTLE_S3_BUCKET=trestle
TRESTLE_S3_ACCESS_KEY=...
TRESTLE_S3_SECRET_KEY=...

Non-loopback endpoints must use HTTPS. Credentials are startup-only secrets: the dashboard status endpoint returns the provider and quota, never keys. Trestle signs requests with AWS Signature Version 4 and uses path-style bucket URLs for broad compatible-service support.

Object lifecycle

Uploads are bounded and hashed in private staging first, then sent to object storage before metadata commits. A failed metadata association removes the uploaded object. Deletion removes the object before committing the metadata transaction; cleanup compares provider keys with database metadata.

Permissions

Grant only object read, write, delete and list permissions for the configured bucket. Do not make the bucket public. Downloads continue through Trestle so collection authorization remains authoritative.

Migration and backup

Changing providers does not migrate existing objects automatically. Copy objects and verify the database manifest before switching. A database backup alone is incomplete: retain a matching bucket snapshot or versioned object copy.