Завантаження документації...
Підготовка контенту платформи Ring
Концепції, цінність і типові сценарії
Концепції, цінність і типові сценарії
Підготовка контенту платформи Ring
Підготовка контенту платформи Ring
Підготовка контенту платформи Ring
Ring Platform підтримує три цільові середовища розгортання: k3s кластер (продакшн), Vercel (попередній перегляд) та Docker (саморозміщення). Платформа використовує уніфіковану конфігурацію середовища; лише DB_BACKEND_MODE та RING_DEPLOY_TARGET змінюються залежно від цільового середовища.
Ця сторінка є оглядом стратегії розгортання. Покрокові інструкції дивіться на відповідних сторінках: Vercel, Docker, Self-hosted та Конфігурація середовища.
Основним продакшн цільовим середовищем є Kubernetes кластер (5.161.246.54). Усі клони імперії Ringdom працюють на цьому кластері.
TUNNEL_HUB_MODE=k8s-postgres)Vercel підходить для попереднього перегляду розгортань та швидкого прототипування. Безсерверні обробники маршрутів працюють на Vercel Edge — власний сервер (server.ts) не використовується, тому нативний WebSocket Tunnel недоступний. Tunnel переходить на SSE + довге опитування.
RING_DEPLOY_TARGET=vercel та NEXT_PUBLIC_RING_DEPLOY_TARGET=vercelDB_BACKEND_MODE=firebase-full (Firestore) або k8s-postgres-fcm (потребує доступного PostgreSQL хоста)Розгортання Docker задокументовано для самостійного розміщення спільнотою (OSS репозиторій). Dockerfile створює продакшн образ із власним сервером (server.ts) та підтримкою нативного WSS Tunnel. PostgreSQL працює як супутній контейнер або зовнішній сервіс.
DB_BACKEND_MODE=k8s-postgres-fcm)Єдиним джерелом істини для всіх змінних середовища є env.local.template у корені репозиторію. Ключові рішення:
| Змінна | Призначення |
|---|---|
DB_BACKEND_MODE | Адаптер бази даних: k8s-postgres-fcm (рекомендовано), firebase-full або supabase-fcm |
RING_DEPLOY_TARGET | Режим Tunnel та середовища виконання: k8s, vercel або self-hosted |
AUTH_SECRET | Шифрування сесій Auth.js (згенерувати за допомогою openssl rand -base64 32) |
AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET | Облікові дані Google OAuth |
Повний довідник змінних дивіться в Конфігурація середовища.
Ніколи не комітьте реальні секрети в Git. Скопіюйте env.local.template у .env.local (входить до gitignore) і заповніть продакшн значеннями. На k3s інжектуйте секрети через Kubernetes secrets; на Vercel використовуйте змінні середовища панелі керування Vercel.
Ring Platform підтримує три цільові середовища розгортання: k3s кластер (продакшн), Vercel (попередній перегляд) та Docker (саморозміщення). Платформа використовує уніфіковану конфігурацію середовища; лише DB_BACKEND_MODE та RING_DEPLOY_TARGET змінюються залежно від цільового середовища.
Ця сторінка є оглядом стратегії розгортання. Покрокові інструкції дивіться на відповідних сторінках: Vercel, Docker, Self-hosted та Конфігурація середовища.
Основним продакшн цільовим середовищем є Kubernetes кластер (5.161.246.54). Усі клони імперії Ringdom працюють на цьому кластері.
TUNNEL_HUB_MODE=k8s-postgres)Vercel підходить для попереднього перегляду розгортань та швидкого прототипування. Безсерверні обробники маршрутів працюють на Vercel Edge — власний сервер (server.ts) не використовується, тому нативний WebSocket Tunnel недоступний. Tunnel переходить на SSE + довге опитування.
RING_DEPLOY_TARGET=vercel та NEXT_PUBLIC_RING_DEPLOY_TARGET=vercelDB_BACKEND_MODE=firebase-full (Firestore) або k8s-postgres-fcm (потребує доступного PostgreSQL хоста)Розгортання Docker задокументовано для самостійного розміщення спільнотою (OSS репозиторій). Dockerfile створює продакшн образ із власним сервером (server.ts) та підтримкою нативного WSS Tunnel. PostgreSQL працює як супутній контейнер або зовнішній сервіс.
DB_BACKEND_MODE=k8s-postgres-fcm)Єдиним джерелом істини для всіх змінних середовища є env.local.template у корені репозиторію. Ключові рішення:
| Змінна | Призначення |
|---|---|
DB_BACKEND_MODE | Адаптер бази даних: k8s-postgres-fcm (рекомендовано), firebase-full або supabase-fcm |
RING_DEPLOY_TARGET | Режим Tunnel та середовища виконання: k8s, vercel або self-hosted |
AUTH_SECRET | Шифрування сесій Auth.js (згенерувати за допомогою openssl rand -base64 32) |
AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET | Облікові дані Google OAuth |
Повний довідник змінних дивіться в Конфігурація середовища.
Ніколи не комітьте реальні секрети в Git. Скопіюйте env.local.template у .env.local (входить до gitignore) і заповніть продакшн значеннями. На k3s інжектуйте секрети через Kubernetes secrets; на Vercel використовуйте змінні середовища панелі керування Vercel.
Ring Platform підтримує три цільові середовища розгортання: k3s кластер (продакшн), Vercel (попередній перегляд) та Docker (саморозміщення). Платформа використовує уніфіковану конфігурацію середовища; лише DB_BACKEND_MODE та RING_DEPLOY_TARGET змінюються залежно від цільового середовища.
Ця сторінка є оглядом стратегії розгортання. Покрокові інструкції дивіться на відповідних сторінках: Vercel, Docker, Self-hosted та Конфігурація середовища.
Основним продакшн цільовим середовищем є Kubernetes кластер (5.161.246.54). Усі клони імперії Ringdom працюють на цьому кластері.
TUNNEL_HUB_MODE=k8s-postgres)Vercel підходить для попереднього перегляду розгортань та швидкого прототипування. Безсерверні обробники маршрутів працюють на Vercel Edge — власний сервер (server.ts) не використовується, тому нативний WebSocket Tunnel недоступний. Tunnel переходить на SSE + довге опитування.
RING_DEPLOY_TARGET=vercel та NEXT_PUBLIC_RING_DEPLOY_TARGET=vercelDB_BACKEND_MODE=firebase-full (Firestore) або k8s-postgres-fcm (потребує доступного PostgreSQL хоста)Розгортання Docker задокументовано для самостійного розміщення спільнотою (OSS репозиторій). Dockerfile створює продакшн образ із власним сервером (server.ts) та підтримкою нативного WSS Tunnel. PostgreSQL працює як супутній контейнер або зовнішній сервіс.
DB_BACKEND_MODE=k8s-postgres-fcm)Єдиним джерелом істини для всіх змінних середовища є env.local.template у корені репозиторію. Ключові рішення:
| Змінна | Призначення |
|---|---|
DB_BACKEND_MODE | Адаптер бази даних: k8s-postgres-fcm (рекомендовано), firebase-full або supabase-fcm |
RING_DEPLOY_TARGET | Режим Tunnel та середовища виконання: k8s, vercel або self-hosted |
AUTH_SECRET | Шифрування сесій Auth.js (згенерувати за допомогою openssl rand -base64 32) |
AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET | Облікові дані Google OAuth |
Повний довідник змінних дивіться в Конфігурація середовища.
Ніколи не комітьте реальні секрети в Git. Скопіюйте env.local.template у .env.local (входить до gitignore) і заповніть продакшн значеннями. На k3s інжектуйте секрети через Kubernetes secrets; на Vercel використовуйте змінні середовища панелі керування Vercel.
Dockerfile створює багатостадійний продакшн образ із власним сервером та нативним WSS Tunnel. Він використовує dumb-init як точку входу та виконує перевірку стану на /api/health.
Збірка:
Лише безпечні для часу збірки змінні (NEXT_PUBLIC_*, DB_BACKEND_MODE) слід передавати як build args. Чутливі секрети (AUTH_GOOGLE_SECRET, DB_PASSWORD, WAYFORPAY_SECRET_KEY) інжектуються під час виконання через змінні середовища або менеджери секретів.
Запуск:
Дивіться Розгортання Docker для конфігурації docker-compose та налаштування PostGIS, а також Саморозміщення для OSS налаштування спільноти за допомогою install.sh.
Платформа використовує єдиний рівень абстракції бази даних через getDatabaseService() (див. lib/database/DatabaseService.ts). Активний адаптер обирається за допомогою DB_BACKEND_MODE:
k8s-postgres-fcm — PostgreSQL для всіх CRUD, Firebase Admin SDK лише для FCM push. Рекомендовано для продакшну та локальної розробки.firebase-full — Firestore (Firebase) для всіх CRUD. Найшвидше налаштування для прототипування та Vercel.supabase-fcm — Supabase PostgreSQL для бази даних, Firebase Admin SDK лише для FCM push.Глибоке порівняння дивіться в Режими бекенду та бази даних.
Firestore client SDK (db.collection(...).doc(...).get()) не використовується в цій платформі. Увесь доступ до бази даних відбувається через getDatabaseService() з методами findById(collection, id), create(collection, data), update(collection, id, data), delete(collection, id) та query({ collection, filters?, orderBy?, pagination? }).
Очистіть кеш та повторіть спробу:
Переконайтеся, що AUTH_SECRET встановлено та є однаковим у всіх розгортаннях. Auth.js v5 використовує AUTH_SECRET (не NEXTAUTH_SECRET). Змінні Google OAuth: AUTH_GOOGLE_ID та AUTH_GOOGLE_SECRET (не GOOGLE_CLIENT_ID).
Перевірте, чи PostgreSQL доступний з цільового середовища розгортання:
Переконайтеся, що DB_HOST, DB_PORT, DB_NAME, DB_USER та DB_PASSWORD відповідають вашій конфігурації PostgreSQL.
Переконайтеся, що RING_DEPLOY_TARGET та NEXT_PUBLIC_RING_DEPLOY_TARGET встановлено. На Vercel нативний WebSocket недоступний — Tunnel автоматично переходить на SSE + довге опитування. На k3s або Docker переконайтеся, що TUNNEL_HUB_MODE=k8s-postgres встановлено.
# База даних
DB_BACKEND_MODE=k8s-postgres-fcm
DB_HOST=postgres.ring-platform-org.svc.cluster.local
DB_PORT=5432
DB_NAME=ring_platform
DB_USER=ring_user
DB_PASSWORD=<from-k8s-secret>
DB_SSL=true
DB_POOL_SIZE=20
DB_TIMEOUT=30000
# Auth.js
AUTH_SECRET=<from-k8s-secret>
AUTH_GOOGLE_ID=<from-k8s-secret>
AUTH_GOOGLE_SECRET=<from-k8s-secret>
# Tunnel
RING_DEPLOY_TARGET=k8s
NEXT_PUBLIC_RING_DEPLOY_TARGET=k8s
TUNNEL_HUB_MODE=k8s-postgres
# Firebase Admin (FCM лише — необов'язково)
AUTH_FIREBASE_PROJECT_ID=<your-project-id>
AUTH_FIREBASE_CLIENT_EMAIL=<your-service-account-email>
AUTH_FIREBASE_PRIVATE_KEY="<your-private-key>"
# Платежі
WAYFORPAY_MERCHANT_ACCOUNT=<from-k8s-secret>
WAYFORPAY_SECRET_KEY=<from-k8s-secret>
{
"crons": [
{
"path": "/api/cron/cleanup-usernames",
"schedule": "*/5 * * * *"
}
]
}Dockerfile створює багатостадійний продакшн образ із власним сервером та нативним WSS Tunnel. Він використовує dumb-init як точку входу та виконує перевірку стану на /api/health.
Збірка:
Лише безпечні для часу збірки змінні (NEXT_PUBLIC_*, DB_BACKEND_MODE) слід передавати як build args. Чутливі секрети (AUTH_GOOGLE_SECRET, DB_PASSWORD, WAYFORPAY_SECRET_KEY) інжектуються під час виконання через змінні середовища або менеджери секретів.
Запуск:
Дивіться Розгортання Docker для конфігурації docker-compose та налаштування PostGIS, а також Саморозміщення для OSS налаштування спільноти за допомогою install.sh.
Платформа використовує єдиний рівень абстракції бази даних через getDatabaseService() (див. lib/database/DatabaseService.ts). Активний адаптер обирається за допомогою DB_BACKEND_MODE:
k8s-postgres-fcm — PostgreSQL для всіх CRUD, Firebase Admin SDK лише для FCM push. Рекомендовано для продакшну та локальної розробки.firebase-full — Firestore (Firebase) для всіх CRUD. Найшвидше налаштування для прототипування та Vercel.supabase-fcm — Supabase PostgreSQL для бази даних, Firebase Admin SDK лише для FCM push.Глибоке порівняння дивіться в Режими бекенду та бази даних.
Firestore client SDK (db.collection(...).doc(...).get()) не використовується в цій платформі. Увесь доступ до бази даних відбувається через getDatabaseService() з методами findById(collection, id), create(collection, data), update(collection, id, data), delete(collection, id) та query({ collection, filters?, orderBy?, pagination? }).
Очистіть кеш та повторіть спробу:
Переконайтеся, що AUTH_SECRET встановлено та є однаковим у всіх розгортаннях. Auth.js v5 використовує AUTH_SECRET (не NEXTAUTH_SECRET). Змінні Google OAuth: AUTH_GOOGLE_ID та AUTH_GOOGLE_SECRET (не GOOGLE_CLIENT_ID).
Перевірте, чи PostgreSQL доступний з цільового середовища розгортання:
Переконайтеся, що DB_HOST, DB_PORT, DB_NAME, DB_USER та DB_PASSWORD відповідають вашій конфігурації PostgreSQL.
Переконайтеся, що RING_DEPLOY_TARGET та NEXT_PUBLIC_RING_DEPLOY_TARGET встановлено. На Vercel нативний WebSocket недоступний — Tunnel автоматично переходить на SSE + довге опитування. На k3s або Docker переконайтеся, що TUNNEL_HUB_MODE=k8s-postgres встановлено.
# База даних
DB_BACKEND_MODE=k8s-postgres-fcm
DB_HOST=postgres.ring-platform-org.svc.cluster.local
DB_PORT=5432
DB_NAME=ring_platform
DB_USER=ring_user
DB_PASSWORD=<from-k8s-secret>
DB_SSL=true
DB_POOL_SIZE=20
DB_TIMEOUT=30000
# Auth.js
AUTH_SECRET=<from-k8s-secret>
AUTH_GOOGLE_ID=<from-k8s-secret>
AUTH_GOOGLE_SECRET=<from-k8s-secret>
# Tunnel
RING_DEPLOY_TARGET=k8s
NEXT_PUBLIC_RING_DEPLOY_TARGET=k8s
TUNNEL_HUB_MODE=k8s-postgres
# Firebase Admin (FCM лише — необов'язково)
AUTH_FIREBASE_PROJECT_ID=<your-project-id>
AUTH_FIREBASE_CLIENT_EMAIL=<your-service-account-email>
AUTH_FIREBASE_PRIVATE_KEY="<your-private-key>"
# Платежі
WAYFORPAY_MERCHANT_ACCOUNT=<from-k8s-secret>
WAYFORPAY_SECRET_KEY=<from-k8s-secret>
{
"crons": [
{
"path": "/api/cron/cleanup-usernames",
"schedule": "*/5 * * * *"
}
]
}Dockerfile створює багатостадійний продакшн образ із власним сервером та нативним WSS Tunnel. Він використовує dumb-init як точку входу та виконує перевірку стану на /api/health.
Збірка:
Лише безпечні для часу збірки змінні (NEXT_PUBLIC_*, DB_BACKEND_MODE) слід передавати як build args. Чутливі секрети (AUTH_GOOGLE_SECRET, DB_PASSWORD, WAYFORPAY_SECRET_KEY) інжектуються під час виконання через змінні середовища або менеджери секретів.
Запуск:
Дивіться Розгортання Docker для конфігурації docker-compose та налаштування PostGIS, а також Саморозміщення для OSS налаштування спільноти за допомогою install.sh.
Платформа використовує єдиний рівень абстракції бази даних через getDatabaseService() (див. lib/database/DatabaseService.ts). Активний адаптер обирається за допомогою DB_BACKEND_MODE:
k8s-postgres-fcm — PostgreSQL для всіх CRUD, Firebase Admin SDK лише для FCM push. Рекомендовано для продакшну та локальної розробки.firebase-full — Firestore (Firebase) для всіх CRUD. Найшвидше налаштування для прототипування та Vercel.supabase-fcm — Supabase PostgreSQL для бази даних, Firebase Admin SDK лише для FCM push.Глибоке порівняння дивіться в Режими бекенду та бази даних.
Firestore client SDK (db.collection(...).doc(...).get()) не використовується в цій платформі. Увесь доступ до бази даних відбувається через getDatabaseService() з методами findById(collection, id), create(collection, data), update(collection, id, data), delete(collection, id) та query({ collection, filters?, orderBy?, pagination? }).
Очистіть кеш та повторіть спробу:
Переконайтеся, що AUTH_SECRET встановлено та є однаковим у всіх розгортаннях. Auth.js v5 використовує AUTH_SECRET (не NEXTAUTH_SECRET). Змінні Google OAuth: AUTH_GOOGLE_ID та AUTH_GOOGLE_SECRET (не GOOGLE_CLIENT_ID).
Перевірте, чи PostgreSQL доступний з цільового середовища розгортання:
Переконайтеся, що DB_HOST, DB_PORT, DB_NAME, DB_USER та DB_PASSWORD відповідають вашій конфігурації PostgreSQL.
Переконайтеся, що RING_DEPLOY_TARGET та NEXT_PUBLIC_RING_DEPLOY_TARGET встановлено. На Vercel нативний WebSocket недоступний — Tunnel автоматично переходить на SSE + довге опитування. На k3s або Docker переконайтеся, що TUNNEL_HUB_MODE=k8s-postgres встановлено.
# База даних
DB_BACKEND_MODE=k8s-postgres-fcm
DB_HOST=postgres.ring-platform-org.svc.cluster.local
DB_PORT=5432
DB_NAME=ring_platform
DB_USER=ring_user
DB_PASSWORD=<from-k8s-secret>
DB_SSL=true
DB_POOL_SIZE=20
DB_TIMEOUT=30000
# Auth.js
AUTH_SECRET=<from-k8s-secret>
AUTH_GOOGLE_ID=<from-k8s-secret>
AUTH_GOOGLE_SECRET=<from-k8s-secret>
# Tunnel
RING_DEPLOY_TARGET=k8s
NEXT_PUBLIC_RING_DEPLOY_TARGET=k8s
TUNNEL_HUB_MODE=k8s-postgres
# Firebase Admin (FCM лише — необов'язково)
AUTH_FIREBASE_PROJECT_ID=<your-project-id>
AUTH_FIREBASE_CLIENT_EMAIL=<your-service-account-email>
AUTH_FIREBASE_PRIVATE_KEY="<your-private-key>"
# Платежі
WAYFORPAY_MERCHANT_ACCOUNT=<from-k8s-secret>
WAYFORPAY_SECRET_KEY=<from-k8s-secret>
{
"crons": [
{
"path": "/api/cron/cleanup-usernames",
"schedule": "*/5 * * * *"
}
]
}
docker build \
--platform linux/amd64 \
--build-arg AUTH_SECRET="your-auth-secret" \
--build-arg DB_BACKEND_MODE=k8s-postgres-fcm \
--build-arg DB_HOST=postgres.example.com \
--build-arg DB_PORT=5432 \
--build-arg DB_NAME=ring_platform \
--build-arg DB_USER=ring_user \
--build-arg NEXT_PUBLIC_APP_URL=https://your-domain.com \
--build-arg NEXT_PUBLIC_API_URL=https://your-domain.com \
-t ring-platform .
docker run -d \
-p 3000:3000 \
-e AUTH_SECRET=<from-secret-store> \
-e AUTH_GOOGLE_ID=<from-secret-store> \
-e AUTH_GOOGLE_SECRET=<from-secret-store> \
-e DB_BACKEND_MODE=k8s-postgres-fcm \
-e DB_HOST=postgres.example.com \
-e DB_PORT=5432 \
-e DB_NAME=ring_platform \
-e DB_USER=ring_user \
-e DB_PASSWORD=<from-secret-store> \
-e DB_SSL=true \
-e RING_DEPLOY_TARGET=self-hosted \
-e NEXT_PUBLIC_RING_DEPLOY_TARGET=self-hosted \
ring-platform
# Перевірка з'єднання з базою даних (будь-який режим)
# Використовує getDatabaseService() — НЕ Firebase client SDK
# lib/firebase.ts не існує в цій кодовій базі
rm -rf .next node_modules
npm install
npm run type-check
npm run build
# З k3s pod
kubectl exec deploy/ring-platform -- wget -qO- http://postgres:5432
# З Docker
docker exec ring-platform nc -zv postgres.example.com 5432
docker build \
--platform linux/amd64 \
--build-arg AUTH_SECRET="your-auth-secret" \
--build-arg DB_BACKEND_MODE=k8s-postgres-fcm \
--build-arg DB_HOST=postgres.example.com \
--build-arg DB_PORT=5432 \
--build-arg DB_NAME=ring_platform \
--build-arg DB_USER=ring_user \
--build-arg NEXT_PUBLIC_APP_URL=https://your-domain.com \
--build-arg NEXT_PUBLIC_API_URL=https://your-domain.com \
-t ring-platform .
docker run -d \
-p 3000:3000 \
-e AUTH_SECRET=<from-secret-store> \
-e AUTH_GOOGLE_ID=<from-secret-store> \
-e AUTH_GOOGLE_SECRET=<from-secret-store> \
-e DB_BACKEND_MODE=k8s-postgres-fcm \
-e DB_HOST=postgres.example.com \
-e DB_PORT=5432 \
-e DB_NAME=ring_platform \
-e DB_USER=ring_user \
-e DB_PASSWORD=<from-secret-store> \
-e DB_SSL=true \
-e RING_DEPLOY_TARGET=self-hosted \
-e NEXT_PUBLIC_RING_DEPLOY_TARGET=self-hosted \
ring-platform
# Перевірка з'єднання з базою даних (будь-який режим)
# Використовує getDatabaseService() — НЕ Firebase client SDK
# lib/firebase.ts не існує в цій кодовій базі
rm -rf .next node_modules
npm install
npm run type-check
npm run build
# З k3s pod
kubectl exec deploy/ring-platform -- wget -qO- http://postgres:5432
# З Docker
docker exec ring-platform nc -zv postgres.example.com 5432
docker build \
--platform linux/amd64 \
--build-arg AUTH_SECRET="your-auth-secret" \
--build-arg DB_BACKEND_MODE=k8s-postgres-fcm \
--build-arg DB_HOST=postgres.example.com \
--build-arg DB_PORT=5432 \
--build-arg DB_NAME=ring_platform \
--build-arg DB_USER=ring_user \
--build-arg NEXT_PUBLIC_APP_URL=https://your-domain.com \
--build-arg NEXT_PUBLIC_API_URL=https://your-domain.com \
-t ring-platform .
docker run -d \
-p 3000:3000 \
-e AUTH_SECRET=<from-secret-store> \
-e AUTH_GOOGLE_ID=<from-secret-store> \
-e AUTH_GOOGLE_SECRET=<from-secret-store> \
-e DB_BACKEND_MODE=k8s-postgres-fcm \
-e DB_HOST=postgres.example.com \
-e DB_PORT=5432 \
-e DB_NAME=ring_platform \
-e DB_USER=ring_user \
-e DB_PASSWORD=<from-secret-store> \
-e DB_SSL=true \
-e RING_DEPLOY_TARGET=self-hosted \
-e NEXT_PUBLIC_RING_DEPLOY_TARGET=self-hosted \
ring-platform
# Перевірка з'єднання з базою даних (будь-який режим)
# Використовує getDatabaseService() — НЕ Firebase client SDK
# lib/firebase.ts не існує в цій кодовій базі
rm -rf .next node_modules
npm install
npm run type-check
npm run build
# З k3s pod
kubectl exec deploy/ring-platform -- wget -qO- http://postgres:5432
# З Docker
docker exec ring-platform nc -zv postgres.example.com 5432