--- title: "Локальная настройка" description: "Настройка локальной разработки с PostgreSQL 16, PostGIS, Auth.js v5 и сервисным слоем Ring Platform" locale: "ru" --- # Настройка локальной разработки Руководство по настройке 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) — Развёртывание в production - [Руководство по установке](/docs/en/getting-started/installation.md) — Production установка - [Структура кода](/docs/en/development/code-structure.md) — Организация кодовой базы - [Рабочий процесс разработки](/docs/en/development/workflow.md) — Git workflow и лучшие практики - [Тестирование](/docs/en/development/testing.md) — Написание и запуск тестов --- Нужна помощь? Проверьте [руководство по устранению неполадок](/docs/en/getting-started/troubleshooting.md) или присоединяйтесь к нашему [Discord сообществу](https://discord.gg/ring-platform).