Skip to content
Watasu Docs

Object Storage

Watasu’s object storage gives your app an S3-compatible bucket with scoped credentials. Most S3 SDKs work without any platform-specific code.

Good fits

Section titled “Good fits”
  • user file uploads
  • generated reports and exports
  • static assets you don’t want baked into the app image
  • application-level backups
  • media files

Create

Section titled “Create”
Terminal window
watasu addons:create object-storage --app my-app

Connect from your app

Section titled “Connect from your app”

Object storage exports a generous set of S3-compatible env vars so you don’t have to know which one your SDK reads from:

VariablePurpose
S3_BUCKET, AWS_S3_BUCKETBucket name
AWS_ACCESS_KEY_IDCredential ID
AWS_SECRET_ACCESS_KEYCredential secret
AWS_ENDPOINT_URL, AWS_ENDPOINT_URL_S3S3 endpoint (this isn’t AWS)
AWS_REGION, AWS_DEFAULT_REGION, AWS_S3_REGIONRegion label expected by SDKs
AWS_S3_URLConvenience URL

Most AWS SDKs (boto3, aws-sdk for Ruby/JS/Java/Go, rclone, etc.) pick these up automatically once they’re set.

The full list and what each SDK reads is in Reference → Add-on Environment Variables.

Public vs. private files

Section titled “Public vs. private files”

Object storage gives you the bucket and credentials. Your application owns the access model:

  • public objects — typically uploaded with a public ACL or served via signed URLs
  • private objects — generate short-lived signed URLs at request time

There’s no platform setting that flips the bucket between “public” and “private” — that’s a per-object decision your code makes.

Durability

Section titled “Durability”

Plans differ on durability and scale characteristics. Pick deliberately based on what you’d accept losing.

Backups vs. durability — they aren’t the same

Section titled “Backups vs. durability — they aren’t the same”

Object storage is durable. That means a stored object isn’t going to disappear because of disk failure. It does not mean object storage will recover from your app deleting the wrong file.

If you need an undelete or point-in-time recovery for application-level mistakes, design that explicitly — versioned objects, soft-deletes in your app, or periodic snapshots to a second bucket.

The platform-managed backup workflow (Backups and Restores) covers PostgreSQL, Valkey, and ClickHouse. Object storage isn’t part of that flow.

Monitoring

Section titled “Monitoring”

Object storage usage shows up in Grafana once you’ve attached the metrics add-on:

  • bucket size over time
  • request volume
  • bandwidth and egress

Useful for spotting runaway upload bugs and for budgeting. See Observability → Metrics.