Skip to content

File storage

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

View as MarkdownCoding agents can read this page at /docs/storage.md

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

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.
  • Render: use a bucket instead. See the Render guide.

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

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

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:

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

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

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:

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). No variables are needed. Railway redeploys the service.
  • Render: use a bucket (below), or see 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:

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, 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), 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/.