Integ Docs

Appearance

Quick Start / Быстрый старт ​

📋 Для интеграторов — полная настройка локального окружения

Архитектура локальной разработки ​

┌─────────────────── Docker ────────────────────┐
│                                               │
│  ┌───────────┐  ┌───────────┐  ┌──────────┐  │
│  │integ-admin│─▶│ integ-api │─▶│ postgres │  │
│  │   :4205   │  │   :3005   │  │  :5435   │  │
│  └───────────┘  └───────────┘  └──────────┘  │
│                                               │
└───────────────────────────────────────────────┘
                       │ host.docker.internal
                       ▼
┌─────────────── Host (miniflare) ──────────────┐
│                                               │
│  Gateway :3010  ──▶  Integration :8787        │
│  (pnpm start)       (pnpm start sofa)         │
│                           │                   │
│                           ▼                   │
│                    data/miniflare/            │
│                    (D1 SQLite + KV)           │
│                                               │
└───────────────────────────────────────────────┘

Требования ​

  • Node.js 20+
  • pnpm (npm install -g pnpm)
  • Docker Desktop
  • Doppler CLI (brew install dopplerhq/cli/doppler)

Первоначальная настройка (один раз) ​

1. Клонировать и установить ​

bash
git clone git@github.com:Happ-AI/integ-core.git
cd integ-core

pnpm install
pnpm build

2. Настроить Doppler ​

bash
# Логин в Doppler
doppler login

# Привязка проекта integ-core
doppler setup
# → Выбрать: integ-core / local

3. Авторизация в GitHub Container Registry ​

bash
# Для скачивания Docker-образов integ-api и integ-admin
gh auth login
gh auth token | docker login ghcr.io -u $(gh api user -q .login) --password-stdin

4. Сгенерировать env файлы и настроить БД ​

bash
# Генерирует .env, .dev.vars, wrangler.toml и .env.api (для Docker)
pnpm generate:env -- local

# Создать локальные D1/KV базы данных
pnpm setup:local

Ежедневный запуск ​

Шаг 1: Запустить Docker-сервисы ​

bash
pnpm docker:local

Это запустит:

СервисURL
PostgreSQLlocalhost:5435
integ-apihttp://localhost:3005
integ-adminhttp://localhost:4205

Шаг 2: Запустить miniflare (в отдельных терминалах) ​

Терминал 1 — Gateway:

bash
pnpm start gateway

Gateway доступен на http://localhost:3010

Терминал 2 — Интеграция:

bash
pnpm start sofa

Worker доступен на http://localhost:8787

Готово! ​

Обновление Docker-образов ​

Когда выходят обновления integ-api или integ-admin:

bash
# Скачать новые образы и перезапустить
docker compose pull
docker compose up -d

Или одной командой:

bash
pnpm docker:local

Остановка сервисов ​

bash
# Остановить Docker-контейнеры
docker compose down

# Miniflare останавливается через Ctrl+C в терминалах

Создание новой интеграции ​

bash
pnpm generate:integration mycrm
pnpm start mycrm

Полезные команды ​

КомандаОписание
pnpm generate:env -- localСгенерировать env файлы из Doppler
pnpm setup:localСоздать локальные D1/KV базы
pnpm setup:resetСбросить и пересоздать локальные БД
pnpm start gatewayЗапуск Gateway Worker
pnpm start sofaЗапуск интеграции sofa
pnpm buildСборка всех пакетов
pnpm testЗапуск тестов
pnpm docker:localЗапустить Docker-стек
docker compose downОстановить Docker-контейнеры
docker compose logs -f integ-apiЛоги integ-api

Troubleshooting ​

Docker образы не скачиваются (unauthorized) ​

bash
gh auth login
gh auth token | docker login ghcr.io -u $(gh api user -q .login) --password-stdin

"Can't resolve @happ-integ/..." ​

bash
pnpm build

Ошибки с переменными окружения ​

bash
pnpm generate:env -- local

integ-api не запускается (ошибка .env.api) ​

bash
# Перегенерировать env файлы
pnpm generate:env -- local

"D1Database is required" ​

bash
pnpm setup:local
# или для полного сброса:
pnpm setup:reset

Порт занят ​

bash
# Проверить что использует порт
lsof -i :3005

# Остановить Docker-контейнеры
docker compose down

Следующие шаги ​