--- title: "Локальне налаштування" description: "Налаштування локальної розробки з PostgreSQL 16, PostGIS, Auth.js v5 та сервісним рівнем Ring Platform" locale: "uk" --- # Налаштування локальної розробки Посібник з налаштування Ring Platform для локальної розробки. ### For founders ## Що вам знадобиться - Node.js 22, pnpm/npm та Git встановлені на вашому комп'ютері - PostgreSQL 16 + PostGIS (через Homebrew, Docker або нативне встановлення) - Редактор коду (рекомендується VS Code) ## Огляд налаштування 1. Клонуйте репозиторій 2. Встановіть залежності 3. Налаштуйте змінні середовища з `env.local.template` 4. Налаштуйте PostgreSQL та виконайте міграції 5. Запустіть сервер розробки ### For developers ## Передумови ### Необхідне програмне забезпечення - **Node.js 22** — [Завантажити з nodejs.org](https://nodejs.org/) - **npm 10+** або **pnpm 9+** — Менеджер пакетів - **Git** — Контроль версій - **PostgreSQL 16** з розширенням **PostGIS** — Дивіться розділ налаштування бази даних - **VS Code** — Рекомендоване IDE ### Додаткові інструменти - **Docker** — Для контейнеризованого PostgreSQL (альтернатива встановленню через Homebrew) - **Postman** або **Bruno** — Тестування API ## Встановлення ### 1. Клонування репозиторію {`git clone https://github.com/connectplatform/ring.git cd ring`} ### 2. Встановлення залежностей {`npm install`} {`pnpm install`} ### 3. Конфігурація середовища Скопіюйте шаблон середовища: {`cp env.local.template .env.local`} > **Warning** > Змінна `DB_BACKEND_MODE` є **обов'язковою** — платформа не запуститься без неї. Для локальної розробки з PostgreSQL встановіть `k8s-postgres-fcm`. Налаштуйте ваш файл `.env.local` з такими обов'язковими змінними: {`# Режим бекенду бази даних (ОБОВ'ЯЗКОВО) DB_BACKEND_MODE=k8s-postgres-fcm # Підключення PostgreSQL DB_HOST=localhost DB_PORT=5432 DB_NAME=ring_platform DB_USER=ring_user DB_PASSWORD=ring_password_2024 DATABASE_URL=postgresql://ring_user:ring_password_2024@localhost:5432/ring_platform # Auth.js v5 AUTH_SECRET=generate-a-random-secret-here AUTH_TRUST_HOST=true AUTH_GOOGLE_ID=your_google_client_id AUTH_GOOGLE_SECRET=your_google_client_secret # Застосунок NEXT_PUBLIC_BASE_URL=http://localhost:3000 NODE_ENV=development`} > **Tip** > Згенеруйте `AUTH_SECRET` за допомогою: `npx @better-auth/cli secret` Повний перелік підтримуваних змінних та їх опис дивіться в [Конфігурація середовища](/docs/en/deployment/environment.md). ### 4. Налаштування бази даних #### Варіант A: Docker (рекомендовано для локальної розробки) {`# Запуск PostgreSQL 16 з PostGIS 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 \\ postgis/postgis:16-3.4`} #### Варіант B: Homebrew (macOS) {`brew install postgresql@16 postgis brew services start postgresql@16 # Створення користувача бази даних та бази даних createuser ring_user -P # пароль: ring_password_2024 createdb ring_platform -O ring_user`} > **Info** > Для локальної розробки з декількома клонами використовуйте скрипт ініціалізації `infrastructure/postgres/bootstrap-brew-dev.sh`. Дивіться `infrastructure/postgres/MIGRATION-KINGDOM-MATRIX.md`. #### Виконання міграцій {`npm run db:migrate`} > **Tip** > Файли міграцій знаходяться в директорії `data/`. Виконавець міграцій читає `DB_BACKEND_MODE` для вибору правильного адаптера. Для локального PostgreSQL (`k8s-postgres-fcm`) він застосовує SQL міграції з `data/schema.sql` та `data/migrations/`. ### 5. Запуск сервера розробки {`npm run dev`} Застосунок буде доступний за адресами: - **Фронтенд**: http://localhost:3000 - **API маршрути**: http://localhost:3000/api/* - **Перевірка стану**: http://localhost:3000/api/health ## Інструменти розробки ### Гаряче перезавантаження Сервер розробки Next.js підтримує гаряче перезавантаження для: - React компонентів та Server Components - API маршрутів - Змін Tailwind CSS - Файлів локалізації (потребує перезапуску сервера для нових ключів) ### Перевірка типів {`npm run type-check`} ### Лінтинг {`npm run lint`} ## Структура проєкту ``` 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 # Конфігурація клону ``` ## Тестування {`npm run test # Модульні тести npm run test:integration # Інтеграційні тести npm run test:e2e # Наскрізні тести`} ## Поширені проблеми ### Порт 3000 вже використовується {`npm run dev -- -p 3001`} ### Відмовлено у з'єднанні з базою даних 1. Переконайтеся, що PostgreSQL працює: `pg_isready` 2. Перевірте значення `.env.local` для `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD` 3. Переконайтеся, що база даних `ring_platform` існує 4. Підтвердьте, що `DB_BACKEND_MODE` встановлено на `k8s-postgres-fcm` ### Помилки OAuth Auth.js 1. Переконайтеся, що `AUTH_GOOGLE_ID` та `AUTH_GOOGLE_SECRET` вказано в `.env.local` 2. Перевірте, що `http://localhost:3000` є в дозволених URI перенаправлення консолі Google OAuth 3. Переконайтеся, що `AUTH_SECRET` встановлено та є однаковим 4. Формат URL зворотного виклику: `http://localhost:3000/api/auth/callback/google` ### Firebase FCM не працює (необов'язково) Firebase використовується лише для push-сповіщень (FCM) у режимі `k8s-postgres-fcm`. Застосунок працюватиме без налаштованого Firebase, але push-сповіщення не будуть доставлятися. Налаштуйте змінні `AUTH_FIREBASE_*` та `NEXT_PUBLIC_FIREBASE_*` за потреби. ## Наступні кроки - [Конфігурація середовища](/docs/en/deployment/environment.md) — Повний довідник змінних середовища - [Розгортання](/docs/en/development/deployment.md) — Розгортання в продакшн - [Посібник з встановлення](/docs/en/getting-started/installation.md) — Продакшн встановлення - [Структура коду](/docs/en/development/code-structure.md) — Організація кодової бази - [Робочий процес розробки](/docs/en/development/workflow.md) — Git робочий процес та найкращі практики - [Тестування](/docs/en/development/testing.md) — Написання та запуск тестів --- Потрібна допомога? Перевірте [посібник з усунення неполадок](/docs/en/getting-started/troubleshooting.md) або приєднуйтесь до нашої [Discord спільноти](https://discord.gg/ring-platform).