# Развёртывание

Два пути: **быстрый** (для уже зарегистрированного сервиса — изменить compose/env
и поднять) и **полный релиз** (схема + манифест → выгрузка релиза → запуск на
одном или нескольких серверах).

> Перед изменяющими операциями убедитесь, что `read_only=false` в конфиге, а
> ассистент запрашивает подтверждение (`confirm`) на разрушительные шаги.

## Быстрый путь: один уже известный сервис

```text
Промпт: «Обнови compose сервиса demo_web на образ nginx:1.27, подними его и дождись результата.»
```

Вызовы:

1. `list_applications` — найти `demo_web` и его `app_id` (или `get_application`, если id известен).
2. `set_compose {app_id, content}` — записать новый compose (создаётся версия, конфиг уходит агенту).
   При необходимости — `set_env {app_id, filename, content}`.
3. `deploy {app_id, wait:true}` — `docker-compose up -d` и ожидание задачи.
4. `overview` — убедиться, что сервис поднялся.

Для перезапуска — `restart`; для остановки — `down {confirm:true}`.

## Полный релиз: один сервер

Минимальная схема — один хост:

```json
{
  "vm1": { "ip": "10.20.30.11", "services": ["user_system_front"] }
}
```

```text
Промпт: «Сохрани schema.json и manifest.json, разложи хост, скачай релиз с образами,
дождись завершения и запусти сервисы.»
```

1. `save_deployment_files {schema, manifest}`
2. `ip_match` — проверить, что IP хоста сопоставлен агенту.
3. `seed_hosts` — создать запись хоста до выхода агента.
4. `download_release {load_images:true, confirm:true}` → `{"status":"started"}`
5. `release_job` (опрос) — `status: running` → `completed`
6. `start_services` → `start_task_ids`
7. `deployment_tasks` / `get_task {task_id, wait:true}` — результат запуска
8. `overview` — сводка

## Полный релиз: несколько серверов

Схема описывает все VM и их сервисы:

```json
{
  "vm-node-1": { "ip": "10.20.30.11", "services": ["chats", "user_system"] },
  "vm-node-2": { "ip": "10.20.30.12", "services": ["report_system"] }
}
```

Манифест сопоставляет сервис и пакет релиза (URL архива в GitLab):

```json
{
  "services": {
    "chats":         { "package": "https://gitlab.example/api/v4/.../chats.tar.gz" },
    "user_system":   { "package": "https://gitlab.example/api/v4/.../user_system.tar.gz" },
    "report_system": { "package": "https://gitlab.example/api/v4/.../report_system.tar.gz" }
  }
}
```

Порядок:

1. `save_deployment_files {schema, manifest}` (при необходимости — `prebuild_vars`).
2. `ip_match` — увидеть `matched_pairs` и `unmatched_schema_ips`.
   Если IP в схеме не совпадают с IP агентов — задать соответствие через
   `save_deployment_files {ip_overrides}`:
   ```json
   { "10.20.30.11": "10.20.30.101", "10.20.30.12": "10.20.30.102" }
   ```
   затем снова `ip_match`.
3. `fill_vars` (опционально) — заполнить `prebuild_vars` из схемы.
4. `seed_hosts` — создать записи хостов.
5. `download_release {load_images:true, confirm:true}` — запускает фоновую
   выгрузку пакетов и образов; прогресс — `release_job`
   (`phase`, `images_pulled`/`images_total`).
   Без образов: `download_release {load_images:false}` вернёт
   `downloaded_services` и `sync_task_ids`.
6. `start_services` → `start_task_ids` (по одной задаче на хост).
7. `deployment_tasks` и `get_task {wait:true}` — дождаться результата по каждому хосту.
8. `overview` — итоговая сводка; `list_applications` — статусы сервисов.

> Токен GitLab: задайте `gitlab_token` в конфиге сервера (или переменной
> окружения) — тогда не придётся передавать секрет в аргументе.

## Обновление фронта

Фронт-сервисы (`user_system_front`, `chat_widget`, `scenario_front` и др.)
принимают собранную папку.

1. В конфиге сервера задайте `front_roots` — каталог, куда вы кладёте сборки:
   ```json
   "front_roots": ["/srv/omni-front-builds"]
   ```
2. ```text
   Промпт: «Обнови фронт user_system_front из /srv/omni-front-builds/us.»
   ```
   `update_front {app_id, build_dir:"/srv/omni-front-builds/us", confirm:true}` →
   задача агенту → `get_task {wait:true}`.

Каталог обязан лежать внутри `front_roots` (защита от загрузки произвольных
путей); содержимое `build_folder` на хосте заменяется целиком.

## Откат конфигурации

Каждое изменение compose/env создаёт версию, поэтому откат безопасен.

- Compose: `get_application {app_id}` → выбрать `version_id` → `restore_compose {version_id, confirm:true}`.
- Env: `env_versions {app_id, filename}` → `restore_env_version {version_id, confirm:true}`.

Восстановление создаёт **новую** версию (история сохраняется) и отправляет
конфиг агенту.

## Миграции

```text
Промпт: «Запусти миграции сервиса 5 и проверь результат.»
```

`migrate {app_id:5, wait:true}`; журнал последних миграций — в
`get_application` (`migration_logs`).