---
title: "Розгортання"
description: "Огляд розгортання для Ring Platform — продакшн, попередній перегляд та саморозміщення."
locale: "uk"
---
# Посібник з розгортання

Ring Platform підтримує три цільові середовища розгортання: **k3s кластер** (продакшн), **Vercel** (попередній перегляд) та **Docker** (саморозміщення). Платформа використовує уніфіковану конфігурацію середовища; лише `DB_BACKEND_MODE` та `RING_DEPLOY_TARGET` змінюються залежно від цільового середовища.

> **Info**
> Ця сторінка є оглядом стратегії розгортання. Покрокові інструкції дивіться на відповідних сторінках: [Vercel](/docs/deployment/vercel.md), [Docker](/docs/deployment/docker.md), [Self-hosted](/docs/deployment/self-hosted.md) та [Конфігурація середовища](/docs/deployment/environment.md).

### For founders

## Вибір цільового середовища розгортання

### k3s кластер (продакшн — рекомендовано)

Основним продакшн цільовим середовищем є Kubernetes кластер (`5.161.246.54`). Усі клони імперії Ringdom працюють на цьому кластері.

- Повноцінний PostgreSQL з нативним WSS Tunnel (`TUNNEL_HUB_MODE=k8s-postgres`)
- Усі функції реального часу (обмін повідомленнями, спільна робота, живі сповіщення)
- WayForPay платіжні вебхуки
- Cron завдання для очищення імен користувачів, майнінгу рефкодів

### Vercel (попередній перегляд)

Vercel підходить для попереднього перегляду розгортань та швидкого прототипування. Безсерверні обробники маршрутів працюють на Vercel Edge — власний сервер (`server.ts`) не використовується, тому нативний WebSocket Tunnel недоступний. Tunnel переходить на SSE + довге опитування.

- Встановіть `RING_DEPLOY_TARGET=vercel` та `NEXT_PUBLIC_RING_DEPLOY_TARGET=vercel`
- Використовуйте `DB_BACKEND_MODE=firebase-full` (Firestore) або `k8s-postgres-fcm` (потребує доступного PostgreSQL хоста)
- WayForPay вебхуки потребують публічної кінцевої точки — функції Vercel обробляють це нативно

### Docker (саморозміщення)

Розгортання Docker задокументовано для самостійного розміщення спільнотою (OSS репозиторій). `Dockerfile` створює продакшн образ із власним сервером (`server.ts`) та підтримкою нативного WSS Tunnel. PostgreSQL працює як супутній контейнер або зовнішній сервіс.

- Повна паритетність функцій із k3s розгортанням
- PostgreSQL є обов'язковим (`DB_BACKEND_MODE=k8s-postgres-fcm`)
- Дивіться [Розгортання Docker](/docs/deployment/docker.md) та [Саморозміщення](/docs/deployment/self-hosted.md)

## Стратегія змінних середовища

Єдиним джерелом істини для всіх змінних середовища є `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 |

Повний довідник змінних дивіться в [Конфігурація середовища](/docs/deployment/environment.md).

> **Warning**
> Ніколи не комітьте реальні секрети в Git. Скопіюйте `env.local.template` у `.env.local` (входить до gitignore) і заповніть продакшн значеннями. На k3s інжектуйте секрети через Kubernetes secrets; на Vercel використовуйте змінні середовища панелі керування Vercel.

### For developers

## Передумови для всіх цільових середовищ

- Node.js 20+ (22 рекомендовано)
- npm або pnpm
- Екземпляр PostgreSQL (для режимів `k8s-postgres-fcm` та `supabase-fcm`)
- Firebase проєкт (необов'язково — лише якщо потрібні FCM push-сповіщення)

## Цільові середовища розгортання

### 1. k3s кластер (продакшн)

Продакшн k3s кластер використовує Kubernetes маніфести (не включені в публічний OSS репозиторій). Розгортання керується через Ring CLI та CI/CD конвеєр.

Необхідні змінні середовища для продакшну:

```bash
# База даних
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=
DB_SSL=true
DB_POOL_SIZE=20
DB_TIMEOUT=30000

# Auth.js
AUTH_SECRET=
AUTH_GOOGLE_ID=
AUTH_GOOGLE_SECRET=

# Tunnel
RING_DEPLOY_TARGET=k8s
NEXT_PUBLIC_RING_DEPLOY_TARGET=k8s
TUNNEL_HUB_MODE=k8s-postgres

# Firebase Admin (FCM лише — необов'язково)
AUTH_FIREBASE_PROJECT_ID=
AUTH_FIREBASE_CLIENT_EMAIL=
AUTH_FIREBASE_PRIVATE_KEY=""

# Платежі
WAYFORPAY_MERCHANT_ACCOUNT=
WAYFORPAY_SECRET_KEY=
```

У продакшні чутливі значення інжектуються через Kubernetes secrets під час виконання, а не вбудовуються в Docker образ.

### 2. Vercel

Розгортання Vercel використовує безсерверні обробники маршрутів. Власний сервер (`server.ts`) не використовується — Tunnel працює в режимі SSE + довге опитування.

**vercel.json** (платформа постачається з цим файлом):

```json
{
  "crons": [
    {
      "path": "/api/cron/cleanup-usernames",
      "schedule": "*/5 * * * *"
    }
  ]
}
```

> **Tip**
> Встановіть `RING_DEPLOY_TARGET=vercel` та `NEXT_PUBLIC_RING_DEPLOY_TARGET=vercel` у панелі керування Vercel. Без цього Tunnel може намагатися ініціалізувати нативний WebSocket, який недоступний у безсерверному середовищі.

Кроки:

1. Запуште репозиторій на GitHub
2. Імпортуйте проєкт у Vercel
3. Встановіть змінні середовища в панелі керування Vercel (усі `DB_*`, `AUTH_*`, `NEXT_PUBLIC_*`, `WAYFORPAY_*` тощо)
4. Розгорніть основну гілку

Деталі дивіться в [Розгортання Vercel](/docs/deployment/vercel.md).

### 3. Docker (саморозміщення)

`Dockerfile` створює багатостадійний продакшн образ із власним сервером та нативним WSS Tunnel. Він використовує `dumb-init` як точку входу та виконує перевірку стану на `/api/health`.

Збірка:

```bash
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 .
```

> **Warning**
> Лише безпечні для часу збірки змінні (`NEXT_PUBLIC_*`, `DB_BACKEND_MODE`) слід передавати як build args. Чутливі секрети (`AUTH_GOOGLE_SECRET`, `DB_PASSWORD`, `WAYFORPAY_SECRET_KEY`) інжектуються під час виконання через змінні середовища або менеджери секретів.

Запуск:

```bash
docker run -d \
  -p 3000:3000 \
  -e AUTH_SECRET= \
  -e AUTH_GOOGLE_ID= \
  -e AUTH_GOOGLE_SECRET= \
  -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= \
  -e DB_SSL=true \
  -e RING_DEPLOY_TARGET=self-hosted \
  -e NEXT_PUBLIC_RING_DEPLOY_TARGET=self-hosted \
  ring-platform
```

Дивіться [Розгортання Docker](/docs/deployment/docker.md) для конфігурації docker-compose та налаштування PostGIS, а також [Саморозміщення](/docs/deployment/self-hosted.md) для 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.

Глибоке порівняння дивіться в [Режими бекенду та бази даних](/docs/architecture/backend-modes-and-databases.md).

```bash
# Перевірка з'єднання з базою даних (будь-який режим)
# Використовує getDatabaseService() — НЕ Firebase client SDK
# lib/firebase.ts не існує в цій кодовій базі
```

> **Info**
> 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? })`.

## Усунення неполадок

### Збій збірки з помилками TypeScript

Очистіть кеш та повторіть спробу:

```bash
rm -rf .next node_modules
npm install
npm run type-check
npm run build
```

### Сесія Auth.js не працює

Переконайтеся, що `AUTH_SECRET` встановлено та є однаковим у всіх розгортаннях. Auth.js v5 використовує `AUTH_SECRET` (не `NEXTAUTH_SECRET`). Змінні Google OAuth: `AUTH_GOOGLE_ID` та `AUTH_GOOGLE_SECRET` (не `GOOGLE_CLIENT_ID`).

### Відмовлено у з'єднанні з базою даних

Перевірте, чи PostgreSQL доступний з цільового середовища розгортання:

```bash
# З k3s pod
kubectl exec deploy/ring-platform -- wget -qO- http://postgres:5432

# З Docker
docker exec ring-platform nc -zv postgres.example.com 5432
```

Переконайтеся, що `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER` та `DB_PASSWORD` відповідають вашій конфігурації PostgreSQL.

### Tunnel / WebSocket не підключається

Переконайтеся, що `RING_DEPLOY_TARGET` та `NEXT_PUBLIC_RING_DEPLOY_TARGET` встановлено. На Vercel нативний WebSocket недоступний — Tunnel автоматично переходить на SSE + довге опитування. На k3s або Docker переконайтеся, що `TUNNEL_HUB_MODE=k8s-postgres` встановлено.

## Пов'язана документація