RustFS
S3-compatible object store — S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY, /data volume, console on :9001.
RustFS is the default oke dev / prod store.files image — an Apache-2.0 S3-compatible
object store. Driver id stays s3; Bun binds Bun.S3Client against the endpoint.
The one rule
Protocol name is s3 — vendor choice is the image pin (rustfs/rustfs:…) plus S3_ENDPOINT.
Never invent a rustfs driver id.
Quick start
Pin driver + image (templates already do)
drivers: {
store: {
files: { dev: "s3", test: "memory", prod: "s3" },
},
},
images: {
store: { files: "rustfs/rustfs:1.0.0-rc.5" },
},Credentials and endpoint
S3_ACCESS_KEY_ID=…
S3_SECRET_ACCESS_KEY=…
S3_BUCKET=oke
S3_ENDPOINT=http://127.0.0.1:9000
S3_URL=http://…@127.0.0.1:9000/oke
S3_REGION=us-east-1
S3_CONSOLE_URL=http://127.0.0.1:9001Recipe maps:
RUSTFS_ACCESS_KEY=${S3_ACCESS_KEY_ID}RUSTFS_SECRET_KEY=${S3_SECRET_ACCESS_KEY}RUSTFS_CONSOLE_ENABLE=trueRUSTFS_ADDRESS=:9000- command:
/data
Put an object
Any flow using fx.store files (put / get) against the s3 driver talks to this
endpoint. Open S3_CONSOLE_URL for a browser console on port 9001.
Required env
| Variable | Required? | Meaning |
|---|---|---|
S3_ACCESS_KEY_ID | Yes | Access key → RUSTFS_ACCESS_KEY |
S3_SECRET_ACCESS_KEY | Yes | Secret key → RUSTFS_SECRET_KEY |
S3_BUCKET | Yes (app) | Bucket name the driver opens |
S3_ENDPOINT | Yes (non-AWS) | Origin http://host:9000 |
S3_REGION | Optional | Default us-east-1 in stack env |
S3_SESSION_TOKEN | Optional | Temporary creds |
S3_CONSOLE_URL | Written by stack | UI on :9001 — not required by the driver |
S3_URL | Written by stack | Credentialed URL form |
Data and backup
| Volume | Path | What it stores |
|---|---|---|
store-files-data | /data | Object bytes + RustFS metadata |
Backup means: snapshot that named volume (or aws s3 sync against the API).
Deleting the volume deletes every object.
Credentials live in .env.local, not in /data — rotate keys without wiping objects.
Losing both volume and keys means full restore from backup only.
Production note
For cloud prod, point the same s3 driver at real S3 / R2 / GCS interop by changing
S3_ENDPOINT + keys — keep the driver id. Self-hosted RustFS on a single node is a
durability SPOF: put the /data volume on reliable disks and back it up.
Do not publish :9000 / :9001 on the public internet without TLS and network policy —
the recipe enables the console for local ops.
What the recipe configures
| Field | Value |
|---|---|
| API port | 9000 |
| Extra port | 9001 → console |
| Healthcheck | curl -f http://127.0.0.1:9000/health, every 5s, 12 retries, 10s start |
| Connection URL | http://user:pass@host:9000/bucket |
Troubleshooting
Files on the s3 driver need S3_BUCKET (or OKE_STORE_FILES_DB). Without it the
facet cannot open. Re-run oke dev so stack env fills S3_*, or export them
for a managed bucket.
S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY do not match RUSTFS_* inside the
container, or S3_ENDPOINT points at the wrong host/port. Align .env.local with the
running service; confirm health at /health before debugging client signatures.
Learn more
- Store · Files — facet API and drivers
- Environment variables — full
S3_*map - Recipes — docker env cheat sheet