Налаштування локальної розробки

Посібник з налаштування Ring Platform для локальної розробки.

Що вам знадобиться

Node.js 22, pnpm/npm та Git встановлені на вашому комп'ютері
PostgreSQL 16 + PostGIS (через Homebrew, Docker або нативне встановлення)
Редактор коду (рекомендується VS Code)

Огляд налаштування

Клонуйте репозиторій
Встановіть залежності
Налаштуйте змінні середовища з env.local.template
Налаштуйте PostgreSQL та виконайте міграції
Запустіть сервер розробки

Передумови

Необхідне програмне забезпечення

Node.js 22 — Завантажити з nodejs.org
npm 10+ або pnpm 9+ — Менеджер пакетів
Git — Контроль версій
PostgreSQL 16 з розширенням PostGIS — Дивіться розділ налаштування бази даних
VS Code — Рекомендоване IDE

Додаткові інструменти

Docker — Для контейнеризованого PostgreSQL (альтернатива встановленню через Homebrew)
Postman або Bruno — Тестування API

Встановлення

1. Клонування репозиторію

2. Встановлення залежностей

3. Конфігурація середовища

Скопіюйте шаблон середовища:

Змінна DB_BACKEND_MODE є обов'язковою — платформа не запуститься без неї. Для локальної розробки з PostgreSQL встановіть k8s-postgres-fcm.

Налаштуйте ваш файл .env.local з такими обов'язковими змінними:

Згенеруйте AUTH_SECRET за допомогою: npx @better-auth/cli secret

Повний перелік підтримуваних змінних та їх опис дивіться в Конфігурація середовища.

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

Варіант A: Docker (рекомендовано для локальної розробки)

Варіант B: Homebrew (macOS)

Для локальної розробки з декількома клонами використовуйте скрипт ініціалізації infrastructure/postgres/bootstrap-brew-dev.sh. Дивіться infrastructure/postgres/MIGRATION-KINGDOM-MATRIX.md.

Виконання міграцій

Файли міграцій знаходяться в директорії data/. Виконавець міграцій читає DB_BACKEND_MODE для вибору правильного адаптера. Для локального PostgreSQL (k8s-postgres-fcm) він застосовує SQL міграції з data/schema.sql та data/migrations/.

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

Застосунок буде доступний за адресами:

Фронтенд: http://localhost:3000
API маршрути: http://localhost:3000/api/*
Перевірка стану: http://localhost:3000/api/health

Інструменти розробки

Гаряче перезавантаження

Сервер розробки Next.js підтримує гаряче перезавантаження для:

React компонентів та Server Components
API маршрутів
Змін Tailwind CSS
Файлів локалізації (потребує перезапуску сервера для нових ключів)

Перевірка типів

Лінтинг

Структура проєкту

Тестування

Поширені проблеми

Порт 3000 вже використовується

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

Переконайтеся, що PostgreSQL працює: pg_isready
Перевірте значення .env.local для DB_HOST, DB_PORT, DB_USER, DB_PASSWORD
Переконайтеся, що база даних ring_platform існує
Підтвердьте, що DB_BACKEND_MODE встановлено на k8s-postgres-fcm

Помилки OAuth Auth.js

Переконайтеся, що AUTH_GOOGLE_ID та AUTH_GOOGLE_SECRET вказано в .env.local
Перевірте, що http://localhost:3000 є в дозволених URI перенаправлення консолі Google OAuth
Переконайтеся, що AUTH_SECRET встановлено та є однаковим
Формат URL зворотного виклику: http://localhost:3000/api/auth/callback/google

Firebase FCM не працює (необов'язково)

Firebase використовується лише для push-сповіщень (FCM) у режимі k8s-postgres-fcm. Застосунок працюватиме без налаштованого Firebase, але push-сповіщення не будуть доставлятися. Налаштуйте змінні AUTH_FIREBASE_* та NEXT_PUBLIC_FIREBASE_* за потреби.

Наступні кроки

Конфігурація середовища — Повний довідник змінних середовища
Розгортання — Розгортання в продакшн
Посібник з встановлення — Продакшн встановлення
Структура коду — Організація кодової бази
Робочий процес розробки — Git робочий процес та найкращі практики
Тестування — Написання та запуск тестів

Потрібна допомога? Перевірте посібник з усунення неполадок або приєднуйтесь до нашої Discord спільноти.

Налаштування локальної розробки

Посібник з налаштування Ring Platform для локальної розробки.

Що вам знадобиться

Node.js 22, pnpm/npm та Git встановлені на вашому комп'ютері
PostgreSQL 16 + PostGIS (через Homebrew, Docker або нативне встановлення)
Редактор коду (рекомендується VS Code)

Огляд налаштування

Клонуйте репозиторій
Встановіть залежності
Налаштуйте змінні середовища з env.local.template
Налаштуйте PostgreSQL та виконайте міграції
Запустіть сервер розробки

Передумови

Необхідне програмне забезпечення

Node.js 22 — Завантажити з nodejs.org
npm 10+ або pnpm 9+ — Менеджер пакетів
Git — Контроль версій
PostgreSQL 16 з розширенням PostGIS — Дивіться розділ налаштування бази даних
VS Code — Рекомендоване IDE

Додаткові інструменти

Docker — Для контейнеризованого PostgreSQL (альтернатива встановленню через Homebrew)
Postman або Bruno — Тестування API

Встановлення

1. Клонування репозиторію

2. Встановлення залежностей

3. Конфігурація середовища

Скопіюйте шаблон середовища:

Налаштуйте ваш файл .env.local з такими обов'язковими змінними:

Згенеруйте AUTH_SECRET за допомогою: npx @better-auth/cli secret

Повний перелік підтримуваних змінних та їх опис дивіться в Конфігурація середовища.

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

Варіант A: Docker (рекомендовано для локальної розробки)

Варіант B: Homebrew (macOS)

Виконання міграцій

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

Застосунок буде доступний за адресами:

Фронтенд: http://localhost:3000
API маршрути: http://localhost:3000/api/*
Перевірка стану: http://localhost:3000/api/health

Інструменти розробки

Гаряче перезавантаження

Сервер розробки Next.js підтримує гаряче перезавантаження для:

React компонентів та Server Components
API маршрутів
Змін Tailwind CSS
Файлів локалізації (потребує перезапуску сервера для нових ключів)

Перевірка типів

Лінтинг

Структура проєкту

Тестування

Поширені проблеми

Порт 3000 вже використовується

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

Переконайтеся, що PostgreSQL працює: pg_isready
Перевірте значення .env.local для DB_HOST, DB_PORT, DB_USER, DB_PASSWORD
Переконайтеся, що база даних ring_platform існує
Підтвердьте, що DB_BACKEND_MODE встановлено на k8s-postgres-fcm

Помилки OAuth Auth.js

Переконайтеся, що AUTH_GOOGLE_ID та AUTH_GOOGLE_SECRET вказано в .env.local
Перевірте, що http://localhost:3000 є в дозволених URI перенаправлення консолі Google OAuth
Переконайтеся, що AUTH_SECRET встановлено та є однаковим
Формат URL зворотного виклику: http://localhost:3000/api/auth/callback/google

Firebase FCM не працює (необов'язково)

Наступні кроки

Конфігурація середовища — Повний довідник змінних середовища
Розгортання — Розгортання в продакшн
Посібник з встановлення — Продакшн встановлення
Структура коду — Організація кодової бази
Робочий процес розробки — Git робочий процес та найкращі практики
Тестування — Написання та запуск тестів

Потрібна допомога? Перевірте посібник з усунення неполадок або приєднуйтесь до нашої Discord спільноти.

Налаштування локальної розробки

Посібник з налаштування Ring Platform для локальної розробки.

Що вам знадобиться

Node.js 22, pnpm/npm та Git встановлені на вашому комп'ютері
PostgreSQL 16 + PostGIS (через Homebrew, Docker або нативне встановлення)
Редактор коду (рекомендується VS Code)

Огляд налаштування

Клонуйте репозиторій
Встановіть залежності
Налаштуйте змінні середовища з env.local.template
Налаштуйте PostgreSQL та виконайте міграції
Запустіть сервер розробки

Передумови

Необхідне програмне забезпечення

Node.js 22 — Завантажити з nodejs.org
npm 10+ або pnpm 9+ — Менеджер пакетів
Git — Контроль версій
PostgreSQL 16 з розширенням PostGIS — Дивіться розділ налаштування бази даних
VS Code — Рекомендоване IDE

Додаткові інструменти

Docker — Для контейнеризованого PostgreSQL (альтернатива встановленню через Homebrew)
Postman або Bruno — Тестування API

Встановлення

1. Клонування репозиторію

2. Встановлення залежностей

3. Конфігурація середовища

Скопіюйте шаблон середовища:

Налаштуйте ваш файл .env.local з такими обов'язковими змінними:

Згенеруйте AUTH_SECRET за допомогою: npx @better-auth/cli secret

Повний перелік підтримуваних змінних та їх опис дивіться в Конфігурація середовища.

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

Варіант A: Docker (рекомендовано для локальної розробки)

Варіант B: Homebrew (macOS)

Виконання міграцій

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

Застосунок буде доступний за адресами:

Фронтенд: http://localhost:3000
API маршрути: http://localhost:3000/api/*
Перевірка стану: http://localhost:3000/api/health

Інструменти розробки

Гаряче перезавантаження

Сервер розробки Next.js підтримує гаряче перезавантаження для:

React компонентів та Server Components
API маршрутів
Змін Tailwind CSS
Файлів локалізації (потребує перезапуску сервера для нових ключів)

Перевірка типів

Лінтинг

Структура проєкту

Тестування

Поширені проблеми

Порт 3000 вже використовується

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

Переконайтеся, що PostgreSQL працює: pg_isready
Перевірте значення .env.local для DB_HOST, DB_PORT, DB_USER, DB_PASSWORD
Переконайтеся, що база даних ring_platform існує
Підтвердьте, що DB_BACKEND_MODE встановлено на k8s-postgres-fcm

Помилки OAuth Auth.js

Переконайтеся, що AUTH_GOOGLE_ID та AUTH_GOOGLE_SECRET вказано в .env.local
Перевірте, що http://localhost:3000 є в дозволених URI перенаправлення консолі Google OAuth
Переконайтеся, що AUTH_SECRET встановлено та є однаковим
Формат URL зворотного виклику: http://localhost:3000/api/auth/callback/google

Firebase FCM не працює (необов'язково)

Наступні кроки

Конфігурація середовища — Повний довідник змінних середовища
Розгортання — Розгортання в продакшн
Посібник з встановлення — Продакшн встановлення
Структура коду — Організація кодової бази
Робочий процес розробки — Git робочий процес та найкращі практики
Тестування — Написання та запуск тестів

Потрібна допомога? Перевірте посібник з усунення неполадок або приєднуйтесь до нашої Discord спільноти.

text


ring-platform.org/
├── app/                  # Next.js 16 App Router
│   ├── (auth)/           # Сторінки автентифікації (вхід, реєстрація)
│   ├── api/              # API маршрути
│   └── (public)/         # Публічні сторінки
├── features/             # Модулі функцій
│   ├── news/             # Управління новинами
│   ├── entities/         # Управління сутностями
│   ├── opportunities/    # Система можливостей
│   └── wallet/           # Web3 гаманець
├── lib/                  # Основні бібліотеки
│   ├── database/         # Абстракція бази даних
│   │   ├── DatabaseService.ts
│   │   └── adapters/     # PostgreSQLAdapter, FirebaseAdapter
│   ├── firebase-admin.server.ts  # Firebase Admin (FCM лише)
│   └── auth-adapter-singleton.ts # Вибір адаптера Auth.js
├── @actions/             # Серверні дії
├── data/                 # SQL міграції
├── infrastructure/       # Скрипти ініціалізації Postgres
├── public/               # Статичні ресурси, firebase-messaging-sw.js
├── locales/              # Файли перекладів i18n
├── env.local.template    # Єдине джерело істини для змінних середовища
└── ring-config.json      # Конфігурація клону

text


ring-platform.org/
├── app/                  # Next.js 16 App Router
│   ├── (auth)/           # Сторінки автентифікації (вхід, реєстрація)
│   ├── api/              # API маршрути
│   └── (public)/         # Публічні сторінки
├── features/             # Модулі функцій
│   ├── news/             # Управління новинами
│   ├── entities/         # Управління сутностями
│   ├── opportunities/    # Система можливостей
│   └── wallet/           # Web3 гаманець
├── lib/                  # Основні бібліотеки
│   ├── database/         # Абстракція бази даних
│   │   ├── DatabaseService.ts
│   │   └── adapters/     # PostgreSQLAdapter, FirebaseAdapter
│   ├── firebase-admin.server.ts  # Firebase Admin (FCM лише)
│   └── auth-adapter-singleton.ts # Вибір адаптера Auth.js
├── @actions/             # Серверні дії
├── data/                 # SQL міграції
├── infrastructure/       # Скрипти ініціалізації Postgres
├── public/               # Статичні ресурси, firebase-messaging-sw.js
├── locales/              # Файли перекладів i18n
├── env.local.template    # Єдине джерело істини для змінних середовища
└── ring-config.json      # Конфігурація клону

text


ring-platform.org/
├── app/                  # Next.js 16 App Router
│   ├── (auth)/           # Сторінки автентифікації (вхід, реєстрація)
│   ├── api/              # API маршрути
│   └── (public)/         # Публічні сторінки
├── features/             # Модулі функцій
│   ├── news/             # Управління новинами
│   ├── entities/         # Управління сутностями
│   ├── opportunities/    # Система можливостей
│   └── wallet/           # Web3 гаманець
├── lib/                  # Основні бібліотеки
│   ├── database/         # Абстракція бази даних
│   │   ├── DatabaseService.ts
│   │   └── adapters/     # PostgreSQLAdapter, FirebaseAdapter
│   ├── firebase-admin.server.ts  # Firebase Admin (FCM лише)
│   └── auth-adapter-singleton.ts # Вибір адаптера Auth.js
├── @actions/             # Серверні дії
├── data/                 # SQL міграції
├── infrastructure/       # Скрипти ініціалізації Postgres
├── public/               # Статичні ресурси, firebase-messaging-sw.js
├── locales/              # Файли перекладів i18n
├── env.local.template    # Єдине джерело істини для змінних середовища
└── ring-config.json      # Конфігурація клону

Documentation

Швидкий вхід (CTO · аудитори · агенти)

Documentation

Швидкий вхід (CTO · аудитори · агенти)

Documentation

Швидкий вхід (CTO · аудитори · агенти)

Loading documentation...

Documentation

Швидкий вхід (CTO · аудитори · агенти)

Loading documentation...

Documentation

Швидкий вхід (CTO · аудитори · агенти)

Loading documentation...

Documentation

Швидкий вхід (CTO · аудитори · агенти)

Loading documentation...

Loading documentation...

Loading documentation...

Налаштування локальної розробки

Що вам знадобиться

Огляд налаштування

Налаштування локальної розробки

Що вам знадобиться

Огляд налаштування

Налаштування локальної розробки

Що вам знадобиться

Огляд налаштування