# File storage

> Keep uploaded logos and profile photos on a persistent volume or in an S3-compatible bucket.

Changing the storage setup is optional. Without any storage variables, the app saves uploads to local disk, which works as long as that disk is a persistent volume.

The apps store a few uploaded files:

- profile photos (both apps)
- the organization logo shown in the app and on public pages (both apps)
- the business logo printed on invoices and PDFs (Invoicing)

They're small images, up to 1 MB each: PNG, JPEG or WebP, except the invoice logo, which must be PNG or JPEG so it can be embedded in PDFs. Invoice PDFs are generated on demand and not stored. Everything else lives in Postgres.

You have two choices: local disk (the default) or an S3-compatible bucket.

## Local disk

```sh
STORAGE_DRIVER=local
STORAGE_LOCAL_DIR=/app/data/uploads   # the default inside the Docker image
```

Files are written under `STORAGE_LOCAL_DIR`, and the app serves them through short-lived signed links. This folder must be on a **persistent volume**, a disk that survives restarts and redeploys. Without one, uploads vanish every time the app is redeployed.

- **Docker Compose:** already set up. The `appdata` volume is mounted at `/app/data`.
- **Railway:** add a volume mounted at `/app/data`. No variables needed. See the [Railway guide](./railway.md#6-keep-uploads).
- **Render:** use a bucket instead. See the [Render guide](./render.md#uploads-on-render).

Local disk ties the app to one machine. If you run more than one copy of the app, use a bucket.

## S3-compatible bucket

S3 is Amazon's file storage API, and many providers offer the same API. Create a private bucket, create an access key that can read, write and delete objects in it, then set:

| Variable | Description |
|----------|-------------|
| `STORAGE_DRIVER` | `s3` |
| `S3_ENDPOINT` | The provider's S3 API address. Leave unset for AWS S3. |
| `S3_REGION` | The bucket's region. Default `auto`. |
| `S3_BUCKET` | The bucket name. |
| `S3_ACCESS_KEY_ID` | Access key ID. |
| `S3_SECRET_ACCESS_KEY` | Secret access key. |
| `S3_FORCE_PATH_STYLE` | `true` when `S3_ENDPOINT` is set (see below). |

The bucket can stay private. The app hands browsers presigned links (temporary URLs signed with your key, valid for an hour) and fetches files itself when it needs them. You don't need public access or CORS rules.

**Set `S3_FORCE_PATH_STYLE=true` when you set `S3_ENDPOINT`.** Path style means the bucket name goes in the URL path (`https://endpoint/bucket/file`) rather than in the host name, and every provider below accepts it. If your provider only accepts virtual-hosted style, leave it `false`: the app then puts the bucket in the host name (`https://bucket.endpoint/file`).

### AWS S3

```sh
STORAGE_DRIVER=s3
S3_REGION=us-east-1               # your bucket's region
S3_BUCKET=my-app-uploads
S3_ACCESS_KEY_ID=AKIA...
S3_SECRET_ACCESS_KEY=...
```

Leave `S3_ENDPOINT` unset and `S3_FORCE_PATH_STYLE` off. You must set `S3_REGION`, because the default `auto` isn't a valid AWS region. Keep "Block all public access" on. Give the access key's IAM user a policy that allows `s3:GetObject`, `s3:PutObject` and `s3:DeleteObject` on `arn:aws:s3:::my-app-uploads/*`.

### Cloudflare R2

```sh
STORAGE_DRIVER=s3
S3_ENDPOINT=https://<ACCOUNT_ID>.r2.cloudflarestorage.com
S3_REGION=auto
S3_BUCKET=my-app-uploads
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
S3_FORCE_PATH_STYLE=true
```

Find your account ID in the Cloudflare dashboard. In the R2 section, create an API token with object read and write permission for the bucket, and copy the access key ID and secret access key it shows. R2 has a free monthly allowance and no egress fees.

### Railway Buckets

Railway Buckets are private S3-compatible buckets inside your Railway project. Create one from the project canvas (**Create > Bucket**), then reference its variables from the app service. Replace `Bucket` with the bucket's name on the canvas:

```sh
STORAGE_DRIVER=s3
S3_ENDPOINT=${{Bucket.ENDPOINT}}
S3_REGION=${{Bucket.REGION}}
S3_BUCKET=${{Bucket.BUCKET}}
S3_ACCESS_KEY_ID=${{Bucket.ACCESS_KEY_ID}}
S3_SECRET_ACCESS_KEY=${{Bucket.SECRET_ACCESS_KEY}}
S3_FORCE_PATH_STYLE=true
```

Use the `BUCKET` variable, not `RAILWAY_BUCKET_NAME` (that one is a display name). The bucket's **Credentials** tab shows which URL style it expects. If uploads fail with path style, switch to virtual-hosted style by putting the bucket name in the endpoint host instead: `S3_ENDPOINT=https://${{Bucket.BUCKET}}.t3.storageapi.dev` (use the host from your `ENDPOINT` value) and `S3_FORCE_PATH_STYLE=false`.

### Supabase Storage

```sh
STORAGE_DRIVER=s3
S3_ENDPOINT=https://<PROJECT_REF>.storage.supabase.co/storage/v1/s3
S3_REGION=<your project region>
S3_BUCKET=my-app-uploads
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
S3_FORCE_PATH_STYLE=true
```

Create a private bucket in Supabase Storage. The S3 endpoint, region and access keys are in the project's Storage settings, under the S3 connection section.

### MinIO, SeaweedFS and other self-hosted servers

```sh
STORAGE_DRIVER=s3
S3_ENDPOINT=http://minio:9000      # or https://s3.example.com
S3_REGION=us-east-1
S3_BUCKET=my-app-uploads
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
S3_FORCE_PATH_STYLE=true
```

Browsers download files straight from the endpoint through presigned links, so `S3_ENDPOINT` must be an address that your users' browsers can reach, not only the app.

## Moving from local disk to a bucket

There's no migration command, but files keep the same names in both drivers (for example `logos/<id>.png` and `avatars/<id>.webp`). Copy the contents of the uploads folder to the root of the bucket with any S3 tool, then switch the variables and restart. For example, with the AWS CLI:

```sh
aws s3 sync ./uploads s3://my-app-uploads/ --endpoint-url https://<ACCOUNT_ID>.r2.cloudflarestorage.com
```

## Troubleshooting

- **`S3_BUCKET is required when STORAGE_DRIVER=s3`** (or the same for the key variables) at startup: a required S3 variable is missing.
- **Uploads fail, or images don't load:** check the endpoint, bucket name and keys, and try the other `S3_FORCE_PATH_STYLE` setting if your provider expects a different URL style. The app logs show the provider's error.
- **`Image must be under 1 MB`**, **`Image must be PNG, JPG or WEBP`**, **`Logo must be under 1 MB`** or **`Logo must be a PNG or JPEG`:** the upload limits. Resize or convert the image.
- **Images disappear after a redeploy:** you're on local disk without a persistent volume.

## Adding this to an existing deploy

**To keep using local disk**, make sure the uploads folder is on a persistent volume:

- **Railway:** add a volume mounted at `/app/data` to the app service ([Railway guide](./railway.md#6-keep-uploads)). No variables are needed. Railway redeploys the service.
- **Render:** use a bucket (below), or see [Uploads on Render](./render.md#uploads-on-render).
- **Docker Compose:** nothing to do; the `appdata` volume is already mounted.

**To switch to a bucket**, set these variables on the running app, with the values for your provider from the presets above:

```sh
STORAGE_DRIVER=s3
S3_ENDPOINT=...
S3_REGION=...
S3_BUCKET=...
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
S3_FORCE_PATH_STYLE=true
```

- **Railway:** open the app service's **Variables** tab, add the variables, and deploy the staged changes. Railway redeploys the service.
- **Render:** open the web service's environment settings, add the variables, and save. Render redeploys the service.
- **Docker Compose:** `compose.yaml` sets `STORAGE_DRIVER=local`, and that wins over `.env`. Put `STORAGE_DRIVER` and the non-secret `S3_*` values in `compose.override.yaml` and the two keys in `.env`, as shown in the [Docker guide](./docker.md#use-s3-storage), then run `docker compose up -d` in the app's folder.

The new settings take effect only after this restart or redeploy.

Files uploaded before the switch stay where they were. Copy them over first (see [Moving from local disk to a bucket](#moving-from-local-disk-to-a-bucket)), or upload the logos and photos again.

To confirm it works:

1. The app starts without `Invalid configuration` errors.
2. Upload a profile photo (or, in Invoicing, the business logo) and check that it displays.
3. Check the bucket: the file appears under `avatars/` or `logos/`.