Integ Docs | API

Appearance

Первоначальная настройка ​

Пошаговое руководство по настройке проекта Integ API с нуля. Выполняется один раз при начале работы с проектом.

Время выполнения

~15-20 минут при хорошем интернет-соединении

Чеклист требований ​

Перед началом убедитесь, что установлено:

  • [ ] Node.js 20.x+ (node --version)
  • [ ] npm 10.x+ (npm --version)
  • [ ] Docker 24.x+ (docker --version)
  • [ ] Docker Compose 2.x+ (docker compose version)
  • [ ] Git (git --version)
  • [ ] Доступ к репозиторию проекта

Шаг 1: Клонирование репозитория ​

bash
# Клонировать репозиторий
git clone git@github.com:Happ-AI/integ-api.git

# Перейти в директорию
cd integ-api

# Проверить текущую ветку
git branch
# Должно показать: * dev
Если нет доступа к репозиторию

Обратитесь к администратору для получения доступа. Вам нужен SSH ключ добавленный в GitHub.

bash
# Проверить SSH ключ
ssh -T git@github.com

Шаг 2: Установка зависимостей ​

bash
# Установить npm пакеты
npm install

# Инициализировать Husky (git hooks)
npm run prepare

Ожидаемый результат: папка node_modules создана, нет ошибок в консоли.

Шаг 3: Установка Doppler CLI ​

Doppler используется для управления секретами и переменными окружения.

macOS ​

bash
brew install dopplerhq/cli/doppler

Linux ​

bash
# Ubuntu/Debian
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg
curl -sLf --retry 3 --tlsv1.2 --proto "=https" \
  'https://packages.doppler.com/public/cli/gpg.DE2A7741A397C129.key' | \
  sudo gpg --dearmor -o /usr/share/keyrings/doppler-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/doppler-archive-keyring.gpg] https://packages.doppler.com/public/cli/deb/debian any-version main" | \
  sudo tee /etc/apt/sources.list.d/doppler-cli.list
sudo apt-get update && sudo apt-get install doppler

Windows (PowerShell) ​

powershell
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex
scoop bucket add doppler https://github.com/DopplerHQ/scoop-doppler.git
scoop install doppler

Проверка установки ​

bash
doppler --version
# Должно показать версию

Шаг 4: Настройка Doppler ​

bash
# Авторизоваться (откроет браузер)
doppler login

# Настроить проект
doppler setup

# Выбрать:
# - Project: integ-api
# - Config: local

Проверка:

bash
doppler secrets
# Должен показать список секретов

Нет доступа к Doppler?

Обратитесь к администратору проекта для получения доступа к workspace.

Шаг 5: Запуск Docker инфраструктуры ​

bash
# Запустить PostgreSQL
npm run docker:up

# Проверить что контейнер работает
docker ps

Ожидаемый результат:

CONTAINER ID   IMAGE         STATUS    PORTS
xxxx           postgres:16   Up        0.0.0.0:5435->5432/tcp

Шаг 6: Запуск миграций ​

bash
# Применить миграции базы данных
npm run migration:run

Ожидаемый результат:

Migration AddUsersTable has been executed successfully
Migration AddIntegrationsTable has been executed successfully
...

Шаг 7: Первый запуск ​

bash
# Запустить dev сервер
npm start

Ожидаемый результат:

[Nest] LOG [NestApplication] Nest application successfully started
[Nest] LOG Application is running on: http://localhost:3005

Шаг 8: Проверка работоспособности ​

Health Check ​

bash
curl http://localhost:3005/health
# {"status":"ok"}

Scalar UI ​

Откройте в браузере: http://localhost:3005/api/reference

Создание тестового пользователя ​

bash
curl -X POST http://localhost:3005/api/auth/sign-up \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123"
  }'

Получение токена ​

bash
curl -X POST http://localhost:3005/api/auth/sign-in \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123"
  }'

Сохраните полученный токен для дальнейшей работы.

Шаг 9: Настройка IDE (опционально) ​

VS Code ​

Рекомендуемые расширения:

  • ESLint - линтинг
  • Prettier - форматирование
  • TypeScript - поддержка TypeScript
  • Docker - работа с контейнерами
bash
# Установить расширения
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension ms-azuretools.vscode-docker

Настройки VS Code ​

Создайте .vscode/settings.json:

json
{
	"editor.formatOnSave": true,
	"editor.defaultFormatter": "esbenp.prettier-vscode",
	"editor.codeActionsOnSave": {
		"source.fixAll.eslint": "explicit"
	},
	"typescript.preferences.importModuleSpecifier": "relative"
}

Итоговый чеклист ​

После выполнения всех шагов проверьте:

  • [ ] npm start запускает приложение без ошибок
  • [ ] http://localhost:3005/health отвечает {"status":"ok"}
  • [ ] http://localhost:3005/api/reference открывается
  • [ ] Можно зарегистрировать и авторизовать пользователя
  • [ ] docker ps показывает работающий контейнер PostgreSQL

Что дальше? ​

  1. Ежедневный workflow - узнайте типичный рабочий день
  2. Архитектура - изучите структуру проекта
  3. Правила кода - познакомьтесь со стандартами
  4. API Guide - начните работать с API

Troubleshooting ​

Порт занят ​

bash
# Найти процесс на порту 3000
lsof -i :3005
kill -9 <PID>

Docker не запускается ​

bash
# Проверить Docker
docker info

# Если не работает - запустить Docker Desktop

Миграции не применяются ​

bash
# Проверить подключение к БД
docker exec -it postgres psql -U postgres -c "SELECT 1"

# Перезапустить миграции
npm run migration:revert
npm run migration:run

Doppler ошибки ​

bash
# Переавторизоваться
doppler logout
doppler login
doppler setup

Подробнее: Частые ошибки