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. Клонировать и установить

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

pnpm install
pnpm build

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

Путь зависит от того, есть ли у вас место в Doppler-организации Happ.

Есть место в организации:

doppler login
doppler setup
# → Выбрать: integ-core / local

Внешний интегратор — вам выдали service token. Логин не нужен: токен привязывается к папке проекта, а не к аккаунту.

doppler configure set token dp.st.xxx --scope ~/work/integ-core

Токен read-only и действует только на integ-core / local. Не кладите его в .bashrc и не коммитьте — привязка к папке достаточна.

Проверить, что всё встало:

doppler secrets --only-names | head

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

# Для скачивания 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 файлы и настроить БД

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

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

---

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

Локальный Docker больше не нужен. Вы поднимаете только свою интеграцию, а API и админку берёте девовские — они ходят к вам через ваш корпоративный Cloudflare-туннель.

Шаг 1: поднять gateway на своём туннеле

pnpm start gateway --tunnel=<ваш-слаг>

Слаг — имя вашего именованного туннеля (credentials лежат в ~/.cloudflared/<слаг>.json). Gateway окажется доступен снаружи как https://<слаг>.integ.happ.tools.

Шаг 2: поднять интеграцию

В отдельном терминале:

pnpm start sofa

Шаг 3: направить девовскую админку на себя

Откройте admin-integ.dev.happ.tools:

1. Настройки → Профиль — впишите тот же слаг в поле tunnel username.
2. В нижней части сайдбара включите тумблер туннеля. Индикатор рядом покажет, отвечает ли ваш gateway.

С этого момента админка работает с вашей локальной интеграцией: D1, KV, секреты и вызовы хендлеров уходят на ваш ноутбук, а не на дев.

Что	Где
Админка	admin-integ.dev.happ.tools
Ваш gateway снаружи	https://<слаг>.integ.happ.tools
Он же локально	http://localhost:3010
Ваша интеграция	http://localhost:8787

Остановка

Ctrl+C в обоих терминалах. Туннель гасится вместе с gateway.

---

Когда всё-таки нужен Docker

pnpm docker:local поднимает PostgreSQL, integ-api и integ-admin у вас локально. Это нужно в двух случаях: вы правите сам integ-api или integ-admin, либо работаете без интернета. Для обычной работы над интеграцией — не нужно.

pnpm docker:local        # postgres :5435, api :3005, admin :4205
docker compose down      # остановить

---

Если админка не видит вашу интеграцию

Симптом	Причина
Индикатор туннеля красный	gateway не запущен или запущен без --tunnel
D1 и KV пустые, хотя данные есть	слаг в настройках админки не совпадает с --tunnel=<слаг>
401 при обращении к D1/KV	INTROSPECT_TOKEN в вашем Doppler integ-core/local разошёлся с девовским
Тумблер туннеля не виден	вы на прод-админке — туннель работает только с девовской

---

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

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)

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

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

pnpm build

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

pnpm generate:env -- local

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

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

"D1Database is required"

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

Порт занят

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

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

---

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

• 📖 Архитектура — как всё устроено
• 📖 Чеклист интеграции — что не забыть
• 📖 Правила кода — стиль и конвенции
• 📖 Handlers Reference — написание handlers