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
    SubscriptionConductor
    PaymentConductor
    Payments Overview
    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
    News Module
    Member Blogs
    Public Profile Pages
    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
    Branding
    Themes
    Features
    Localization
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    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
    Docker
    Environment Configuration
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Architecture
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    PaymentConductor architecture
    WalletConductor architecture
    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
    SubscriptionConductor
    PaymentConductor
    Payments Overview
    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
    News Module
    Member Blogs
    Public Profile Pages
    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
    Branding
    Themes
    Features
    Localization
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    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
    Docker
    Environment Configuration
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Architecture
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    PaymentConductor architecture
    WalletConductor architecture
    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
    SubscriptionConductor
    PaymentConductor
    Payments Overview
    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
    News Module
    Member Blogs
    Public Profile Pages
    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
    Branding
    Themes
    Features
    Localization
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    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
    Docker
    Environment Configuration
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Architecture
    Data Model
    Security
    Real Time
    Discovery Mutation Sync
    PaymentConductor architecture
    WalletConductor architecture
    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)
    1. Docs
    2. /Deployment
    3. /Environment Configuration
    Updated Jul 20, 20264 min listen
    Ring Platform Logo

    Завантаження документації...

    Підготовка контенту платформи Ring

    1. Docs
    2. /Deployment
    3. /Environment Configuration
    Updated Jul 20, 20264 min listen
    Ring Platform Logo

    Завантаження документації...

    Підготовка контенту платформи Ring

    1. Docs
    2. /Deployment
    3. /Environment Configuration
    Updated Jul 20, 20264 min listen
    Ring Platform Logo

    Завантаження документації...

    Підготовка контенту платформи Ring

    Environment Configuration

    This page is the canonical reference for every environment variable consumed by Ring Platform. The source of truth is env.local.template in the repository root — when in doubt, consult that file. Use Founder / Developer tabs in the docs sidebar to filter by audience.

    DB_BACKEND_MODE (required)

    Ring Platform requires DB_BACKEND_MODE at runtime. It controls which database adapter is active and how FCM push notifications are wired.

    ValueApplication databaseFirebase Admin for Firestore?Push
    k8s-postgres-fcmPostgreSQL (your cluster)No — mock FirestoreFCM via Firebase Admin messaging
    firebase-fullFirestoreYesFCM as part of full Firebase stack
    supabase-fcmSupabase PostgreSQLNo — mock FirestoreFCM via Firebase Admin messaging

    See Backend modes and databases for a deep comparison.

    Firebase: when is it needed?

    Your Ring clone may need Firebase project credentials in two contexts:

    1. Push notifications (FCM) — required in all three DB_BACKEND_MODE values if you want push delivery. Firebase is used as the FCM transport only; your application data stays in PostgreSQL.
    2. Full Firestore backend — only when DB_BACKEND_MODE=firebase-full. In this mode Firebase Admin SDK serves as the primary database.

    If you don't need push notifications, you can omit all Firebase environment variables. The platform runs on PostgreSQL alone.

    Firebase Admin SDK v14 uses Application Default Credentials (ADC) in the FirebaseAdapter (database abstraction layer). For the FCM/auth path (firebase-admin.server.ts), explicit service-account credentials via AUTH_FIREBASE_CLIENT_EMAIL + AUTH_FIREBASE_PRIVATE_KEY are still required when ADC is not configured.

    In production (Cloud Run, Cloud Functions, GKE), ADC auto-detects credentials from the environment. You only need AUTH_FIREBASE_PROJECT_ID. On local dev or CI, provide the full service-account key set.

    Database backend

    The canonical dev setup uses ring-postgres-dev (postgres:16-alpine). See docker-compose.dev.yml.

    Firebase Admin SDK (server-side)

    • lib/firebase-admin.server.ts (FCM + Auth path): always requires AUTH_FIREBASE_PROJECT_ID. When AUTH_FIREBASE_CLIENT_EMAIL and AUTH_FIREBASE_PRIVATE_KEY are present, uses explicit cert(). Falls back to ADC if they are absent.
    • lib/database/adapters/FirebaseAdapter.ts (database abstraction): uses ADC first. If credentials.clientEmail and credentials.privateKey are in the backend config, falls back to explicit cert(). This path is only active in firebase-full mode.

    On Cloud Run / Cloud Functions / GKE: set only AUTH_FIREBASE_PROJECT_ID. The SDK auto-detects credentials via ADC. On local dev: set AUTH_FIREBASE_CLIENT_EMAIL and AUTH_FIREBASE_PRIVATE_KEY from your service-account JSON key.

    Firebase Client SDK (browser-side)

    Required when your Ring clone uses Firebase for client-side features (FCM push token registration, FirebaseUI auth):

    Get these from Firebase Console → Project Settings → General → Web apps.

    Auth providers

    Auth.js v5 reads AUTH_* prefixed vars for OAuth/OIDC providers (Google, Telegram, Apple). Email auth uses Ring Mailer — see Ring Mailer and Authentication.

    Payments (PaymentConductor)

    Related documentation

    Backend modes and databases

    Database selection

    Authentication

    Docker deployment

    Environment Configuration

    This page is the canonical reference for every environment variable consumed by Ring Platform. The source of truth is env.local.template in the repository root — when in doubt, consult that file. Use Founder / Developer tabs in the docs sidebar to filter by audience.

    DB_BACKEND_MODE (required)

    Ring Platform requires DB_BACKEND_MODE at runtime. It controls which database adapter is active and how FCM push notifications are wired.

    ValueApplication databaseFirebase Admin for Firestore?Push
    k8s-postgres-fcmPostgreSQL (your cluster)No — mock FirestoreFCM via Firebase Admin messaging
    firebase-fullFirestoreYesFCM as part of full Firebase stack
    supabase-fcmSupabase PostgreSQLNo — mock FirestoreFCM via Firebase Admin messaging

    See Backend modes and databases for a deep comparison.

    Firebase: when is it needed?

    Your Ring clone may need Firebase project credentials in two contexts:

    1. Push notifications (FCM) — required in all three DB_BACKEND_MODE values if you want push delivery. Firebase is used as the FCM transport only; your application data stays in PostgreSQL.
    2. Full Firestore backend — only when DB_BACKEND_MODE=firebase-full. In this mode Firebase Admin SDK serves as the primary database.

    If you don't need push notifications, you can omit all Firebase environment variables. The platform runs on PostgreSQL alone.

    Firebase Admin SDK v14 uses Application Default Credentials (ADC) in the FirebaseAdapter (database abstraction layer). For the FCM/auth path (firebase-admin.server.ts), explicit service-account credentials via AUTH_FIREBASE_CLIENT_EMAIL + AUTH_FIREBASE_PRIVATE_KEY are still required when ADC is not configured.

    In production (Cloud Run, Cloud Functions, GKE), ADC auto-detects credentials from the environment. You only need AUTH_FIREBASE_PROJECT_ID. On local dev or CI, provide the full service-account key set.

    Database backend

    The canonical dev setup uses ring-postgres-dev (postgres:16-alpine). See docker-compose.dev.yml.

    Firebase Admin SDK (server-side)

    • lib/firebase-admin.server.ts (FCM + Auth path): always requires AUTH_FIREBASE_PROJECT_ID. When AUTH_FIREBASE_CLIENT_EMAIL and AUTH_FIREBASE_PRIVATE_KEY are present, uses explicit cert(). Falls back to ADC if they are absent.
    • lib/database/adapters/FirebaseAdapter.ts (database abstraction): uses ADC first. If credentials.clientEmail and credentials.privateKey are in the backend config, falls back to explicit cert(). This path is only active in firebase-full mode.

    On Cloud Run / Cloud Functions / GKE: set only AUTH_FIREBASE_PROJECT_ID. The SDK auto-detects credentials via ADC. On local dev: set AUTH_FIREBASE_CLIENT_EMAIL and AUTH_FIREBASE_PRIVATE_KEY from your service-account JSON key.

    Firebase Client SDK (browser-side)

    Required when your Ring clone uses Firebase for client-side features (FCM push token registration, FirebaseUI auth):

    Get these from Firebase Console → Project Settings → General → Web apps.

    Auth providers

    Auth.js v5 reads AUTH_* prefixed vars for OAuth/OIDC providers (Google, Telegram, Apple). Email auth uses Ring Mailer — see Ring Mailer and Authentication.

    Payments (PaymentConductor)

    Related documentation

    Backend modes and databases

    Database selection

    Authentication

    Docker deployment

    Environment Configuration

    This page is the canonical reference for every environment variable consumed by Ring Platform. The source of truth is env.local.template in the repository root — when in doubt, consult that file. Use Founder / Developer tabs in the docs sidebar to filter by audience.

    DB_BACKEND_MODE (required)

    Ring Platform requires DB_BACKEND_MODE at runtime. It controls which database adapter is active and how FCM push notifications are wired.

    ValueApplication databaseFirebase Admin for Firestore?Push
    k8s-postgres-fcmPostgreSQL (your cluster)No — mock FirestoreFCM via Firebase Admin messaging
    firebase-fullFirestoreYesFCM as part of full Firebase stack
    supabase-fcmSupabase PostgreSQLNo — mock FirestoreFCM via Firebase Admin messaging

    See Backend modes and databases for a deep comparison.

    Firebase: when is it needed?

    Your Ring clone may need Firebase project credentials in two contexts:

    1. Push notifications (FCM) — required in all three DB_BACKEND_MODE values if you want push delivery. Firebase is used as the FCM transport only; your application data stays in PostgreSQL.
    2. Full Firestore backend — only when DB_BACKEND_MODE=firebase-full. In this mode Firebase Admin SDK serves as the primary database.

    If you don't need push notifications, you can omit all Firebase environment variables. The platform runs on PostgreSQL alone.

    Firebase Admin SDK v14 uses Application Default Credentials (ADC) in the FirebaseAdapter (database abstraction layer). For the FCM/auth path (firebase-admin.server.ts), explicit service-account credentials via AUTH_FIREBASE_CLIENT_EMAIL + AUTH_FIREBASE_PRIVATE_KEY are still required when ADC is not configured.

    In production (Cloud Run, Cloud Functions, GKE), ADC auto-detects credentials from the environment. You only need AUTH_FIREBASE_PROJECT_ID. On local dev or CI, provide the full service-account key set.

    Database backend

    The canonical dev setup uses ring-postgres-dev (postgres:16-alpine). See docker-compose.dev.yml.

    Firebase Admin SDK (server-side)

    • lib/firebase-admin.server.ts (FCM + Auth path): always requires AUTH_FIREBASE_PROJECT_ID. When AUTH_FIREBASE_CLIENT_EMAIL and AUTH_FIREBASE_PRIVATE_KEY are present, uses explicit cert(). Falls back to ADC if they are absent.
    • lib/database/adapters/FirebaseAdapter.ts (database abstraction): uses ADC first. If credentials.clientEmail and credentials.privateKey are in the backend config, falls back to explicit cert(). This path is only active in firebase-full mode.

    On Cloud Run / Cloud Functions / GKE: set only AUTH_FIREBASE_PROJECT_ID. The SDK auto-detects credentials via ADC. On local dev: set AUTH_FIREBASE_CLIENT_EMAIL and AUTH_FIREBASE_PRIVATE_KEY from your service-account JSON key.

    Firebase Client SDK (browser-side)

    Required when your Ring clone uses Firebase for client-side features (FCM push token registration, FirebaseUI auth):

    Get these from Firebase Console → Project Settings → General → Web apps.

    Auth providers

    Auth.js v5 reads AUTH_* prefixed vars for OAuth/OIDC providers (Google, Telegram, Apple). Email auth uses Ring Mailer — see Ring Mailer and Authentication.

    Payments (PaymentConductor)

    Related documentation

    Backend modes and databases

    Database selection

    Authentication

    Docker deployment

    Apply data/migrations/004_payment_transactions.sql before production payments.

    Locales

    See lib/locale-config.ts. Supported locales: en, uk, ru.

    Generative conductors (xAI Grok)

    Per‑purpose prefixes:

    • IMAGE_GEN_* / XAI_IMAGE_* — ImageConductor
    • TEXT_GEN_* / XAI_TEXT_* — TextConductor (cited articles)
    • TTS_* / XAI_TTS_* — AudioConductor (narration)
    • NEWS_AUTOGEN_* — newsroom draft defaults

    Requires NEXT_PUBLIC_STORAGE_PROVIDER=ring_filebase (or ring-config.json storage.provider) with RINGBASE_API_URL and RINGBASE_API_TOKEN for CDN-backed uploads. See RingFileBase and Ring CDN.

    File storage (file())

    Provider SSOT: lib/storage/storage-config.ts — env → ring-config.json storage.provider → default (local_storage in development, vercel_blob in production).

    CDN slaves (k3s-3 / k8s-1) are pull-mirrors only — never point uploads at them. Do not set RINGBASE_API_URL to your Next.js api. hostname — that ingress serves the app, not RingFileBase.

    Ring Tunnel (real-time)

    Feature flags

    Platform

    Optional — Email AI-CRM, CRON, backup

    See env.local.template for the complete commented reference. Key optional blocks:

    Never commit real secrets to Git. The env.local.template file uses placeholder values. Copy it to .env.local (gitignored) and fill in your production values. Use K8s secrets or your deployment system's secret store for production.

    bash
    
# Required — selects database adapter + FCM wiring
DB_BACKEND_MODE=k8s-postgres-fcm

# PostgreSQL connection (required for k8s-postgres-fcm and supabase-fcm)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ring_platform
DB_USER=ring_user
DB_PASSWORD=ring_password_2024
DB_POOL_SIZE=20
DB_TIMEOUT=30000
DB_RETRIES=3
DB_SSL=false
    bash
    
# Minimum for FCM-only usage:
AUTH_FIREBASE_PROJECT_ID=your_firebase_project_id

# Required when ADC is not configured (local dev / CI):
AUTH_FIREBASE_CLIENT_EMAIL=your_firebase_client_email
AUTH_FIREBASE_PRIVATE_KEY="your_firebase_private_key"

# Optional
FIREBASE_DATABASE_URL=https://your-project-default-rtdb.firebaseio.com
FIREBASE_PRIVATE_KEY_ID=your_firebase_private_key_id
FIREBASE_CLIENT_ID="your_firebase_client_id"
FIREBASE_FIRESTORE_DEBUG=true
    bash
    
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_firebase_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=G-YCZKPV315E
NEXT_PUBLIC_FIREBASE_VAPID_KEY=your_vapid_key
    bash
    
# Auth.js core
AUTH_SECRET=your_auth_secret
AUTH_TRUST_HOST=true

# Google OAuth (required for Google sign-in)
AUTH_GOOGLE_ID=your_google_client_id
AUTH_GOOGLE_SECRET=your_google_client_secret

# Telegram Web Login OIDC (BotFather → Bot Settings → Web Login)
# Allowed URLs: https://<host> and https://<host>/api/auth/callback/telegram
AUTH_TELEGRAM_ID=your_telegram_oidc_client_id
AUTH_TELEGRAM_SECRET=your_telegram_oidc_client_secret
# ADMIN_BOT_TOKEN=...  # Login Widget hash + admin bot API (not the OIDC secret)

# Apple Sign-In (required for Apple sign-in)
AUTH_APPLE_ID=your_apple_client_id
AUTH_APPLE_SECRET=your_apple_private_key

# Ring Mailer — OTP / magic link / reset (own SMTP; no AUTH_RESEND_*)
# EMAIL_MODE=ethereal
SMTP_HOST=mail.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=noreply@example.com
SMTP_PASSWORD=
SMTP_FROM=Ring Platform <noreply@example.com>
# OTP_HMAC_SECRET=

    Apply data/migrations/004_payment_transactions.sql before production payments.

    Locales

    See lib/locale-config.ts. Supported locales: en, uk, ru.

    Generative conductors (xAI Grok)

    Per‑purpose prefixes:

    • IMAGE_GEN_* / XAI_IMAGE_* — ImageConductor
    • TEXT_GEN_* / XAI_TEXT_* — TextConductor (cited articles)
    • TTS_* / XAI_TTS_* — AudioConductor (narration)
    • NEWS_AUTOGEN_* — newsroom draft defaults

    Requires NEXT_PUBLIC_STORAGE_PROVIDER=ring_filebase (or ring-config.json storage.provider) with RINGBASE_API_URL and RINGBASE_API_TOKEN for CDN-backed uploads. See RingFileBase and Ring CDN.

    File storage (file())

    Provider SSOT: lib/storage/storage-config.ts — env → ring-config.json storage.provider → default (local_storage in development, vercel_blob in production).

    CDN slaves (k3s-3 / k8s-1) are pull-mirrors only — never point uploads at them. Do not set RINGBASE_API_URL to your Next.js api. hostname — that ingress serves the app, not RingFileBase.

    Ring Tunnel (real-time)

    Feature flags

    Platform

    Optional — Email AI-CRM, CRON, backup

    See env.local.template for the complete commented reference. Key optional blocks:

    Never commit real secrets to Git. The env.local.template file uses placeholder values. Copy it to .env.local (gitignored) and fill in your production values. Use K8s secrets or your deployment system's secret store for production.

    bash
    
# Required — selects database adapter + FCM wiring
DB_BACKEND_MODE=k8s-postgres-fcm

# PostgreSQL connection (required for k8s-postgres-fcm and supabase-fcm)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ring_platform
DB_USER=ring_user
DB_PASSWORD=ring_password_2024
DB_POOL_SIZE=20
DB_TIMEOUT=30000
DB_RETRIES=3
DB_SSL=false
    bash
    
# Minimum for FCM-only usage:
AUTH_FIREBASE_PROJECT_ID=your_firebase_project_id

# Required when ADC is not configured (local dev / CI):
AUTH_FIREBASE_CLIENT_EMAIL=your_firebase_client_email
AUTH_FIREBASE_PRIVATE_KEY="your_firebase_private_key"

# Optional
FIREBASE_DATABASE_URL=https://your-project-default-rtdb.firebaseio.com
FIREBASE_PRIVATE_KEY_ID=your_firebase_private_key_id
FIREBASE_CLIENT_ID="your_firebase_client_id"
FIREBASE_FIRESTORE_DEBUG=true
    bash
    
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_firebase_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=G-YCZKPV315E
NEXT_PUBLIC_FIREBASE_VAPID_KEY=your_vapid_key
    bash
    
# Auth.js core
AUTH_SECRET=your_auth_secret
AUTH_TRUST_HOST=true

# Google OAuth (required for Google sign-in)
AUTH_GOOGLE_ID=your_google_client_id
AUTH_GOOGLE_SECRET=your_google_client_secret

# Telegram Web Login OIDC (BotFather → Bot Settings → Web Login)
# Allowed URLs: https://<host> and https://<host>/api/auth/callback/telegram
AUTH_TELEGRAM_ID=your_telegram_oidc_client_id
AUTH_TELEGRAM_SECRET=your_telegram_oidc_client_secret
# ADMIN_BOT_TOKEN=...  # Login Widget hash + admin bot API (not the OIDC secret)

# Apple Sign-In (required for Apple sign-in)
AUTH_APPLE_ID=your_apple_client_id
AUTH_APPLE_SECRET=your_apple_private_key

# Ring Mailer — OTP / magic link / reset (own SMTP; no AUTH_RESEND_*)
# EMAIL_MODE=ethereal
SMTP_HOST=mail.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=noreply@example.com
SMTP_PASSWORD=
SMTP_FROM=Ring Platform <noreply@example.com>
# OTP_HMAC_SECRET=

    Apply data/migrations/004_payment_transactions.sql before production payments.

    Locales

    See lib/locale-config.ts. Supported locales: en, uk, ru.

    Generative conductors (xAI Grok)

    Per‑purpose prefixes:

    • IMAGE_GEN_* / XAI_IMAGE_* — ImageConductor
    • TEXT_GEN_* / XAI_TEXT_* — TextConductor (cited articles)
    • TTS_* / XAI_TTS_* — AudioConductor (narration)
    • NEWS_AUTOGEN_* — newsroom draft defaults

    Requires NEXT_PUBLIC_STORAGE_PROVIDER=ring_filebase (or ring-config.json storage.provider) with RINGBASE_API_URL and RINGBASE_API_TOKEN for CDN-backed uploads. See RingFileBase and Ring CDN.

    File storage (file())

    Provider SSOT: lib/storage/storage-config.ts — env → ring-config.json storage.provider → default (local_storage in development, vercel_blob in production).

    CDN slaves (k3s-3 / k8s-1) are pull-mirrors only — never point uploads at them. Do not set RINGBASE_API_URL to your Next.js api. hostname — that ingress serves the app, not RingFileBase.

    Ring Tunnel (real-time)

    Feature flags

    Platform

    Optional — Email AI-CRM, CRON, backup

    See env.local.template for the complete commented reference. Key optional blocks:

    Never commit real secrets to Git. The env.local.template file uses placeholder values. Copy it to .env.local (gitignored) and fill in your production values. Use K8s secrets or your deployment system's secret store for production.

    bash
    
# Required — selects database adapter + FCM wiring
DB_BACKEND_MODE=k8s-postgres-fcm

# PostgreSQL connection (required for k8s-postgres-fcm and supabase-fcm)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ring_platform
DB_USER=ring_user
DB_PASSWORD=ring_password_2024
DB_POOL_SIZE=20
DB_TIMEOUT=30000
DB_RETRIES=3
DB_SSL=false
    bash
    
# Minimum for FCM-only usage:
AUTH_FIREBASE_PROJECT_ID=your_firebase_project_id

# Required when ADC is not configured (local dev / CI):
AUTH_FIREBASE_CLIENT_EMAIL=your_firebase_client_email
AUTH_FIREBASE_PRIVATE_KEY="your_firebase_private_key"

# Optional
FIREBASE_DATABASE_URL=https://your-project-default-rtdb.firebaseio.com
FIREBASE_PRIVATE_KEY_ID=your_firebase_private_key_id
FIREBASE_CLIENT_ID="your_firebase_client_id"
FIREBASE_FIRESTORE_DEBUG=true
    bash
    
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_firebase_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=G-YCZKPV315E
NEXT_PUBLIC_FIREBASE_VAPID_KEY=your_vapid_key
    bash
    
# Auth.js core
AUTH_SECRET=your_auth_secret
AUTH_TRUST_HOST=true

# Google OAuth (required for Google sign-in)
AUTH_GOOGLE_ID=your_google_client_id
AUTH_GOOGLE_SECRET=your_google_client_secret

# Telegram Web Login OIDC (BotFather → Bot Settings → Web Login)
# Allowed URLs: https://<host> and https://<host>/api/auth/callback/telegram
AUTH_TELEGRAM_ID=your_telegram_oidc_client_id
AUTH_TELEGRAM_SECRET=your_telegram_oidc_client_secret
# ADMIN_BOT_TOKEN=...  # Login Widget hash + admin bot API (not the OIDC secret)

# Apple Sign-In (required for Apple sign-in)
AUTH_APPLE_ID=your_apple_client_id
AUTH_APPLE_SECRET=your_apple_private_key

# Ring Mailer — OTP / magic link / reset (own SMTP; no AUTH_RESEND_*)
# EMAIL_MODE=ethereal
SMTP_HOST=mail.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=noreply@example.com
SMTP_PASSWORD=
SMTP_FROM=Ring Platform <noreply@example.com>
# OTP_HMAC_SECRET=
    bash
    
# Default processor
PAYMENT_DEFAULT_PROCESSOR=stripe

# Per-purpose overrides (optional)
PAYMENT_STORE_PROCESSOR=stripe
PAYMENT_MEMBERSHIP_PROCESSOR=stripe
PAYMENT_NEWS_PROCESSOR=stripe

# WayForPay
WAYFORPAY_MERCHANT_ACCOUNT=your_merchant
WAYFORPAY_SECRET_KEY=your_secret

# Stripe (alternative)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
PAYMENT_FIAT_CURRENCY=USD
    bash
    
NEXT_PUBLIC_SUPPORTED_LOCALES=en,uk,ru
NEXT_PUBLIC_DEFAULT_LOCALE=en
    bash
    
XAI_API_KEY=your_xai_key
XAI_API_BASE_URL=https://api.x.ai/v1
    bash
    
# local_storage | vercel_blob | ring_filebase | firebase_storage
NEXT_PUBLIC_STORAGE_PROVIDER=local_storage

# vercel_blob
# BLOB_READ_WRITE_TOKEN=vercel_blob_rw_...

# local_storage
# NEXT_PUBLIC_LOCAL_STORAGE_URL=/uploads
# LOCAL_STORAGE_DIR=public/uploads

# ring_filebase (self-hosted / k8s) — write authority is k3s-or primary
# Prod (in-cluster):
# RINGBASE_API_URL=http://ring-filebase-api.ring-filebase.svc.cluster.local
# Local / CI (public write API on primary):
# RINGBASE_API_URL=https://filebase-api.ring-platform.org
# RINGBASE_API_TOKEN=...   # Secret — claim-shaped Bearer for ring-filebase-api
# RINGBASE_PUBLIC_URL=https://cdn.ring-platform.org
# NEXT_PUBLIC_RINGBASE_API_URL=   # optional fallback for API URL
# REFMAGIC_CDN_INTERNAL_URL=http://ring-filebase-cdn.ring-filebase.svc.cluster.local
    bash
    
# vercel | k8s | self-hosted
RING_DEPLOY_TARGET=self-hosted
NEXT_PUBLIC_RING_DEPLOY_TARGET=self-hosted

# Optional explicit WS URL (default: same host /api/tunnel/ws)
# NEXT_PUBLIC_TUNNEL_WS_URL=wss://ring-platform.org/api/tunnel/ws
    bash
    
FEATURE_DOCUMENTATION=true
FEATURE_NETWORKING=true
FEATURE_MESSAGING=true
FEATURE_WALLET=true
FEATURE_AI_MATCHER=true
FEATURE_WEB3_INTEGRATION=true
    bash
    
NEXT_PUBLIC_BASE_URL=https://ring-platform.org
NODE_ENV=development
    bash
    
# Email CRM (IMAP poll + admin UI)
# IMAP_HOST=mail.example.com
# IMAP_PORT=993
# ...

# CRON protection
# CRON_SECRET=generate-a-long-random-string

# Backup & compliance
# BACKUP_ENABLED=true
# BACKUP_SCHEDULE=0 2 * * *
    bash
    
# Default processor
PAYMENT_DEFAULT_PROCESSOR=stripe

# Per-purpose overrides (optional)
PAYMENT_STORE_PROCESSOR=stripe
PAYMENT_MEMBERSHIP_PROCESSOR=stripe
PAYMENT_NEWS_PROCESSOR=stripe

# WayForPay
WAYFORPAY_MERCHANT_ACCOUNT=your_merchant
WAYFORPAY_SECRET_KEY=your_secret

# Stripe (alternative)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
PAYMENT_FIAT_CURRENCY=USD
    bash
    
NEXT_PUBLIC_SUPPORTED_LOCALES=en,uk,ru
NEXT_PUBLIC_DEFAULT_LOCALE=en
    bash
    
XAI_API_KEY=your_xai_key
XAI_API_BASE_URL=https://api.x.ai/v1
    bash
    
# local_storage | vercel_blob | ring_filebase | firebase_storage
NEXT_PUBLIC_STORAGE_PROVIDER=local_storage

# vercel_blob
# BLOB_READ_WRITE_TOKEN=vercel_blob_rw_...

# local_storage
# NEXT_PUBLIC_LOCAL_STORAGE_URL=/uploads
# LOCAL_STORAGE_DIR=public/uploads

# ring_filebase (self-hosted / k8s) — write authority is k3s-or primary
# Prod (in-cluster):
# RINGBASE_API_URL=http://ring-filebase-api.ring-filebase.svc.cluster.local
# Local / CI (public write API on primary):
# RINGBASE_API_URL=https://filebase-api.ring-platform.org
# RINGBASE_API_TOKEN=...   # Secret — claim-shaped Bearer for ring-filebase-api
# RINGBASE_PUBLIC_URL=https://cdn.ring-platform.org
# NEXT_PUBLIC_RINGBASE_API_URL=   # optional fallback for API URL
# REFMAGIC_CDN_INTERNAL_URL=http://ring-filebase-cdn.ring-filebase.svc.cluster.local
    bash
    
# vercel | k8s | self-hosted
RING_DEPLOY_TARGET=self-hosted
NEXT_PUBLIC_RING_DEPLOY_TARGET=self-hosted

# Optional explicit WS URL (default: same host /api/tunnel/ws)
# NEXT_PUBLIC_TUNNEL_WS_URL=wss://ring-platform.org/api/tunnel/ws
    bash
    
FEATURE_DOCUMENTATION=true
FEATURE_NETWORKING=true
FEATURE_MESSAGING=true
FEATURE_WALLET=true
FEATURE_AI_MATCHER=true
FEATURE_WEB3_INTEGRATION=true
    bash
    
NEXT_PUBLIC_BASE_URL=https://ring-platform.org
NODE_ENV=development
    bash
    
# Email CRM (IMAP poll + admin UI)
# IMAP_HOST=mail.example.com
# IMAP_PORT=993
# ...

# CRON protection
# CRON_SECRET=generate-a-long-random-string

# Backup & compliance
# BACKUP_ENABLED=true
# BACKUP_SCHEDULE=0 2 * * *
    bash
    
# Default processor
PAYMENT_DEFAULT_PROCESSOR=stripe

# Per-purpose overrides (optional)
PAYMENT_STORE_PROCESSOR=stripe
PAYMENT_MEMBERSHIP_PROCESSOR=stripe
PAYMENT_NEWS_PROCESSOR=stripe

# WayForPay
WAYFORPAY_MERCHANT_ACCOUNT=your_merchant
WAYFORPAY_SECRET_KEY=your_secret

# Stripe (alternative)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
PAYMENT_FIAT_CURRENCY=USD
    bash
    
NEXT_PUBLIC_SUPPORTED_LOCALES=en,uk,ru
NEXT_PUBLIC_DEFAULT_LOCALE=en
    bash
    
XAI_API_KEY=your_xai_key
XAI_API_BASE_URL=https://api.x.ai/v1
    bash
    
# local_storage | vercel_blob | ring_filebase | firebase_storage
NEXT_PUBLIC_STORAGE_PROVIDER=local_storage

# vercel_blob
# BLOB_READ_WRITE_TOKEN=vercel_blob_rw_...

# local_storage
# NEXT_PUBLIC_LOCAL_STORAGE_URL=/uploads
# LOCAL_STORAGE_DIR=public/uploads

# ring_filebase (self-hosted / k8s) — write authority is k3s-or primary
# Prod (in-cluster):
# RINGBASE_API_URL=http://ring-filebase-api.ring-filebase.svc.cluster.local
# Local / CI (public write API on primary):
# RINGBASE_API_URL=https://filebase-api.ring-platform.org
# RINGBASE_API_TOKEN=...   # Secret — claim-shaped Bearer for ring-filebase-api
# RINGBASE_PUBLIC_URL=https://cdn.ring-platform.org
# NEXT_PUBLIC_RINGBASE_API_URL=   # optional fallback for API URL
# REFMAGIC_CDN_INTERNAL_URL=http://ring-filebase-cdn.ring-filebase.svc.cluster.local
    bash
    
# vercel | k8s | self-hosted
RING_DEPLOY_TARGET=self-hosted
NEXT_PUBLIC_RING_DEPLOY_TARGET=self-hosted

# Optional explicit WS URL (default: same host /api/tunnel/ws)
# NEXT_PUBLIC_TUNNEL_WS_URL=wss://ring-platform.org/api/tunnel/ws
    bash
    
FEATURE_DOCUMENTATION=true
FEATURE_NETWORKING=true
FEATURE_MESSAGING=true
FEATURE_WALLET=true
FEATURE_AI_MATCHER=true
FEATURE_WEB3_INTEGRATION=true
    bash
    
NEXT_PUBLIC_BASE_URL=https://ring-platform.org
NODE_ENV=development
    bash
    
# Email CRM (IMAP poll + admin UI)
# IMAP_HOST=mail.example.com
# IMAP_PORT=993
# ...

# CRON protection
# CRON_SECRET=generate-a-long-random-string

# Backup & compliance
# BACKUP_ENABLED=true
# BACKUP_SCHEDULE=0 2 * * *