Buckets Overview

A bucket is a named container for uploaded files. It carries its own size limit, its own allowed MIME types, and its own visibility. Tables write into buckets through attachment fields, forms accept uploads into them, and the REST API exposes upload, download, signed-URL, and image-transform endpoints per bucket.

Two concerns are deliberately kept apart:

Where the bytes live — the storage backend — is an operator concern, set with environment variables. It never appears in the app schema. See Storage Backends.
How files are organized — the buckets — is application configuration, declared in the top-level buckets[] array.

app.yaml

buckets:
  - name: avatars
    public: true
    maxFileSize: 2097152
    allowedMimeTypes: [image/jpeg, image/png, image/webp]
    permissions:
      upload: authenticated
      download: all
      delete: [admin]

Bucket Properties

Property	Description
`name`	Unique bucket name, used verbatim as the storage path prefix. Lowercase letters, digits and hyphens; must start with a letter; 63 characters max.
`public`	Boolean. When `true`, files are served without a session and without a signed URL. Defaults to `false`.
`maxFileSize`	Largest accepted upload, in bytes (integer ≥ 1). Overrides the global `STORAGE_MAX_FILE_SIZE` for this bucket.
`allowedMimeTypes`	Accepted MIME types. Wildcards work (`image/*`). At least one entry when present; omitting the property accepts every type. See Upload Security.
`permissions`	Per-operation access rules. See Bucket Permissions.

The 63-character ceiling and the leading-letter rule come from S3 prefix compatibility, and they are enforced offline: Avatars and 123-bucket both fail sovrium validate, as does a duplicate name anywhere in the array.

Public vs Private

Visibility	Behavior
`public: true`	Downloads are served with no session and no token. Right for avatars, logos, marketing assets.
`public: false` (default)	A download needs a session, or a valid signed URL. Anonymous requests get `404`, never `403`.

The 404 is deliberate: a 403 would confirm that a file exists at a guessed key, so private buckets answer as if the path were meaningless.

An operator can also mark path prefixes public across every bucket with STORAGE_PUBLIC_PATHS — see Signed URLs.

The implicit default bucket follows your auth setup. When buckets is omitted, Sovrium still serves /api/buckets/default/.... That implicit bucket is private when app.auth is configured and public when it is not — an app with no session system has nothing to gate on, so anonymous form uploads keep working. Declare the bucket explicitly the moment you want a different answer.

Storage Backends

Moved to Storage Backends — the local, S3 and bytea backends, and how the running binary picks one.

Permissions

Moved to Bucket Permissions — the five per-operation entries, their defaults, and which ones the runtime enforces today.

Example: Multiple Buckets

A public image bucket beside a private, role-gated document bucket:

app.yaml

buckets:
  - name: avatars
    public: true
    maxFileSize: 2097152
    allowedMimeTypes: [image/*]
    permissions:
      upload: authenticated
      download: all
      delete: [admin]

  - name: documents
    maxFileSize: 52428800
    allowedMimeTypes: [application/pdf]
    permissions:
      upload: [admin, editor]
      download: authenticated
      sign: authenticated
      signUpload: [admin, editor]
      delete: [admin]

Nothing is shared between the two but the backend. avatars accepts any image up to 2 MB from any logged-in user and serves it to the world; documents accepts PDFs up to 50 MB from two roles and hands them out only through a session or a signed URL.

Storage Backends — where the bytes actually go.
Bucket Permissions — per-operation access rules.
File Operations — the upload, download and delete endpoints.
Signed URLs — time-limited access to private files.
Resize & Crop — on-the-fly image transforms.
Attachment Fields & Storage — files attached to table records.

Last updated August 11, 2026

← PreviousOAuth Server Next →Storage Backends

Edit this page Report an issue

This documentation was written with AI, so errors or outdated content are possible. Sovrium is in beta. Contributions and corrections are welcome.