Завантаження документації...
Підготовка контенту платформи Ring
Концепции, ценность и типичные сценарии клонирования — меньше кода.
Концепции, ценность и типичные сценарии клонирования — меньше кода.
Підготовка контенту платформи Ring
Підготовка контенту платформи Ring
Підготовка контенту платформи Ring
Ring Platform поддерживает три целевых окружения развёртывания: k3s-кластер (production), Vercel (preview) и Docker (self-hosted). Платформа использует унифицированную конфигурацию окружения; только DB_BACKEND_MODE и RING_DEPLOY_TARGET изменяются в зависимости от целевого окружения.
Эта страница представляет обзор стратегии развёртывания. Пошаговые инструкции смотрите на соответствующих страницах: Vercel, Docker, Self-hosted и Конфигурация окружения.
Основное production-окружение — Kubernetes-кластер (5.161.246.54). Все клоны империи Ringdom работают на этом кластере.
TUNNEL_HUB_MODE=k8s-postgres)Vercel подходит для preview-развёртываний и быстрого прототипирования. Бессерверные обработчики маршрутов работают на 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 создаёт production-образ с собственным сервером (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) и заполните production-значения. На k3s инжектируйте секреты через Kubernetes secrets; на Vercel используйте переменные окружения панели управления Vercel.
Ring Platform поддерживает три целевых окружения развёртывания: k3s-кластер (production), Vercel (preview) и Docker (self-hosted). Платформа использует унифицированную конфигурацию окружения; только DB_BACKEND_MODE и RING_DEPLOY_TARGET изменяются в зависимости от целевого окружения.
Эта страница представляет обзор стратегии развёртывания. Пошаговые инструкции смотрите на соответствующих страницах: Vercel, Docker, Self-hosted и Конфигурация окружения.
Основное production-окружение — Kubernetes-кластер (5.161.246.54). Все клоны империи Ringdom работают на этом кластере.
TUNNEL_HUB_MODE=k8s-postgres)Vercel подходит для preview-развёртываний и быстрого прототипирования. Бессерверные обработчики маршрутов работают на 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 создаёт production-образ с собственным сервером (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) и заполните production-значения. На k3s инжектируйте секреты через Kubernetes secrets; на Vercel используйте переменные окружения панели управления Vercel.
Ring Platform поддерживает три целевых окружения развёртывания: k3s-кластер (production), Vercel (preview) и Docker (self-hosted). Платформа использует унифицированную конфигурацию окружения; только DB_BACKEND_MODE и RING_DEPLOY_TARGET изменяются в зависимости от целевого окружения.
Эта страница представляет обзор стратегии развёртывания. Пошаговые инструкции смотрите на соответствующих страницах: Vercel, Docker, Self-hosted и Конфигурация окружения.
Основное production-окружение — Kubernetes-кластер (5.161.246.54). Все клоны империи Ringdom работают на этом кластере.
TUNNEL_HUB_MODE=k8s-postgres)Vercel подходит для preview-развёртываний и быстрого прототипирования. Бессерверные обработчики маршрутов работают на 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 создаёт production-образ с собственным сервером (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) и заполните production-значения. На k3s инжектируйте секреты через Kubernetes secrets; на Vercel используйте переменные окружения панели управления Vercel.
Dockerfile создаёт многостадийный production-образ с собственным сервером и нативным 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. Рекомендуется для production и локальной разработки.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 создаёт многостадийный production-образ с собственным сервером и нативным 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. Рекомендуется для production и локальной разработки.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 создаёт многостадийный production-образ с собственным сервером и нативным 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. Рекомендуется для production и локальной разработки.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