S3

Store file uploads in an S3 bucket instead of on the server’s local filesystem.

Syntax

$ vela enable s3                    # the development database
$ vela enable s3 -t production      # a deployment

You are prompted for the endpoint, bucket, region and credentials. Every value can also be passed as a flag for non-interactive use, and the secret is read from VELA_S3_SECRET when set — a secret on the command line lands in shell history and in ps.

Once configured, file retrievals are handled automatically; nothing in the app changes.

Targets

Unlike the deploy commands, vela enable s3 defaults to -t local. S3 settings live in the database of whichever copy you configure, and are deliberately not copied from development into a new deployment — naming the target is how they get to production.

Options

  • --backups - Configure where backups are kept, rather than where uploads go
  • --endpoint <url>, --bucket <name>, --region <region>, --access-key <key>, --secret <secret>
  • --force-path-style / --no-force-path-style - How the bucket is addressed
  • --force - Enable it although uploads already exist on disk
  • -t, --target <target> - Which copy of the app to act on, defaults to local

Path style

AWS and Cloudflare R2 address a bucket as a subdomain. MinIO, Ceph, Garage and most self-hosted gateways need it in the path instead, and fail with an unhelpful connection error when they do not get it. The right default is guessed from the endpoint, and the connection test runs immediately so a wrong guess surfaces at once rather than on the first upload.

Existing files are not moved

Turning S3 on changes where PocketBase reads from. It does not migrate anything, so every file already on disk stops resolving.

vela enable s3 refuses when it finds uploads already stored locally. The layout is identical on both sides — <collection>/<record>/<file> — so copying them across is a plain sync:

$ rclone copy /var/lib/vela/apps/<instance>/shared/pb_data/storage/ <remote>:<bucket>/

Then re-run with --force.

Effect on backups

With S3 storage on, PocketBase leaves storage/ out of the archives it writes, so vela backup create captures the databases but not the uploads. Your bucket’s versioning is what protects them from that point.

vela enable s3 --backups is a separate setting that sends the backup archives themselves to a bucket, so they no longer sit on the same disk as the data they protect.