R2 or local storage

Storage backends

OpenQuok can store workspace media (account media library, composer attachments, and similar) in one of two ways:

Avatars and blog inline images still use Supabase Storage (separate buckets), regardless of this choice.

Pick one STORAGE_PROVIDER value for the API (r2 = object storage, local = disk). That is where the API stores files. Separately, the web app sets VITE_MEDIA_LIBRARY_UPLOAD to choose how the browser uploads (direct multipart to R2, via API to disk, or full file through the API). See Web environment variables.

Cloudflare R2

STORAGE_PROVIDER=r2
STORAGE_R2_ACCOUNT_ID=your_account_id
STORAGE_R2_ACCESS_KEY_ID=your_r2_access_key_id
STORAGE_R2_SECRET_ACCESS_KEY=your_r2_secret_access_key
STORAGE_R2_BUCKET=your_bucket_name
STORAGE_R2_REGION=WNAM

STORAGE_R2_PUBLIC_BASE_URL=https://customdomain.com

VITE_STORAGE_R2_PUBLIC_BASE_URL=https://customdomain.com

VITE_MEDIA_LIBRARY_UPLOAD=direct

[
  {
    "AllowedOrigins": [
      "https://localhost:5173",
      "http://localhost:5173",
      "https://www.openquok.com"
    ],
    "AllowedMethods": [
      "GET",
      "POST",
      "HEAD",
      "PUT",
      "DELETE"
    ],
    "AllowedHeaders": [
      "Authorization",
      "content-type",
      "x-amz-*"
    ],
    "ExposeHeaders": [
      "ETag",
      "Location"
    ],
    "MaxAgeSeconds": 3600
  }
]

Local disk storage

Use this when you do not want to configure R2 (typical local development).

Backend

1. Set an absolute directory on the machine running the API. The process must be able to create and write files there.

STORAGE_PROVIDER=local
UPLOAD_DIRECTORY=/absolute/path/to/openquok-uploads

2. Set FRONTEND_DOMAIN_URL (or BACKEND_DOMAIN_URL) so public URLs for saved media resolve correctly. The API builds public URLs as <origin>/uploads/<storage-key> (same origin as the app in dev is fine, e.g. https://localhost:5173).

3. Restart the API. When STORAGE_PROVIDER is local, the server exposes files under /uploads from UPLOAD_DIRECTORY.

Web app (account media)

For direct-to-R2 multipart uploads, the browser must talk to R2 (bucket CORS). For local storage, uploads should go through the API instead.

Set a web env var so the account media uploader uses the server upload flow (XHR to the API) instead of presigned R2 URLs:

VITE_MEDIA_LIBRARY_UPLOAD=local

When local storage is not enough

Local disk is a single-host solution. For production scale, redundancy, and CDN-friendly URLs, use R2 (or another object store) and keep STORAGE_PROVIDER=r2.

Overview

OpenQuok stores workspace media objects in Cloudflare R2 when STORAGE_PROVIDER is r2 and the R2 variables are set. With STORAGE_PROVIDER = local, objects are stored on disk under UPLOAD_DIRECTORY and served at /uploads/*.

Avatars and blog inline images continue to use Supabase Storage (avatars, blog_images).

Backend environment variables

Set these in backend/.env.development.local (or your host secret store). Restart the API after changes.

R2 (STORAGE_PROVIDER=r2)

STORAGE_PROVIDER=r2
STORAGE_R2_ACCOUNT_ID=your_account_id
STORAGE_R2_ACCESS_KEY_ID=your_r2_access_key_id
STORAGE_R2_SECRET_ACCESS_KEY=your_r2_secret_access_key
STORAGE_R2_BUCKET=your_bucket_name
STORAGE_R2_REGION=WNAM
STORAGE_R2_PUBLIC_BASE_URL=https://media.yourdomain.com

Local disk (STORAGE_PROVIDER=local)

STORAGE_PROVIDER=local
UPLOAD_DIRECTORY=/absolute/path/to/openquok-uploads
FRONTEND_DOMAIN_URL=https://localhost:5173

Web environment variables

Set these in web/.env.development.local (or your production web env). Restart Vite after changes. See also Vite (SvelteKit).

Do not confuse backend STORAGE_PROVIDER r2 (where the API stores objects) with browser upload mode VITE_MEDIA_LIBRARY_UPLOAD=direct (how the client sends bytes).

Example for R2 + direct browser uploads:

VITE_MEDIA_LIBRARY_UPLOAD=direct
VITE_STORAGE_R2_PUBLIC_BASE_URL=https://media.yourdomain.com

Example for local disk (with backend STORAGE_PROVIDER=local):

VITE_MEDIA_LIBRARY_UPLOAD=local

Related