Object storage
Source maps and session replays need an S3-compatible object store. Without one, both are off, and everything else works. Choose one of three before the first start.
Garage on the same server
Section titled “Garage on the same server”This is the setup in example.env. Garage runs in the stack, on the same server, and is not open to the internet.
-
Keep these two lines in
.env:Terminal window COMPOSE_PROFILES=object-storeOBJECT_STORE_URL=http://garage:3900 -
Fill in the keys, as Install Ottertrail shows:
OBJECT_STORE_ACCESS_KEY_ID:GKand 24 hex digits.OBJECT_STORE_SECRET_ACCESS_KEY: 64 hex digits.GARAGE_RPC_SECRET: 64 hex digits.GARAGE_ADMIN_TOKEN: 64 hex digits. Optional.
Garage creates its bucket and its access key on its first start, from the same settings that the API reads. Docker Compose reads COMPOSE_PROFILES from .env, so every docker compose command includes Garage.
Garage runs as one node, without copies on other servers. Only your backups keep another copy.
Garage keeps its data on the same disk as the databases. With GARAGE_ADMIN_TOKEN, the Storage tab of the instance settings shows the bucket’s real size and the free space of Garage’s disk, and the worker keeps a quota on the bucket, a little above the budgets below. Without the token, everything else works. See Storage and warnings.
Cloudflare R2, Amazon S3, or another S3-compatible store
Section titled “Cloudflare R2, Amazon S3, or another S3-compatible store”-
Remove the
COMPOSE_PROFILESline from.env. -
Create a bucket and an access key for it at your provider.
-
Set the store’s settings in
.env. For Cloudflare R2:Terminal window OBJECT_STORE_URL=https://<account ID>.r2.cloudflarestorage.comOBJECT_STORE_REGION=autoOBJECT_STORE_BUCKET=ottertrailOBJECT_STORE_ACCESS_KEY_ID=…OBJECT_STORE_SECRET_ACCESS_KEY=…For Amazon S3, use your region’s endpoint and region name.
-
Leave
GARAGE_RPC_SECRETandGARAGE_ADMIN_TOKENempty.
With a store outside the server, the budgets below limit what the store costs, not your server’s disk.
Backups of an R2 or S3 bucket with backup.sh are not tested.
No object store
Section titled “No object store”Remove the COMPOSE_PROFILES and OBJECT_STORE_URL lines from .env. Source maps and session replays are then off. The API writes OBJECT_STORE_URL is not set: source maps are off to its log when it starts.
When a key is missing
Section titled “When a key is missing”| What is missing | What happens | Where to look |
|---|---|---|
OBJECT_STORE_ACCESS_KEY_ID or OBJECT_STORE_SECRET_ACCESS_KEY, with OBJECT_STORE_URL set |
migrate stops, so the API and the worker do not start. docker compose up -d ends with service "migrate" didn't complete successfully: exit 1. |
docker compose logs migrate |
GARAGE_RPC_SECRET, with Garage on |
Garage stops and restarts again and again. The rest starts, but uploads of source maps and replays fail. The message is Invalid RPC secret key. |
docker compose logs garage |
Fill in the setting, then run docker compose up -d again.
How much it stores
Section titled “How much it stores”| Setting | Default | What it limits |
|---|---|---|
SOURCE_MAP_STORAGE_BYTES |
1 GiB | Compressed source maps, all projects together. Maps stay until someone deletes them. |
REPLAY_STORAGE_BYTES |
2 GiB | Compressed session replays, all projects together. Replays are kept 30 days. |
At its budget, new uploads of source maps are refused (409), and new replays are refused. Nothing else breaks. The Storage tab warns at 90% of each budget, and can send the warning to a notification channel. See Storage and warnings.