# AGIL Calls — запуск и эксплуатация

Документ для DevOps: как поднять MVP, что обязательно для production и как
масштабироваться дальше. Переменные окружения — в [README](../README.md#переменные-окружения-сервера)
и `docs/contract.md` §2/§14.

## 1. Локальный запуск

```bash
npm ci
npm run build
npm start            # http://localhost:8787 — API + WS + demo + editor + dashboard + SDK
```

Разработка: `npm run dev` (сервер 8787, demo 5173, редактор 5174, панель 5175).

Проверка: `npm test`, `npm run e2e` (headless Chrome/Edge, 2 участника, чат, тема).

## 2. Docker

```bash
cp .env.example .env      # задайте секреты
docker compose up -d --build
```

Образ — multi-stage (`Dockerfile`): сборка всех пакетов → runtime только с `dist`
и production-зависимостями, запуск от пользователя `node`, healthcheck на
`/v1/health`, данные в volume `/app/.data`.

## 3. Обязательный production-минимум

1. **TLS** на reverse proxy (Caddy/Nginx/ALB). WebSocket — с `Upgrade`/`Connection`
   и таймаутами не меньше 1 часа (иначе рвётся keepalive).
2. **TURN** (coturn) — без него звонки не пройдут через NAT/корпоративные сети.
   `AGIL_ICE_SERVERS` должен содержать `stun:` и `turn:` (better `turns:` 5349).
   Для TURN over TLS — сертификат и `--tls-listening-port`.
3. **Секреты** — только из env/vault: `AGIL_TOKEN_SECRET` (≥32 байт),
   `AGIL_API_KEYS` (сильный ключ на тенант), `AGIL_IP_SALT`,
   `AGIL_AI_AGENT_KEY`/`AGIL_KNOWLEDGE_AGENT_KEY`/`AGIL_STT_KEY`,
   `AGIL_INTEGRITY_KEY`, HMAC-секреты вебхуков. В git — никогда.
4. `AGIL_ALLOW_ANONYMOUS=0` в проде; выпуск токенов — только с бэкенда компании.
5. `AGIL_TRUST_PROXY=1` только если за прокси (для IP/гео-заголовков).
6. Файловое хранилище `.data` — на持久 диск с бэкапом; лимит диска мониторить
   (записи/файлы). Для S3-совместимого хранилища — адаптер FilesStore (roadmap).
7. Гео-провайдер: `AGIL_GEO_PROVIDER=header` + заголовки от CDN/WAF
   (`x-agil-country`, `cf-ipcountry`, `x-vercel-ip-country`), либо `ipapi`
   (внешний вызов; учитывайте приватность).
8. Публикация документации/MCP — по умолчанию в проде закройте наружу:
   `AGIL_DOCS_ENABLED=0` (или allowlist/отдельный порт), `AGIL_ADMIN_API_ENABLED`
   и `AGIL_MCP_HTTP_*` — см. `docs/api-exposure.md`. Отдельный docs-порт
   (`AGIL_DOCS_PORT`) не должен попадать во внешний ingress.

## 4. Мониторинг

- `GET /v1/health` — liveness (ok, uptime, rooms, tenants, security-флаги).
- `GET /v1/admin/overview`, `GET /v1/admin/security` — KPI и события.
- `GET /v1/admin/audit?limit=…` — аудит (JSONL в `.data/audit`).
- Логи сервера — структурированные строки старта/ошибок; для продакшена
  подключите сбор логов (stdout → Loki/ELK) и алерты на 5xx, рестарты,
  `webhook.failed`, `join.denied`, `geo.blocked`, `integrity.flagged`.
- Сетевые метрики WebRTC — из виджета (`quality-changed`) можно отправлять в
  свою аналитику через host-приложение; серверных метрик медиа в mesh-режиме нет.

## 5. Масштабирование

Текущий MVP — один инстанс, состояние (комнаты/WS/чат) в памяти.

| Этап | Что делать |
|---|---|
| 1. Вертикально | больше RAM/CPU; вынести `.data` на быстрый диск; CDN для статики |
| 2. Горизонтально (signaling) | Redis pub/sub для broadcast между инстансами, sticky sessions по комнате (consistent hashing), WS-прокси (Nginx `ip_hash`) |
| 3. Медиа | перейти на SFU: LiveKit (Apache-2.0) или mediasoup; `mediaMode:'sfu'` в комнате, сервер выдаёт SFU-транспорты; TURN остаётся |
| 4. Хранилище | S3/MinIO для файлов/записей, Postgres для метаданных и аудита, объектная ротация |
| 5. Очереди | вынести AI-анализ/STT/вебхуки в воркеры (очередь + ретраи) |
| 6. Мультирегион | региональные кластеры + маршрутизация по гео; данные — по резидентности |

Оценка перехода на SFU и production-объёма — `docs/estimate.md` (C1: LiveKit +
свой слой).

## 6. Бэкапы и retention

- `.data/tenants` — конфиги (бэкап ежедневно, маленькие).
- `.data/audit` — append-only JSONL (ротация по размеру, отправка в SIEM).
- `.data/files`, `.data/recordings` — по политике компании; TTL ссылок —
  `AGIL_FILE_TTL_SEC`, удаление через `DELETE /v1/admin/recordings/:id`.
- Транскрипты/заметки — retention `session.aiAgent.retentionMin` (минуты).
- При удалении тенанта — удалить `.data/<tenant>` целиком (процедура описана в
  `docs/security.md`).

## 7. Чек-лист перед продакшеном

- [ ] TLS-сертификаты, HSTS, WSS работает через прокси
- [ ] TURN/TURNS настроен и проверен на мобильной сети и корпоративном VPN
- [ ] `AGIL_ALLOW_ANONYMOUS=0`, ключи ≥32 символов, секреты в vault
- [ ] Гео-политика и пароли включены для чувствительных тенантов
- [ ] Запись/STT/AI/knowledge — включены осознанно, согласие настроено
- [ ] Вебхуки компании принимают и проверяют подпись; есть dead-letter лог
- [ ] Бэкапы `.data` и проверка восстановления
- [ ] Мониторинг `/v1/health`, алерты на 5xx/рестарты
- [ ] Аудит уходит в SIEM компании
- [ ] Проверены Safari/iOS и корпоративные браузеры (WebRTC-политики)