---
title: "Базове налаштування"
description: "Швидкий запуск екземпляра Ring Platform з PostgreSQL, Auth.js v5 та мінімальною конфігурацією — для засновників та розробників"
locale: "uk"
---
# Базове налаштування

Цей посібник описує мінімальне локальне налаштування Ring Platform. Це найшвидший спосіб побачити працюючий екземпляр після клонування репозиторію.

  Node.js 20+, PostgreSQL 16 та Git. Повний перелік вимог описано у [Посібнику зі встановлення](/docs/en/getting-started/installation.md).

### For founders

## Що ви отримуєте

Працюючий екземпляр Ring Platform з:

- **PostgreSQL** як база даних додатку (режим `k8s-postgres-fcm`)
- **Auth.js v5** аутентифікація з Google OAuth входом
- **Керування сутностями** — створення та управління організаціями
- **Маркетплейс можливостей** — публікація та пошук оголошень
- **Сповіщення в реальному часі** через WebSocket тунель

Платформа працює на `http://localhost:3000`. Для базової локальної роботи не потрібні хмарні сервіси.

## Подальші кроки після налаштування

Після перевірки локального екземпляра див. [Локальне налаштування](/docs/en/development/local-setup.md) для white-label кастомізації, прапорців функцій та розширеної конфігурації. Для продакшн-розгортання див. [Конфігурація середовища](/docs/en/deployment/environment.md).

### For developers

## Покрокове налаштування

### Клонування та встановлення

```bash
git clone https://github.com/connectplatform/ring.git
cd ring
npm install
```

### Налаштування середовища

Скопіюйте шаблон і відредагуйте необхідні змінні:

```bash
cp env.local.template .env.local
```

Як мінімум, встановіть у `.env.local`:

```bash
# Database backend (required)
DB_BACKEND_MODE=k8s-postgres-fcm

# Auth.js secret (required)
AUTH_SECRET=your-secret

# Database connection (required for k8s-postgres-fcm)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ring_platform
DB_USER=ring_user
DB_PASSWORD=ring_password_2024

# Google OAuth (required for sign-in)
AUTH_GOOGLE_ID=your-client-id
AUTH_GOOGLE_SECRET=your-client-secret
```

  Auth.js v5 може згенерувати секрет автоматично при першому запуску. Або використовуйте `npx auth secret` для явної генерації. Підхід `openssl rand -hex 32` не потрібен.

Повна довідка змінних — у [Конфігурація середовища](/docs/en/deployment/environment.md). Для локальної розробки рекомендується `AUTH_TRUST_HOST=true`.

### Налаштування бази даних

Запустіть PostgreSQL та створіть базу даних:

```bash
docker run -d --name ring-postgres-dev \
  -e POSTGRES_USER=ring_user \
  -e POSTGRES_PASSWORD=ring_password_2024 \
  -e POSTGRES_DB=ring_platform \
  -p 5432:5432 \
  postgres:16-alpine
```

Застосуйте схему та міграції:

```bash
export DATABASE_URL="postgresql://ring_user:ring_password_2024@localhost:5432/ring_platform"
psql "$DATABASE_URL" -f data/schema.sql
psql "$DATABASE_URL" -f data/migrations/002_news_content_schema.sql
psql "$DATABASE_URL" -f data/migrations/003_news_kingdom_upgrade.sql
psql "$DATABASE_URL" -f data/migrations/004_payment_transactions.sql
```

Або використовуйте скрипт встановлення, який виконує налаштування бази даних:

```bash
./install.sh --quick
```

Див. [Встановлення > Налаштування PostgreSQL](/docs/en/getting-started/installation.md#postgresql-setup) для додаткових варіантів.

### Запуск сервера розробки

```bash
npm run dev
```

Користувацький `server.ts` запускає Next.js 16 з WebSocket тунелем на порту 3000.

### Перевірка

```bash
curl http://localhost:3000/api/health
```

Очікувана відповідь: `{"status":"ok","timestamp":"..."}`

Відкрийте `http://localhost:3000/login` для тестування входу через Google OAuth.

## Ключові файли

| Файл | Призначення |
|------|---------|
| `auth.ts` | Конфігурація Auth.js v5 — провайдери, колбеки, стратегія JWT сесії |
| `lib/database/DatabaseService.ts` | Уніфікована абстракція бази даних (PostgreSQL або Firestore) |
| `lib/firebase-admin.server.ts` | Firebase Admin SDK для FCM push (лише серверна частина) |
| `public/firebase-messaging-sw.js` | Сервіс-воркер з Firebase клієнтським SDK для push-сповіщень |
| `lib/tunnel/` | Транспорт реального часу через WebSocket |
| `data/schema.sql` | Схема PostgreSQL v4 |

  Ring Platform **не** має клієнтського файлу ініціалізації `lib/firebase.ts`. Клієнтський Firebase SDK завантажується виключно всередині сервіс-воркера (`public/firebase-messaging-sw.js`) через CDN `importScripts()`. Клієнтського об'єкта `firebaseConfig` не існує. Серверний Firebase Admin використовує `lib/firebase-admin.server.ts` з явними обліковими даними сервісного акаунта.

## Технологічний стек

| Компонент | Версія / Провайдер |
|-----------|--------------------|
| Framework | Next.js 16 App Router |
| UI | React 19 |
| Auth | Auth.js v5 (`auth()` / `useSession()`) |
| Database | PostgreSQL 16 + PostGIS (або Firestore через `DB_BACKEND_MODE=firebase-full`) |
| Push | Firebase Cloud Messaging (серверний Admin SDK, клієнтський сервіс-воркер) |
| Payments | WayForPay (серверна HMAC верифікація) |
| Locales | `next-intl`, підтримувані мови: en, uk, ru |

## Вирішення проблем

### "FETCH_FAILED" або помилки підключення до бази даних

Переконайтеся, що PostgreSQL запущено та облікові дані у `.env.local` збігаються:

```bash
psql "postgresql://ring_user:ring_password_2024@localhost:5432/ring_platform" -c "SELECT 1"
```

### Google OAuth не працює

1. Перевірте Google Cloud Console — додайте `http://localhost:3000` до Authorized JavaScript origins
2. Додайте `http://localhost:3000/api/auth/callback/google` до Authorized redirect URIs
3. Переконайтеся, що `AUTH_GOOGLE_ID` та `AUTH_GOOGLE_SECRET` вказано у `.env.local`

### Помилки секрету аутентифікації

Переконайтеся, що `AUTH_SECRET` встановлено у `.env.local`. Згенеруйте за допомогою:

```bash
npx auth secret
```

Потім скопіюйте результат у `AUTH_SECRET`.

## Подальші кроки

- [Посібник зі встановлення](/docs/en/getting-started/installation.md) — повне налаштування зі скриптом встановлення та розширеною конфігурацією бази даних
- [Локальне налаштування](/docs/en/development/local-setup.md) — white-label конфігурація, прапорці функцій та робочий процес розробки
- [Конфігурація середовища](/docs/en/deployment/environment.md) — довідка всіх змінних середовища
- [Розширені можливості](/docs/en/examples/advanced-features.md) — AI-матчер, верифікація, PaymentConductor та інше