Установка

Разработка без контейнеров

Запуск из исходников через pnpm, структура монорепозитория и полезные команды.

На этой странице · 5

В контейнере правки видны только после пересборки образа. Если вы меняете код, удобнее оставить в Docker одну базу, а шлюз и кабинет запускать из исходников: API перезапускается по node --watch, кабинет обновляется турбопаком.

Что нужно на машине


Node	`engines` в корневом `package.json` требует 20.10 и выше. Образ и боевой сервер — Node 26; API запускается прямо с TypeScript-исходников через `node --experimental-strip-types`
pnpm	10.33.4 — версия закреплена полем `packageManager`
Docker	только ради PostgreSQL

Запуск

1
Поднимите базу
```
docker compose up -d postgres
```
То же самое делает pnpm db:up.
2
Поставьте зависимости
```
pnpm install
```
postinstall пакета @apistend/api сам вызывает prisma generate.
3
Заполните .env
```
cp .env.example .env
```
Обязательных переменных две — DATABASE_URL и JWT_SECRET; без них API не стартует. Остальное имеет значения по умолчанию.
4
Накатите схему и демо-данные
```
pnpm db:migrate
pnpm db:seed
```
pnpm db:seed печатает ключи API в терминал — других мест, где полный ключ виден, нет: в базе лежит только HMAC-хеш.
5
Запустите шлюз и кабинет
```
pnpm dev
```
Это turbo run dev --parallel: API на 8080 под node --watch, кабинет на 3100 под next dev --turbopack.

Структура монорепозитория

Пакет	Назначение
`apps/web`	Next.js: лендинг, кабинет и эта документация
`apps/api`	Fastify: мок-шлюз, каталог, ключи, журнал, вебхуки, туннель
`packages/cli`	npm-пакет `apistend` — вход, туннель, триггеры событий
`packages/mock-engine`	резолвер ответов, детерминированная генерация, LRU-кеш
`packages/catalog-ingest`	спецификации и документация → каталог методов
`packages/ui`	дизайн-система
`packages/shared`	профили сервисов, конверты ошибок, протокол туннеля

Каталог методов лежит в репозитории уже собранным — packages/mock-engine/generated/*.catalog.json под контролем версий. Движок читает эти файлы при старте; отсутствующий сервис просто пропускается, и в /health его не будет.

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

Команды корня репозитория

Команда	Что делает
pnpm dev	шлюз и кабинет параллельно
pnpm db:up	поднять только контейнер с базой
pnpm db:migrate	`prisma migrate dev` — создать и применить миграцию
pnpm db:push	`prisma db push` — синхронизировать схему без миграции
pnpm db:seed	демо-данные и ключи, пересоздаёт демо-аккаунт
pnpm db:studio	Prisma Studio
pnpm -w typecheck	проверка типов по всем пакетам
pnpm -w test	тесты, включая сквозные с настоящим CLI
pnpm ingest	пересобрать каталог из спецификаций
pnpm vendor:b24	скачать документацию Bitrix24 и русские тексты
pnpm clean	`git clean -xdf node_modules dist .next .turbo`

pnpm ingest нужен, только когда меняются спецификации в specs/: без него каталог уже на месте.

Подводные камни

API по умолчанию слушает петлю. API_HOST без значения — это 127.0.0.1. Для разработки правильно; для контейнера или для доступа с другой машины нужен 0.0.0.0.

WEB_ORIGIN считается из WEB_PORT. Значение по умолчанию — http://localhost:${WEB_PORT}, а если WEB_PORT не задан, то порт 3000. Кабинет при этом всегда поднимается на 3100 (порт зашит в dev-скрипт apps/web), поэтому .env без WEB_PORT=3100 даёт кабинет, которому CORS запрещает ходить в API. Симптом — вход не проходит, в консоли браузера отказ по origin.

NODE_ENV=production ломает установку зависимостей. pnpm в этом режиме выбросит prisma и dotenv, а dotenv импортируется в рантайме — apps/api/src/env.ts читает корневой .env. Ставьте с --prod=false, как это делают образ и боевой сервер.

Сборка API в развёртывании не участвует. Скрипт tsc -p tsconfig.build.json у пакета есть и входит в pnpm -w build, но результат никуда не идёт: и в образе, и на сервере запускается node --experimental-strip-types apps/api/src/server.ts. Снятие типов — не транспиляция, поэтому в tsconfig.base.json включён erasableSyntaxOnly: enum, namespace и параметры-свойства конструктора Node не переварит.

Дальше читайте

Переменные окружениячто и на что влияет Запуск одной командойвариант в контейнерах