telemt-api/docs/GATEWAY_RUN.md

# Запуск Telemt API Gateway (Docker)

Оглавление:

1. [Назначение](#назначение)
2. [Требования](#требования)
3. [Минимальная конфигурация](#минимальная-конфигурация)
4. [Переменные окружения](#переменные-окружения)
5. [Сборка образа](#сборка-образа)
6. [Запуск через Docker CLI](#запуск-через-docker-cli)
7. [Запуск через Docker Compose](#запуск-через-docker-compose)
8. [Проверка](#проверка)
9. [Обновление и CI/CD](#обновление-и-cicd)
10. [Устранение неполадок](#устранение-неполадок)

## Назначение

Шлюз — это один HTTP‑вход для нескольких экземпляров [Telemt Control API](API.md):

- **Белый список IP** (CIDR): кто может обращаться к шлюзу (кроме `GET /health`, см. ниже).
- **Маршрутизация по alias**: клиент вызывает `GET /api/{alias}/health`, шлюз проксирует на `{base_url}/v1/health` у соответствующего сервера.
- **Метрики Prometheus**: `GET /metrics` (под тем же правилом whitelist, что и API).
- **Доверенные прокси**: если прямой TCP‑peer входит в `trusted_proxies`, для проверки whitelist берётся первый адрес из `X-Forwarded-For` или `X-Real-IP`.

Эндпоинты и контракт ответов бэкенда описаны в [API.md](API.md).

## Требования

- Установленные [Docker](https://docs.docker.com/get-docker/) и при необходимости [Docker Compose](https://docs.docker.com/compose/) v2.
- Для локальной сборки из исходников: [Go 1.22+](https://go.dev/dl/) (опционально, если не используете только готовый образ из registry).

## Минимальная конфигурация

Скопируйте [config.example.yaml](../config.example.yaml) в свой `config.yaml` и отредактируйте.

Минимальный рабочий фрагмент для **разработки** (без проверки IP):

```yaml
listen: ":8080"
allow_all: true
servers:
  - alias: main_srv
    base_url: http://127.0.0.1:9091
```

Минимальный фрагмент для **продакшена** (только перечисленные сети/хосты):

```yaml
listen: ":8080"
allow_all: false
whitelist_cidrs:
  - "203.0.113.10/32"
  - "10.0.0.0/8"
servers:
  - alias: main_srv
    base_url: http://telemt-internal:9091
```

Правила:

- При `allow_all: false` и **пустом** `whitelist_cidrs` доступ будет **закрыт для всех** (кроме `GET /health`).
- `GET /health` на шлюзе **не** проверяется по whitelist — так проще настроить Docker `HEALTHCHECK` и оркестраторы.
- Поле `path_prefix` по умолчанию равно `/v1` (префикс Telemt Control API).

Опционально для бэкенда с включённым `auth_header` в Telemt задайте в конфиге имя переменной окружения, значение которой будет отправлено как заголовок `Authorization` на этот upstream:

```yaml
servers:
  - alias: main_srv
    base_url: http://telemt:9091
    authorization_env: TELEMT_API_AUTH
```

Значение должно **точно** совпадать с настроенным в Telemt `auth_header` (см. [API.md](API.md)).

## Переменные окружения

| Переменная     | Описание |
|----------------|----------|
| `CONFIG_PATH`  | Путь к YAML внутри контейнера. По умолчанию: `/etc/telemt-gateway/config.yaml`. |
| `TELEMT_API_AUTH` | Пример: секрет для `authorization_env` в конфиге (имя может быть любым). |

## Сборка образа

В каталоге репозитория:

```powershell
docker build -t telemt-api-gateway:local .
```

## Запуск через Docker CLI

Пример для PowerShell (подставьте путь к своему `config.yaml`):

```powershell
docker run -d --name telemt-gateway `
  -p 8080:8080 `
  -v "C:\path\to\config.yaml:/etc/telemt-gateway/config.yaml:ro" `
  -e CONFIG_PATH=/etc/telemt-gateway/config.yaml `
  telemt-api-gateway:local
```

Проверка:

```powershell
Invoke-WebRequest -Uri http://127.0.0.1:8080/health -UseBasicParsing
Invoke-WebRequest -Uri http://127.0.0.1:8080/api/main_srv/health -UseBasicParsing
```

Второй запрос проксируется на `{base_url}/v1/health` для alias `main_srv`.

Остановка и удаление:

```powershell
docker stop telemt-gateway
docker rm telemt-gateway
```

## Запуск через Docker Compose

В репозитории есть [docker-compose.yml](../docker-compose.yml) и пример [config.compose.yaml](../config.compose.yaml) с `allow_all: true` и `base_url: http://host.docker.internal:9091` (Telemt на хосте).

```powershell
docker compose up -d --build
docker compose logs -f gateway
docker compose down
```

На старых Linux‑хостах, где нет `host.docker.internal`, замените `base_url` на IP хоста или добавьте сервис Telemt в тот же `docker-compose` и укажите его DNS‑имя.

## Проверка

| Сценарий | Ожидание |
|----------|----------|
| `GET /health` | `200`, JSON `{"status":"ok"}` |
| Разрешённый IP, корректный alias | ответ бэкенда (например `200` для `/v1/health`) |
| IP не в whitelist | `403`, JSON с `code: forbidden` |
| Неизвестный alias | `404`, JSON с `code: not_found` |
| Бэкенд недоступен | `502`, JSON с `code: bad_gateway` |
| `GET /metrics` | текст метрик Prometheus (при разрешённом IP) |

## Обновление и CI/CD

- **Образ**: пересоберите тег или подтяните новый из registry, затем `docker compose up -d --build` или `docker stop` / `docker run ...` с тем же volume конфига.
- **Конфиг**: отредактируйте файл на хосте и перезапустите контейнер (шлюз не перечитывает конфиг на лету).
- **Gitea Actions**: workflow [.gitea/workflows/docker.yaml](../.gitea/workflows/docker.yaml) выполняет `go test` и собирает Docker‑образ. Для пуша в registry задайте secrets:

  - `REGISTRY_IMAGE` — полное имя образа без тега, например `git.example.com/owner/telemt-api-gateway`
  - `REGISTRY_URL` — хост registry, например `git.example.com`
  - `REGISTRY_USER` / `REGISTRY_PASSWORD`

  Если secrets не заданы, образ только собирается в runner без push.

## Устранение неполадок

- **`403 forbidden` с хоста при `allow_all: false`**: добавьте CIDR клиента в `whitelist_cidrs`. Запросы из контейнера к самому себе идут с `127.0.0.1` — при необходимости добавьте `127.0.0.1/32`.
- **За reverse proxy**: укажите CIDR прокси в `trusted_proxies`, иначе whitelist видит IP прокси, а не клиента.
- **`502 bad_gateway`**: проверьте `base_url`, DNS в Docker‑сети и то, что Telemt слушает API (`[server.api].enabled=true` и корректный `listen`).
- **Сборка Go без Docker**: выполните `go mod tidy && go test ./...` в корне репозитория.