OpportunitiesEntities
Docs
    Ring Platform

    Decentralized Self-building Future

    Sign In
    Entities
    Opportunities
    Store
    Docs
    Platform Concepts
    RING EconomySonoratek LLCGlobal ImpactAI Meets Web3
    Get Started
    Quick StartCalculatorRoadmap
    Privacy|Contact
    v1.104.17|Sonoratek LLC

    Documentation

    Concepts, value, and typical clone scenarios — less code.

    Welcome to Ring
    Quick Reference
    Getting Started
    Prerequisites
    Installation
    First Success Validation
    Next Steps
    Features
    Multi-Vendor Store
    Inventory & Stock
    Vendor Management
    Commissions & Settlements
    SubscriptionConductor
    PaymentConductor
    Ring Oracle
    Payments Overview
    Public Pools & DAO Jars
    WayForPay Payment Integration
    Wallet & Credit System
    WalletConductor
    Affiliate & Referral Enablement
    Referral Codes (Refcodes)
    NFT Exhibition Marketplace
    Solana NFT Gates
    Token Staking System
    Owner Project Lab
    Entities
    Opportunities
    Real-Time Messaging
    Ring Tasks
    WebRTC Calls & STUNner TURN
    Peer Games
    News Module
    Member Blogs
    Public Profile Pages
    Profile Account Widgets
    Ring File Cabinet
    Username Reservation System
    Scientific Editor
    Notifications
    Push Notifications with FCM (Ring-Powered)
    Email AI-CRM
    Ring Mailer & RingdomX Mail
    Tunnel Protocol
    VideoConductor
    MediaConductor
    Generative Gallery
    Authentication
    Security & Compliance
    Admin console
    Admin Wiki
    Manage via Telegram
    Locale System
    Mobile Experience
    Performance Optimization Patterns
    Examples
    Quick Start
    Basic Setup
    White Label
    Custom Branding
    Web3 Integration
    Real World
    Advanced Features
    Customization
    Quick Start — Your First Ring Clone
    Customization Guide
    Vertical Presets (SSOT)
    Ringization playbook
    Branding
    Themes
    Features
    Localization
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    Project configuration
    Public environment variables
    Order Lab secrets
    WalletConnect Project ID (Reown Cloud)
    Supported services
    NODUS wiki (project knowledge)
    Configuration playbook
    Web3
    Token launch jurisdictions
    Wallet
    Wallet Security Tips
    Integrations
    Ethereum wallets (Wagmi v3)
    RingFileBase (object storage API)
    Ring CDN (RingFileBase edge)
    Deployment
    Self-hosted deployment
    Vercel Deployment
    Docker
    Environment Configuration
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Architecture
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    PaymentConductor architecture
    WalletConductor architecture
    Backend Services
    Firebase Integration
    Development
    Ring MCP Server

    Quick entry (CTOs · auditors · agents)

    Welcome — mission & audiences
    Quick Reference
    Getting started
    Architecture & Auth.js
    Backend modes & databases (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Deploy (Docker · k8s)
    Security & compliance reads
    ringdom.org — LegioX homebase
    Source — MIT license (GitHub)

    Documentation

    Concepts, value, and typical clone scenarios — less code.

    Welcome to Ring
    Quick Reference
    Getting Started
    Prerequisites
    Installation
    First Success Validation
    Next Steps
    Features
    Multi-Vendor Store
    Inventory & Stock
    Vendor Management
    Commissions & Settlements
    SubscriptionConductor
    PaymentConductor
    Ring Oracle
    Payments Overview
    Public Pools & DAO Jars
    WayForPay Payment Integration
    Wallet & Credit System
    WalletConductor
    Affiliate & Referral Enablement
    Referral Codes (Refcodes)
    NFT Exhibition Marketplace
    Solana NFT Gates
    Token Staking System
    Owner Project Lab
    Entities
    Opportunities
    Real-Time Messaging
    Ring Tasks
    WebRTC Calls & STUNner TURN
    Peer Games
    News Module
    Member Blogs
    Public Profile Pages
    Profile Account Widgets
    Ring File Cabinet
    Username Reservation System
    Scientific Editor
    Notifications
    Push Notifications with FCM (Ring-Powered)
    Email AI-CRM
    Ring Mailer & RingdomX Mail
    Tunnel Protocol
    VideoConductor
    MediaConductor
    Generative Gallery
    Authentication
    Security & Compliance
    Admin console
    Admin Wiki
    Manage via Telegram
    Locale System
    Mobile Experience
    Performance Optimization Patterns
    Examples
    Quick Start
    Basic Setup
    White Label
    Custom Branding
    Web3 Integration
    Real World
    Advanced Features
    Customization
    Quick Start — Your First Ring Clone
    Customization Guide
    Vertical Presets (SSOT)
    Ringization playbook
    Branding
    Themes
    Features
    Localization
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    Project configuration
    Public environment variables
    Order Lab secrets
    WalletConnect Project ID (Reown Cloud)
    Supported services
    NODUS wiki (project knowledge)
    Configuration playbook
    Web3
    Token launch jurisdictions
    Wallet
    Wallet Security Tips
    Integrations
    Ethereum wallets (Wagmi v3)
    RingFileBase (object storage API)
    Ring CDN (RingFileBase edge)
    Deployment
    Self-hosted deployment
    Vercel Deployment
    Docker
    Environment Configuration
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Architecture
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    PaymentConductor architecture
    WalletConductor architecture
    Backend Services
    Firebase Integration
    Development
    Ring MCP Server

    Quick entry (CTOs · auditors · agents)

    Welcome — mission & audiences
    Quick Reference
    Getting started
    Architecture & Auth.js
    Backend modes & databases (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Deploy (Docker · k8s)
    Security & compliance reads
    ringdom.org — LegioX homebase
    Source — MIT license (GitHub)

    Documentation

    Concepts, value, and typical clone scenarios — less code.

    Welcome to Ring
    Quick Reference
    Getting Started
    Prerequisites
    Installation
    First Success Validation
    Next Steps
    Features
    Multi-Vendor Store
    Inventory & Stock
    Vendor Management
    Commissions & Settlements
    SubscriptionConductor
    PaymentConductor
    Ring Oracle
    Payments Overview
    Public Pools & DAO Jars
    WayForPay Payment Integration
    Wallet & Credit System
    WalletConductor
    Affiliate & Referral Enablement
    Referral Codes (Refcodes)
    NFT Exhibition Marketplace
    Solana NFT Gates
    Token Staking System
    Owner Project Lab
    Entities
    Opportunities
    Real-Time Messaging
    Ring Tasks
    WebRTC Calls & STUNner TURN
    Peer Games
    News Module
    Member Blogs
    Public Profile Pages
    Profile Account Widgets
    Ring File Cabinet
    Username Reservation System
    Scientific Editor
    Notifications
    Push Notifications with FCM (Ring-Powered)
    Email AI-CRM
    Ring Mailer & RingdomX Mail
    Tunnel Protocol
    VideoConductor
    MediaConductor
    Generative Gallery
    Authentication
    Security & Compliance
    Admin console
    Admin Wiki
    Manage via Telegram
    Locale System
    Mobile Experience
    Performance Optimization Patterns
    Examples
    Quick Start
    Basic Setup
    White Label
    Custom Branding
    Web3 Integration
    Real World
    Advanced Features
    Customization
    Quick Start — Your First Ring Clone
    Customization Guide
    Vertical Presets (SSOT)
    Ringization playbook
    Branding
    Themes
    Features
    Localization
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    Project configuration
    Public environment variables
    Order Lab secrets
    WalletConnect Project ID (Reown Cloud)
    Supported services
    NODUS wiki (project knowledge)
    Configuration playbook
    Web3
    Token launch jurisdictions
    Wallet
    Wallet Security Tips
    Integrations
    Ethereum wallets (Wagmi v3)
    RingFileBase (object storage API)
    Ring CDN (RingFileBase edge)
    Deployment
    Self-hosted deployment
    Vercel Deployment
    Docker
    Environment Configuration
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Architecture
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    PaymentConductor architecture
    WalletConductor architecture
    Backend Services
    Firebase Integration
    Development
    Ring MCP Server

    Quick entry (CTOs · auditors · agents)

    Welcome — mission & audiences
    Quick Reference
    Getting started
    Architecture & Auth.js
    Backend modes & databases (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Deploy (Docker · k8s)
    Security & compliance reads
    ringdom.org — LegioX homebase
    Source — MIT license (GitHub)
    Ring Logo

    Loading documentation...

    Preparing Ring content

    Ring Logo

    Loading documentation...

    Preparing Ring content

    Ring Logo

    Loading documentation...

    Preparing Ring content

    RingFileBase (object storage API)

    Use Founder / Developer tabs in the docs sidebar to filter this page. Pair with Ring CDN for public delivery of uploaded objects. Ring File Cabinet is a first-class file() consumer (getCabinetStorageConfig(), gallery derivativesProfile).

    RingFileBase is Ring’s self-hosted object-storage plane: an Express API (ring-filebase-api) that accepts authenticated multipart uploads and writes to S3-compatible storage (MinIO or Ceph RGW). Ring apps never talk to MinIO from the browser — they call file().upload(...), which selects RingBaseAdapter when the storage provider is ring_filebase.

    ConcernRingFileBase (this page)Ring CDN
    RoleAuthenticated write APIPublic read edge
    Prod URLIn-cluster http://ring-filebase-api.ring-filebase.svc.cluster.localhttps://cdn.<your-domain>
    Dev / CI URLPublic https://filebase-api.ring-platform.org (k3s-or primary only)Same CDN (multi-A edges; master push to slave ingest)
    ClientServer-side file() / Server ActionsBrowsers, <img>, OG tags
    AuthBearer token (RINGBASE_API_TOKEN)None (GET /files/...)

    Authority: writes always go to k3s-or (Oregon). The API then pushes objects to slave MinIO ingest endpoints (Finland / Ukraine). Slaves never pull from master; pull CronJobs are disabled.

    Provider SSOT (shared)

    Resolution order in lib/storage/storage-config.ts (mirrors db()):

    1. NEXT_PUBLIC_STORAGE_PROVIDER or STORAGE_PROVIDER
    2. ring-config.json → storage.provider
    3. Default: local_storage (development) / vercel_blob (production)
    Provider valueAdapterWhen to use
    local_storageLocalStorageAdapterLocal npm run dev, PVC-backed uploads
    vercel_blobVercelAdapterVercel-hosted clones with BLOB_READ_WRITE_TOKEN
    ring_filebaseRingBaseAdapterSelf-hosted / Ringdom k8s with RingFileBase API
    firebase_storageFalls back to local in selectorNot a first-class upload path today

    Why this matters for your clone

    Product images, KYC scans, chat attachments, and ImageConductor outputs all need a durable home. Vercel Blob is fine for small OSS demos; a marketplace clone that owns its data usually wants RingFileBase so media stays on your cluster, behind your CDN hostname, without per-GB Blob invoices.

    Typical scenarios

    Local development

    Keep storage.provider / env on local_storage — files land under public/uploads (or your PVC mount).

    Production marketplace

    Set ring_filebase, point RINGBASE_API_URL at the in-cluster API, publish URLs via Ring CDN (see Related below).

    File Cabinet

    Member uploads call with cabinet MIME/25MB limits; public gallery items reuse CDN .

    Architecture

    Verified modules

    PathRole
    lib/storage/storage-config.tsProvider SSOT + getStorageConfig()
    lib/file/FileService.tsfile() / fileService.upload
    lib/file/FileSelector.tsBackend map; constructs RingBaseAdapter from env
    lib/file/adapters/RingBaseAdapter.tsMultipart upload, delete, metadata, deriveDerivatives
    lib/images/derive-webp.tsOptional WebP sibling; storage.webpDerivative.provider=ringbase

    Related documentation

    Related documentation

    Ring CDN (RingFileBase edge)

    Next-step: public /files/... edge, host→bucket map, and geo delivery for uploaded objects.

    Ring File Cabinet

    Same-workflow: member /file-cabinet uploads via file() + getCabinetStorageConfig; gallery uses derivativesProfile gallery; subscriber+ /profile/shared is ACL-only (no own uploads).

    Environment Configuration

    Depends-on: storage env block (RINGBASE_*) and generative conductor prerequisites.

    Backup & Recovery

    See-also: object store is a separate backup asset from Postgres.

    RingFileBase (object storage API)

    Use Founder / Developer tabs in the docs sidebar to filter this page. Pair with Ring CDN for public delivery of uploaded objects. Ring File Cabinet is a first-class file() consumer (getCabinetStorageConfig(), gallery derivativesProfile).

    RingFileBase is Ring’s self-hosted object-storage plane: an Express API (ring-filebase-api) that accepts authenticated multipart uploads and writes to S3-compatible storage (MinIO or Ceph RGW). Ring apps never talk to MinIO from the browser — they call file().upload(...), which selects RingBaseAdapter when the storage provider is ring_filebase.

    ConcernRingFileBase (this page)Ring CDN
    RoleAuthenticated write APIPublic read edge
    Prod URLIn-cluster http://ring-filebase-api.ring-filebase.svc.cluster.localhttps://cdn.<your-domain>
    Dev / CI URLPublic https://filebase-api.ring-platform.org (k3s-or primary only)Same CDN (multi-A edges; master push to slave ingest)
    ClientServer-side file() / Server ActionsBrowsers, <img>, OG tags
    AuthBearer token (RINGBASE_API_TOKEN)None (GET /files/...)

    Authority: writes always go to k3s-or (Oregon). The API then pushes objects to slave MinIO ingest endpoints (Finland / Ukraine). Slaves never pull from master; pull CronJobs are disabled.

    Provider SSOT (shared)

    Resolution order in lib/storage/storage-config.ts (mirrors db()):

    1. NEXT_PUBLIC_STORAGE_PROVIDER or STORAGE_PROVIDER
    2. ring-config.json → storage.provider
    3. Default: local_storage (development) / vercel_blob (production)
    Provider valueAdapterWhen to use
    local_storageLocalStorageAdapterLocal npm run dev, PVC-backed uploads
    vercel_blobVercelAdapterVercel-hosted clones with BLOB_READ_WRITE_TOKEN
    ring_filebaseRingBaseAdapterSelf-hosted / Ringdom k8s with RingFileBase API
    firebase_storageFalls back to local in selectorNot a first-class upload path today

    Why this matters for your clone

    Product images, KYC scans, chat attachments, and ImageConductor outputs all need a durable home. Vercel Blob is fine for small OSS demos; a marketplace clone that owns its data usually wants RingFileBase so media stays on your cluster, behind your CDN hostname, without per-GB Blob invoices.

    Typical scenarios

    Local development

    Keep storage.provider / env on local_storage — files land under public/uploads (or your PVC mount).

    Production marketplace

    Set ring_filebase, point RINGBASE_API_URL at the in-cluster API, publish URLs via Ring CDN (see Related below).

    File Cabinet

    Member uploads call with cabinet MIME/25MB limits; public gallery items reuse CDN .

    Architecture

    Verified modules

    PathRole
    lib/storage/storage-config.tsProvider SSOT + getStorageConfig()
    lib/file/FileService.tsfile() / fileService.upload
    lib/file/FileSelector.tsBackend map; constructs RingBaseAdapter from env
    lib/file/adapters/RingBaseAdapter.tsMultipart upload, delete, metadata, deriveDerivatives
    lib/images/derive-webp.tsOptional WebP sibling; storage.webpDerivative.provider=ringbase

    Related documentation

    Related documentation

    Ring CDN (RingFileBase edge)

    Next-step: public /files/... edge, host→bucket map, and geo delivery for uploaded objects.

    Ring File Cabinet

    Same-workflow: member /file-cabinet uploads via file() + getCabinetStorageConfig; gallery uses derivativesProfile gallery; subscriber+ /profile/shared is ACL-only (no own uploads).

    Environment Configuration

    Depends-on: storage env block (RINGBASE_*) and generative conductor prerequisites.

    Backup & Recovery

    See-also: object store is a separate backup asset from Postgres.

    RingFileBase (object storage API)

    Use Founder / Developer tabs in the docs sidebar to filter this page. Pair with Ring CDN for public delivery of uploaded objects. Ring File Cabinet is a first-class file() consumer (getCabinetStorageConfig(), gallery derivativesProfile).

    RingFileBase is Ring’s self-hosted object-storage plane: an Express API (ring-filebase-api) that accepts authenticated multipart uploads and writes to S3-compatible storage (MinIO or Ceph RGW). Ring apps never talk to MinIO from the browser — they call file().upload(...), which selects RingBaseAdapter when the storage provider is ring_filebase.

    ConcernRingFileBase (this page)Ring CDN
    RoleAuthenticated write APIPublic read edge
    Prod URLIn-cluster http://ring-filebase-api.ring-filebase.svc.cluster.localhttps://cdn.<your-domain>
    Dev / CI URLPublic https://filebase-api.ring-platform.org (k3s-or primary only)Same CDN (multi-A edges; master push to slave ingest)
    ClientServer-side file() / Server ActionsBrowsers, <img>, OG tags
    AuthBearer token (RINGBASE_API_TOKEN)None (GET /files/...)

    Authority: writes always go to k3s-or (Oregon). The API then pushes objects to slave MinIO ingest endpoints (Finland / Ukraine). Slaves never pull from master; pull CronJobs are disabled.

    Provider SSOT (shared)

    Resolution order in lib/storage/storage-config.ts (mirrors db()):

    1. NEXT_PUBLIC_STORAGE_PROVIDER or STORAGE_PROVIDER
    2. ring-config.json → storage.provider
    3. Default: local_storage (development) / vercel_blob (production)
    Provider valueAdapterWhen to use
    local_storageLocalStorageAdapterLocal npm run dev, PVC-backed uploads
    vercel_blobVercelAdapterVercel-hosted clones with BLOB_READ_WRITE_TOKEN
    ring_filebaseRingBaseAdapterSelf-hosted / Ringdom k8s with RingFileBase API
    firebase_storageFalls back to local in selectorNot a first-class upload path today

    Why this matters for your clone

    Product images, KYC scans, chat attachments, and ImageConductor outputs all need a durable home. Vercel Blob is fine for small OSS demos; a marketplace clone that owns its data usually wants RingFileBase so media stays on your cluster, behind your CDN hostname, without per-GB Blob invoices.

    Typical scenarios

    Local development

    Keep storage.provider / env on local_storage — files land under public/uploads (or your PVC mount).

    Production marketplace

    Set ring_filebase, point RINGBASE_API_URL at the in-cluster API, publish URLs via Ring CDN (see Related below).

    File Cabinet

    Member uploads call with cabinet MIME/25MB limits; public gallery items reuse CDN .

    Architecture

    Verified modules

    PathRole
    lib/storage/storage-config.tsProvider SSOT + getStorageConfig()
    lib/file/FileService.tsfile() / fileService.upload
    lib/file/FileSelector.tsBackend map; constructs RingBaseAdapter from env
    lib/file/adapters/RingBaseAdapter.tsMultipart upload, delete, metadata, deriveDerivatives
    lib/images/derive-webp.tsOptional WebP sibling; storage.webpDerivative.provider=ringbase

    Related documentation

    Related documentation

    Ring CDN (RingFileBase edge)

    Next-step: public /files/... edge, host→bucket map, and geo delivery for uploaded objects.

    Ring File Cabinet

    Same-workflow: member /file-cabinet uploads via file() + getCabinetStorageConfig; gallery uses derivativesProfile gallery; subscriber+ /profile/shared is ACL-only (no own uploads).

    Environment Configuration

    Depends-on: storage env block (RINGBASE_*) and generative conductor prerequisites.

    Backup & Recovery

    See-also: object store is a separate backup asset from Postgres.

    file()
    /files/{uuid}

    Managed Ringdom hosting

    Operators deploy ring-filebase + ring-filebase-minio namespaces; your clone only needs ConfigMap/Secret wiring.

    Backup pairing

    Postgres dumps do not include MinIO objects — schedule object-store backups separately from pg_dump.

    Do not point RINGBASE_API_URL at your Next.js host

    api. hostnames often route to the Ring app ingress. Uploads must hit ring-filebase-api (in-cluster) or https://filebase-api.ring-platform.org (public write on primary) — never the Next.js deployment. Wrong URL surfaces as HTML or HTTP 500 instead of JSON success/fileId/url.

    lib/uploads/server/upload-core.ts
    Unified upload used by POST /api/uploads
    app/api/uploads/route.tsBrowser/form upload entry
    infrastructure/ring-file-base/services/ring-filebase-api/API source (derivatives + propagate)
    infrastructure/ring-file-base/k8s/ring-filebase/10-api-deployment.yamlDeploy template
    infrastructure/k3s-or/ring-filebase/60-propagate-slaves-configmap.yamlSlave ingest registry

    Environment variables

    VariableRequired for ring_filebaseNotes
    NEXT_PUBLIC_STORAGE_PROVIDERYesSet to ring_filebase (aliases: ringbase, filebase)
    RINGBASE_API_URLYesHost or host + /api/v1; adapter normalizes to …/api/v1
    RINGBASE_API_TOKENYesBearer for API auth middleware
    RINGBASE_PUBLIC_URLRecommendedPublic base used in returned URLs (usually CDN origin)
    NEXT_PUBLIC_RINGBASE_API_URLOptionalFallback if RINGBASE_API_URL unset
    BLOB_READ_WRITE_TOKENNoOnly for vercel_blob
    NEXT_PUBLIC_LOCAL_STORAGE_URLNoOnly for local_storage

    ring-config.json example:

    k8s ConfigMap / Secret pattern (see k8s/secrets.example.yaml):

    Upload type mapping (resolveRingBaseUploadType)

    The API validates MIME types per type field. The adapter maps:

    Content / accesstype sent to API
    access: 'private'document
    image/*image (first-class; product is a deprecated alias)
    video/* or audio/*media
    Everything elseother

    Optional overrides: ringbaseType, derivativesProfile (none | thumb | gallery | product | news).

    Derivative key scheme (SSOT)

    PatternStatus
    {fileId}_v_{variant} e.g. _v_thumb.webp, _v_blur.webp, _v_sync_thumb.jpgCurrent — only scheme the API writes
    {fileId}_v_video_frame_N.jpg / _v_video_frame_N_480.webpCurrent — async HEIC/video frames (_480.webp under _v_ is intentional)
    {fileId}_thumb, {fileId}_thumb_v{N}, {fileId}_thumb_v{N}_480w.webpBanned — never write; purge orphans with infrastructure/ring-file-base/scripts/purge-legacy-derivative-keys.sh

    Prefer upload type=image for rasters (product is a deprecated alias → image). Thumbnail status poll: GET /api/v1/files/{fileId}/thumbnail?type=image.

    App wiring (2026-07-15): upload-core and /api/uploads request ladders when storage.provider is ring_filebase (purpose→profile: news→news, product media→product, nft/chat images→gallery, avatar/logos→thumb, docs→none). Responses include fileId + derivatives. Persist as MediaImageAsset on news (featuredImageAsset / gallery) and GalleryItem.derivatives on store/NFT. Display via pickImageSrc / pickGalleryDisplayUrl. Dead Vikka dual-compat (vikka-field-normalize / NEXT_PUBLIC_NEWS_VIKKA_COMPAT) was deleted — camelCase JSONB only.

    Sending images as media fails validation (A/V + HEIC only in current API rules).

    Bucket hygiene (after push-only is stable)

    Dry-run on primary, then FI/UA slaves: ./scripts/purge-legacy-derivative-keys.sh --endpoint https://… --bucket ring-filebase. Add --delete only after reviewing the sample list. Does not match intentional _v_video_frame_*_480.webp or _v_thumb.webp.

    Wire-up steps

    1. 1

      Choose provider

      Set env and/or ring-config.json storage.provider to ring_filebase. Restart Next.js after env changes.

    2. 2

      Deploy API + MinIO (cluster)

      Apply RingFileBase manifests under infrastructure/ring-file-base/k8s/ring-filebase/ (API Deployment/Service, MinIO namespace, CDN stack). Ensure the API can reach minio-service.ring-filebase-minio.svc.cluster.local:9000 and the target bucket exists.

    3. 3

      Issue a Bearer token

      API auth (services/ring-filebase-api/src/middleware/auth.ts) expects a JWT whose decoded claims include:

      • iss = kubernetes/serviceaccount
      • kubernetes.io/serviceaccount/namespace
      • kubernetes.io/serviceaccount/service-account.name

      Today the middleware decodes claims and does not call TokenReview or enforce exp. Prefer a long-lived claim-shaped token in Secrets — do not paste a one-hour projected ServiceAccount JWT into RINGBASE_API_TOKEN and forget it.

    4. 4

      Smoke test from the app pod

      Expect JSON with success: true, fileId, url, and optional derivatives under your CDN host. Within seconds, slave ingest HEAD for the same key should be 200 (master push).

    5. 5

      App-level upload

      Browser forms should use POST /api/uploads (unified upload core), not call RingFileBase directly.

    Common failures

    SymptomLikely cause
    HTML / 500 from upload URLRINGBASE_API_URL points at Next.js (api. ingress)
    401 Invalid ServiceAccount tokenToken missing legacy SA claim shape
    Invalid file type … got: image/pngtype=media instead of image / other
    Upload OK, CDN 404 on slave brieflyRare race before push; edges must keep proxy_cache_valid 404 0
    Upload OK, CDN 403MinIO bucket lacks anonymous GetObject (or CDN Host header misconfigured)
    Node stream.isDisturbed on BlobPrefer local_storage or ring_filebase; Vercel adapter uploads Uint8Array
    Propagate stuck failedPOST /api/v1/replication/redrive on primary (max 3 retries then stop)

    Integrations

    See-also: full integration catalog hub.

    file()
    /files/{uuid}

    Managed Ringdom hosting

    Operators deploy ring-filebase + ring-filebase-minio namespaces; your clone only needs ConfigMap/Secret wiring.

    Backup pairing

    Postgres dumps do not include MinIO objects — schedule object-store backups separately from pg_dump.

    Do not point RINGBASE_API_URL at your Next.js host

    api. hostnames often route to the Ring app ingress. Uploads must hit ring-filebase-api (in-cluster) or https://filebase-api.ring-platform.org (public write on primary) — never the Next.js deployment. Wrong URL surfaces as HTML or HTTP 500 instead of JSON success/fileId/url.

    lib/uploads/server/upload-core.ts
    Unified upload used by POST /api/uploads
    app/api/uploads/route.tsBrowser/form upload entry
    infrastructure/ring-file-base/services/ring-filebase-api/API source (derivatives + propagate)
    infrastructure/ring-file-base/k8s/ring-filebase/10-api-deployment.yamlDeploy template
    infrastructure/k3s-or/ring-filebase/60-propagate-slaves-configmap.yamlSlave ingest registry

    Environment variables

    VariableRequired for ring_filebaseNotes
    NEXT_PUBLIC_STORAGE_PROVIDERYesSet to ring_filebase (aliases: ringbase, filebase)
    RINGBASE_API_URLYesHost or host + /api/v1; adapter normalizes to …/api/v1
    RINGBASE_API_TOKENYesBearer for API auth middleware
    RINGBASE_PUBLIC_URLRecommendedPublic base used in returned URLs (usually CDN origin)
    NEXT_PUBLIC_RINGBASE_API_URLOptionalFallback if RINGBASE_API_URL unset
    BLOB_READ_WRITE_TOKENNoOnly for vercel_blob
    NEXT_PUBLIC_LOCAL_STORAGE_URLNoOnly for local_storage

    ring-config.json example:

    k8s ConfigMap / Secret pattern (see k8s/secrets.example.yaml):

    Upload type mapping (resolveRingBaseUploadType)

    The API validates MIME types per type field. The adapter maps:

    Content / accesstype sent to API
    access: 'private'document
    image/*image (first-class; product is a deprecated alias)
    video/* or audio/*media
    Everything elseother

    Optional overrides: ringbaseType, derivativesProfile (none | thumb | gallery | product | news).

    Derivative key scheme (SSOT)

    PatternStatus
    {fileId}_v_{variant} e.g. _v_thumb.webp, _v_blur.webp, _v_sync_thumb.jpgCurrent — only scheme the API writes
    {fileId}_v_video_frame_N.jpg / _v_video_frame_N_480.webpCurrent — async HEIC/video frames (_480.webp under _v_ is intentional)
    {fileId}_thumb, {fileId}_thumb_v{N}, {fileId}_thumb_v{N}_480w.webpBanned — never write; purge orphans with infrastructure/ring-file-base/scripts/purge-legacy-derivative-keys.sh

    Prefer upload type=image for rasters (product is a deprecated alias → image). Thumbnail status poll: GET /api/v1/files/{fileId}/thumbnail?type=image.

    App wiring (2026-07-15): upload-core and /api/uploads request ladders when storage.provider is ring_filebase (purpose→profile: news→news, product media→product, nft/chat images→gallery, avatar/logos→thumb, docs→none). Responses include fileId + derivatives. Persist as MediaImageAsset on news (featuredImageAsset / gallery) and GalleryItem.derivatives on store/NFT. Display via pickImageSrc / pickGalleryDisplayUrl. Dead Vikka dual-compat (vikka-field-normalize / NEXT_PUBLIC_NEWS_VIKKA_COMPAT) was deleted — camelCase JSONB only.

    Sending images as media fails validation (A/V + HEIC only in current API rules).

    Bucket hygiene (after push-only is stable)

    Dry-run on primary, then FI/UA slaves: ./scripts/purge-legacy-derivative-keys.sh --endpoint https://… --bucket ring-filebase. Add --delete only after reviewing the sample list. Does not match intentional _v_video_frame_*_480.webp or _v_thumb.webp.

    Wire-up steps

    1. 1

      Choose provider

      Set env and/or ring-config.json storage.provider to ring_filebase. Restart Next.js after env changes.

    2. 2

      Deploy API + MinIO (cluster)

      Apply RingFileBase manifests under infrastructure/ring-file-base/k8s/ring-filebase/ (API Deployment/Service, MinIO namespace, CDN stack). Ensure the API can reach minio-service.ring-filebase-minio.svc.cluster.local:9000 and the target bucket exists.

    3. 3

      Issue a Bearer token

      API auth (services/ring-filebase-api/src/middleware/auth.ts) expects a JWT whose decoded claims include:

      • iss = kubernetes/serviceaccount
      • kubernetes.io/serviceaccount/namespace
      • kubernetes.io/serviceaccount/service-account.name

      Today the middleware decodes claims and does not call TokenReview or enforce exp. Prefer a long-lived claim-shaped token in Secrets — do not paste a one-hour projected ServiceAccount JWT into RINGBASE_API_TOKEN and forget it.

    4. 4

      Smoke test from the app pod

      Expect JSON with success: true, fileId, url, and optional derivatives under your CDN host. Within seconds, slave ingest HEAD for the same key should be 200 (master push).

    5. 5

      App-level upload

      Browser forms should use POST /api/uploads (unified upload core), not call RingFileBase directly.

    Common failures

    SymptomLikely cause
    HTML / 500 from upload URLRINGBASE_API_URL points at Next.js (api. ingress)
    401 Invalid ServiceAccount tokenToken missing legacy SA claim shape
    Invalid file type … got: image/pngtype=media instead of image / other
    Upload OK, CDN 404 on slave brieflyRare race before push; edges must keep proxy_cache_valid 404 0
    Upload OK, CDN 403MinIO bucket lacks anonymous GetObject (or CDN Host header misconfigured)
    Node stream.isDisturbed on BlobPrefer local_storage or ring_filebase; Vercel adapter uploads Uint8Array
    Propagate stuck failedPOST /api/v1/replication/redrive on primary (max 3 retries then stop)

    Integrations

    See-also: full integration catalog hub.

    file()
    /files/{uuid}

    Managed Ringdom hosting

    Operators deploy ring-filebase + ring-filebase-minio namespaces; your clone only needs ConfigMap/Secret wiring.

    Backup pairing

    Postgres dumps do not include MinIO objects — schedule object-store backups separately from pg_dump.

    Do not point RINGBASE_API_URL at your Next.js host

    api. hostnames often route to the Ring app ingress. Uploads must hit ring-filebase-api (in-cluster) or https://filebase-api.ring-platform.org (public write on primary) — never the Next.js deployment. Wrong URL surfaces as HTML or HTTP 500 instead of JSON success/fileId/url.

    lib/uploads/server/upload-core.ts
    Unified upload used by POST /api/uploads
    app/api/uploads/route.tsBrowser/form upload entry
    infrastructure/ring-file-base/services/ring-filebase-api/API source (derivatives + propagate)
    infrastructure/ring-file-base/k8s/ring-filebase/10-api-deployment.yamlDeploy template
    infrastructure/k3s-or/ring-filebase/60-propagate-slaves-configmap.yamlSlave ingest registry

    Environment variables

    VariableRequired for ring_filebaseNotes
    NEXT_PUBLIC_STORAGE_PROVIDERYesSet to ring_filebase (aliases: ringbase, filebase)
    RINGBASE_API_URLYesHost or host + /api/v1; adapter normalizes to …/api/v1
    RINGBASE_API_TOKENYesBearer for API auth middleware
    RINGBASE_PUBLIC_URLRecommendedPublic base used in returned URLs (usually CDN origin)
    NEXT_PUBLIC_RINGBASE_API_URLOptionalFallback if RINGBASE_API_URL unset
    BLOB_READ_WRITE_TOKENNoOnly for vercel_blob
    NEXT_PUBLIC_LOCAL_STORAGE_URLNoOnly for local_storage

    ring-config.json example:

    k8s ConfigMap / Secret pattern (see k8s/secrets.example.yaml):

    Upload type mapping (resolveRingBaseUploadType)

    The API validates MIME types per type field. The adapter maps:

    Content / accesstype sent to API
    access: 'private'document
    image/*image (first-class; product is a deprecated alias)
    video/* or audio/*media
    Everything elseother

    Optional overrides: ringbaseType, derivativesProfile (none | thumb | gallery | product | news).

    Derivative key scheme (SSOT)

    PatternStatus
    {fileId}_v_{variant} e.g. _v_thumb.webp, _v_blur.webp, _v_sync_thumb.jpgCurrent — only scheme the API writes
    {fileId}_v_video_frame_N.jpg / _v_video_frame_N_480.webpCurrent — async HEIC/video frames (_480.webp under _v_ is intentional)
    {fileId}_thumb, {fileId}_thumb_v{N}, {fileId}_thumb_v{N}_480w.webpBanned — never write; purge orphans with infrastructure/ring-file-base/scripts/purge-legacy-derivative-keys.sh

    Prefer upload type=image for rasters (product is a deprecated alias → image). Thumbnail status poll: GET /api/v1/files/{fileId}/thumbnail?type=image.

    App wiring (2026-07-15): upload-core and /api/uploads request ladders when storage.provider is ring_filebase (purpose→profile: news→news, product media→product, nft/chat images→gallery, avatar/logos→thumb, docs→none). Responses include fileId + derivatives. Persist as MediaImageAsset on news (featuredImageAsset / gallery) and GalleryItem.derivatives on store/NFT. Display via pickImageSrc / pickGalleryDisplayUrl. Dead Vikka dual-compat (vikka-field-normalize / NEXT_PUBLIC_NEWS_VIKKA_COMPAT) was deleted — camelCase JSONB only.

    Sending images as media fails validation (A/V + HEIC only in current API rules).

    Bucket hygiene (after push-only is stable)

    Dry-run on primary, then FI/UA slaves: ./scripts/purge-legacy-derivative-keys.sh --endpoint https://… --bucket ring-filebase. Add --delete only after reviewing the sample list. Does not match intentional _v_video_frame_*_480.webp or _v_thumb.webp.

    Wire-up steps

    1. 1

      Choose provider

      Set env and/or ring-config.json storage.provider to ring_filebase. Restart Next.js after env changes.

    2. 2

      Deploy API + MinIO (cluster)

      Apply RingFileBase manifests under infrastructure/ring-file-base/k8s/ring-filebase/ (API Deployment/Service, MinIO namespace, CDN stack). Ensure the API can reach minio-service.ring-filebase-minio.svc.cluster.local:9000 and the target bucket exists.

    3. 3

      Issue a Bearer token

      API auth (services/ring-filebase-api/src/middleware/auth.ts) expects a JWT whose decoded claims include:

      • iss = kubernetes/serviceaccount
      • kubernetes.io/serviceaccount/namespace
      • kubernetes.io/serviceaccount/service-account.name

      Today the middleware decodes claims and does not call TokenReview or enforce exp. Prefer a long-lived claim-shaped token in Secrets — do not paste a one-hour projected ServiceAccount JWT into RINGBASE_API_TOKEN and forget it.

    4. 4

      Smoke test from the app pod

      Expect JSON with success: true, fileId, url, and optional derivatives under your CDN host. Within seconds, slave ingest HEAD for the same key should be 200 (master push).

    5. 5

      App-level upload

      Browser forms should use POST /api/uploads (unified upload core), not call RingFileBase directly.

    Common failures

    SymptomLikely cause
    HTML / 500 from upload URLRINGBASE_API_URL points at Next.js (api. ingress)
    401 Invalid ServiceAccount tokenToken missing legacy SA claim shape
    Invalid file type … got: image/pngtype=media instead of image / other
    Upload OK, CDN 404 on slave brieflyRare race before push; edges must keep proxy_cache_valid 404 0
    Upload OK, CDN 403MinIO bucket lacks anonymous GetObject (or CDN Host header misconfigured)
    Node stream.isDisturbed on BlobPrefer local_storage or ring_filebase; Vercel adapter uploads Uint8Array
    Propagate stuck failedPOST /api/v1/replication/redrive on primary (max 3 retries then stop)

    Integrations

    See-also: full integration catalog hub.

    1. Docs
    2. /Integrations
    3. /RingFileBase (object storage API)

    Updated Jul 21, 20266 min listen

    1. Docs
    2. /Integrations
    3. /RingFileBase (object storage API)

    Updated Jul 21, 20266 min listen

    1. Docs
    2. /Integrations
    3. /RingFileBase (object storage API)

    Updated Jul 21, 20266 min listen