Skip to main content
View as Markdown

Buckets Overview

Buckets are named containers for uploaded files. Each bucket carries its own size limit, allowed MIME types, public/private visibility, and access permissions. Tables reference buckets through attachment fields, forms write files into them, and the REST API exposes upload, download, signed-URL, and image-transform endpoints.

Two concerns are deliberately separated:

  • Where files are stored — the storage backend — is operator-controlled via environment variables (STORAGE_PROVIDER and friends). It never appears in the app schema.
  • How files are organized — the buckets — is application configuration declared in the top-level buckets[] array of your config.
buckets:
  - name: avatars
    public: true
    maxFileSize: 2097152
    allowedMimeTypes: [image/jpeg, image/png, image/webp]
    permissions:
      upload: authenticated
      download: all
      delete: [admin]

When buckets is omitted entirely, Sovrium provisions an implicit default bucket (public: false, standard permission defaults).

Storage Backends

The backend is chosen at deploy time with STORAGE_PROVIDER. All three backends support the full file-operations, signed-URL, and image-transform surface.

Backend STORAGE_PROVIDER Best for Scalability Native presigned URLs
Local filesystem local (default) Development, single-node, self-hosted Disk-bound No (Sovrium signs internally)
S3 / S3-compatible s3 Production, scale-out Unlimited Yes (delegated to the provider)
MinIO s3 + STORAGE_FORCE_PATH_STYLE=true Self-hosted S3-compatible object store Unlimited Yes
PostgreSQL bytea bytea Small files, simple single-database deploys Database-bound No (Sovrium signs internally)

Backend Environment Variables

Variable Required Default Purpose
STORAGE_PROVIDER No local Storage backend: s3, local, or bytea.
STORAGE_ENDPOINT S3 only — S3-compatible endpoint URL.
STORAGE_BUCKET S3 only — Underlying S3 bucket name (the host object store, not a Sovrium bucket).
STORAGE_REGION S3 only us-east-1 AWS region.
STORAGE_ACCESS_KEY S3 only — S3 access key ID.
STORAGE_SECRET_KEY S3 only — S3 secret access key.
STORAGE_FORCE_PATH_STYLE No false Use path-style URLs (required for MinIO).

See Environment Variables for the full operator-facing variable reference.

Bucket Properties

Each entry in the buckets[] array accepts the following properties.

Property Description
name Unique bucket name. Lowercase, alphanumeric, hyphens; must start with a letter; max 63 characters (S3 prefix compatibility). Used as the storage path prefix.
public Boolean. When true, files are served without signed URLs. Defaults to false (private).
maxFileSize Maximum file size in bytes for uploads to this bucket. Overrides the global STORAGE_MAX_FILE_SIZE. Must be ≥ 1.
allowedMimeTypes Array of allowed MIME types for uploads. Supports wildcards (e.g. image/*). When omitted, all types are accepted. Minimum one entry.
permissions Per-operation access control. See Permissions below.

Permissions

Bucket permissions use the same shared PermissionValueSchema format as table permissions: each operation accepts all, authenticated, or a list of role names.

Operation Description Default
upload Who can upload files to this bucket. authenticated
download Who can download files from this bucket. all if public, authenticated if private
sign Who can generate signed download URLs. authenticated
signUpload Who can generate signed upload URLs. [admin]
delete Who can delete files from this bucket. [admin]

Permission values:

  • all — everyone, including unauthenticated requests.
  • authenticated — any logged-in user.
  • ['admin', 'editor'] — only the listed roles.
buckets:
  - name: documents
    maxFileSize: 52428800
    allowedMimeTypes: [application/pdf, text/csv]
    permissions:
      upload: [admin, editor]
      download: authenticated
      sign: authenticated
      signUpload: [admin, editor]
      delete: [admin]

When a bucket omits permissions entirely, the per-operation defaults above apply — notably, only the admin role can generate signed URLs.

Public vs Private

Visibility Behavior
public: true Files served directly without authentication or signed URLs. Suitable for avatars, logos, marketing assets.
public: false (default) Files require either authentication (matching download permission) or a valid signed URL.

Operators can additionally expose path prefixes globally via STORAGE_PUBLIC_PATHS (see Signed URLs).

Example: Multiple Buckets

A public images bucket alongside a private, role-gated documents bucket.

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]