# SigNoz для HAN Chat

Одноузловой self-hosted SigNoz на Ubuntu 24.04 через официальный
`foundryctl` и Docker Compose.

Сетевая модель:

- VM SigNoz: `192.168.0.5`;
- OTLP/gRPC: `192.168.0.5:4317`, только приватная сеть;
- OTLP/HTTP: `192.168.0.5:4318`, только приватная сеть;
- UI/API: `127.0.0.1:8080`, доступ только через SSH-туннель;
- ClickHouse, PostgreSQL и ClickHouse Keeper наружу не публикуются.

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

- минимум 4 GiB RAM (для эксплуатации лучше 8 GiB);
- минимум 30 GiB свободного диска для старта;
- временный исходящий доступ в интернет на время установки и обновлений;
- рабочий приватный интерфейс с адресом `192.168.0.5`;
- доступ к ВМ по SSH через приватную сеть до отключения внешнего IP.

## Установка

Скопируйте эту папку на ВМ, например в `/opt/signoz`:

```bash
rsync -rltD --no-perms --no-owner --no-group -ivc --delete \
  --exclude='.env' \
  --exclude='dist/' \
  --exclude='secrets/' \
  --exclude='pours/' \
  --exclude='casting.yaml.lock' \
  -e "ssh -i ~/.ssh/hansel-private" \
  /mnt/c/Users/MI/Documents/Assistent/HAN_chat_specification/codebase/Signoz/ \
  root@135.106.166.7:/opt/signoz/
```

Исключения `pours/` и `casting.yaml.lock` обязательны при повторной
синхронизации: Foundry создаёт их непосредственно на VM. Без исключений
`rsync --delete` удалит runtime-конфигурацию, которой нет локально.

На ВМ:

```bash
cd /opt/signoz
sed -i 's/\r$//' scripts/*.sh
chmod +x scripts/*.sh

sudo ./scripts/05-configure-private-network.sh
sudo PRIVATE_IP=192.168.0.5 ./scripts/00-check-vm.sh
sudo ./scripts/10-install-docker.sh
sudo PRIVATE_IP=192.168.0.5 ./scripts/20-deploy-signoz.sh
```

После запуска создайте первого администратора и организацию SigNoz. До этого
OpAMP не выдаст ingester рабочую OTLP-конфигурацию, хотя контейнер будет
выглядеть запущенным.

Адреса `127.0.0.1` всегда означают loopback той машины, на которой
интерпретируются. HAN_CHAT имеет приватный адрес `192.168.0.1`, а SigNoz —
`192.168.0.5`. UI слушает `127.0.0.1:8080` именно на VM SigNoz.

Для постоянного доступа после удаления публичного IP SigNoz добавьте в
`C:\Users\MI\.ssh\config`:

```sshconfig
Host han-jump
    HostName 135.106.164.58
    User root
    IdentityFile C:\Users\MI\.ssh\hansel

Host signoz-private
    HostName 192.168.0.5
    User root
    IdentityFile C:\Users\MI\.ssh\hansel-private
    ProxyJump han-jump
```
Затем ssh signoz-ui -N

(устаревшее: 
На рабочем компьютере откройте туннель до SigNoz через HAN_CHAT:

```powershell
ssh -L 8080:127.0.0.1:8080 signoz-private -N
```
)
Маршрут SSH: Windows → публичный адрес HAN_CHAT → `192.168.0.5:22`.
Назначение `127.0.0.1:8080` в `-L` открывает конечная VM SigNoz, а не
HAN_CHAT.

Откройте `http://127.0.0.1:8080`, создайте администратора/организацию, затем
на VM выполните:

```bash
cd /opt/signoz
sudo docker compose -f pours/deployment/compose.yaml restart ingester
sudo ./scripts/30-verify-signoz.sh
```

После успешной проверки настройте host firewall. Подставьте реальный приватный
IP backend:

```bash
sudo OTLP_SOURCE=192.168.0.1 \
  ADMIN_CIDR=192.168.0.0/24 \
  PRIVATE_IP=192.168.0.5 \
  ./scripts/40-configure-firewall.sh
```

Затем выполните чек-лист из [docs/NETWORK.md](docs/NETWORK.md), подключите
backend по [docs/BACKEND_OTLP.md](docs/BACKEND_OTLP.md) и только после
успешной end-to-end проверки удалите внешний IP.

## Проверка и управление

```bash
cd /opt/signoz
sudo ./scripts/30-verify-signoz.sh
sudo docker compose -f pours/deployment/compose.yaml ps
sudo docker compose -f pours/deployment/compose.yaml logs --tail=200
sudo docker compose -f pours/deployment/compose.yaml restart
```

Не редактируйте `pours/` вручную: Foundry перегенерирует эту папку.
Постоянные изменения вносятся в `casting.yaml`, после чего снова запускается
`20-deploy-signoz.sh`.

Обновление требует временного доступа к Docker Hub, GitHub и SigNoz:

```bash
cd /opt/signoz
sudo ./scripts/20-deploy-signoz.sh
```

Перед обновлением сделайте snapshot диска ВМ. Данные находятся в Docker
volumes ClickHouse и PostgreSQL; `docker compose down -v` удалит их и поэтому
для штатного обслуживания запрещён.

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

- [NETWORK.md](docs/NETWORK.md) — сеть, группа безопасности, SSH-туннель;
- [BACKEND_OTLP.md](docs/BACKEND_OTLP.md) — передача телеметрии HAN Chat;
- [SIGNOZ_RUNBOOK.md](docs/SIGNOZ_RUNBOOK.md) — что смотреть в SigNoz;
- [MVP_DASHBOARDS_ALERTS.md](docs/MVP_DASHBOARDS_ALERTS.md) — versioned
  спецификация первых dashboards и alerts.