# telemt-api

HTTP‑шлюз на Go для [Telemt Control API](docs/API.md): один порт, **белый список IP (CIDR)**, маршруты вида `/api/{alias}/…` → `{base_url}/v1/…`, агрегация нескольких инстансов — [`/api/agg/…`](docs/AGGREGATE.md), метрики Prometheus на `/metrics`.

## Быстрый старт (Linux)

Предполагается установлены Docker и Docker Compose v2.

**Рекомендуется** брать уже собранный образ из Container Registry Gitea (после каждого push в репозиторий CI обновляет теги, в том числе `latest`):

```bash
# при необходимости (закрытый registry): логин Gitea + PAT с read:package
docker login git.shts.su

docker pull git.shts.su/denozord/telemt-api:latest
```

Конфиг возьмите из репозитория или создайте свой `config.yaml` (см. [config.example.yaml](config.example.yaml)):

```bash
git clone <url-репозитория> && cd telemt-api
cp config.example.yaml config.yaml
# отредактируйте config.yaml: servers, whitelist_cidrs или allow_all для разработки

docker run -d --name telemt-gateway \
  -p 8080:8080 \
  -v "$(pwd)/config.yaml:/etc/telemt-gateway/config.yaml:ro" \
  -e CONFIG_PATH=/etc/telemt-gateway/config.yaml \
  git.shts.su/denozord/telemt-api:latest

curl -sS http://127.0.0.1:8080/health
curl -sS http://127.0.0.1:8080/api/main_srv/health
```

Обновление образа: `docker pull git.shts.su/denozord/telemt-api:latest` и пересоздайте контейнер (`docker rm -f telemt-gateway` и снова `docker run …`).

### Compose

Тот же образ подтягивается из registry (без локальной сборки):

```bash
git clone <url-репозитория> && cd telemt-api
docker compose pull
docker compose up -d
docker compose logs -f gateway
```

### Локальная сборка образа

Если нужен образ из исходников на этой машине: `docker build -t telemt-api-gateway:local .` и в `docker run` укажите тег `telemt-api-gateway:local`. Подробнее — [docs/GATEWAY_RUN.md](docs/GATEWAY_RUN.md).

## Документация

| Документ | Содержание |
|----------|------------|
| **[docs/GATEWAY_RUN.md](docs/GATEWAY_RUN.md)** | Полная инструкция: конфиг, pull/registry, Docker CLI, Compose, CI/CD, неполадки |
| **[docs/API.md](docs/API.md)** | Контракт Telemt Control API (`/v1/…`) |
| **[docs/AGGREGATE.md](docs/AGGREGATE.md)** | Агрегирующие эндпоинты шлюза (`/api/agg/…`), CORS, кэш |
| **[docs/AGGREGATE_OPENAPI.yaml](docs/AGGREGATE_OPENAPI.yaml)** | OpenAPI 3 черновик для `/api/agg/*` (генерация типов для UI) |
| **[web/README.md](web/README.md)** | Web UI (SvelteKit + shadcn-svelte): установка, `PUBLIC_TELEMT_GATEWAY_URL`, Docker |
| **[docs/GEOIP.md](docs/GEOIP.md)** | GeoLite2 City (страна/город) и опционально ASN (номер AS, организация) для IP в `unique-ips` |

## Сборка и тесты без Docker

```bash
go mod tidy && go test ./...
```

## CI/CD

В репозитории: [.gitea/workflows/docker.yaml](.gitea/workflows/docker.yaml) — тесты Go, сборка и публикация образа в Container Registry Gitea (см. раздел «Обновление и CI/CD» в [docs/GATEWAY_RUN.md](docs/GATEWAY_RUN.md)).