# Object Storage

> S3-compatible object storage for uploads, assets, exports, and archives.

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

* user file uploads
* generated reports and exports
* static assets you don't want baked into the app image
* application-level backups
* media files

## Create

```bash
watasu addons:create object-storage --app my-app
```

## 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:

| Variable                                                         | Purpose                                           |
| ---------------------------------------------------------------- | ------------------------------------------------- |
| `S3_BUCKET`, `AWS_S3_BUCKET`                                     | Bucket name                                       |
| `S3_ACCESS_KEY_ID`, `AWS_ACCESS_KEY_ID`                          | Credential ID                                     |
| `S3_SECRET_ACCESS_KEY`, `AWS_SECRET_ACCESS_KEY`                  | Credential secret                                 |
| `S3_ENDPOINT`, `AWS_ENDPOINT_URL`, `AWS_ENDPOINT_URL_S3`         | S3 endpoint (this isn't AWS)                      |
| `S3_REGION`, `AWS_REGION`, `AWS_DEFAULT_REGION`, `AWS_S3_REGION` | Region label expected by SDKs                     |
| `S3_FORCE_PATH_STYLE`                                            | Set when the SDK should use path-style addressing |
| `S3_PUBLIC_BUCKET_URL`, `AWS_S3_URL`                             | Convenience URLs                                  |

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](https://docs.watasu.io/reference/addon-env-vars.md).

## 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

Plans differ on durability and scale characteristics:

* **Hobby and Standard** — single-zone storage with a monthly public egress allowance.
* **Premium** — geo-replicated across three zones, for data that must survive a full data-center outage.

Each plan includes a monthly egress allowance that scales with the tier. See [Add-on Plans](https://docs.watasu.io/reference/addon-plans.md) for storage sizes and allowances. Pick deliberately based on what you'd accept losing.

## 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](https://docs.watasu.io/workflows/backups-and-restores.md)) covers PostgreSQL, Valkey, and ClickHouse. Object storage isn't part of that flow.

## 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](https://docs.watasu.io/observability/metrics.md).

[View this page on the web](https://docs.watasu.io/addons/object-storage/)