Add Infra Automation Pack v1: docs infrastructure, logging stack, sync scripts

2025-11-27 09:29:42 -08:00
parent 6bd769ef40
commit 2a6112fc42
22 changed files with 595 additions and 0 deletions
--- a/docs/internal/infra/INFRA_AUTOMATION_PACK_V1.md
+++ b/docs/internal/infra/INFRA_AUTOMATION_PACK_V1.md
@@ -0,0 +1,72 @@
+# Infra Automation Pack v1
+
+Infra Automation Pack v1 стандартизує документацію, логування та синхронізацію репозиторію на всіх нодах DAARION.
+
+## 1. Docs
+- Структура `/docs/public` + `/docs/internal` + `mkdocs.yml`.
+- GitHub Actions `.github/workflows/docs.yml` збирає MkDocs і публікує сайт у гілку `gh-pages` (GitHub Pages увімкнути вручну).
+- Dev залежності: `requirements-dev.txt` (`mkdocs`, `mkdocs-material`).
+
+### Як запускається локально
+```bash
+pip install -r requirements-dev.txt
+mkdocs serve
+```
+
+## 2. Logging Stack
+- Конфігурації в `infra/logging/`:
+  - `docker-compose.logging.yml`
+  - `loki-config.yml`
+  - `promtail-config.yml`
+  - `grafana-provisioning/...`
+- Запуск на NODE1 / NODE2:
+```bash
+cd /opt/microdao-daarion
+sudo docker compose -f infra/logging/docker-compose.logging.yml up -d
+```
+- Доступ:
+  - Loki: `http://<node>:3100`
+  - Grafana: `http://<node>:3000` (логін admin / пароль налаштувати після першого запуску).
+
+## 3. Daily Log Summary
+- Скрипти `scripts/logs/generate_daily_summary.py` + `scripts/logs/daily_log_summary.sh`.
+- Параметри через env (`LOKI_URL`, `LAB_NOTES_DIR`).
+- Вихідні файли: `lab-notes/log_summary_YYYY-MM-DD.md`.
+
+### Приклад cron-запису
+```
+0 6 * * * /opt/microdao-daarion/scripts/logs/daily_log_summary.sh >> /var/log/daarion_daily_log_summary.log 2>&1
+```
+
+### GitHub Actions (опціонально)
+- `.github/workflows/log-notes.yml` — ручний запуск для пушу `lab-notes/` у `main`.
+
+## 4. Docs Sync on Nodes
+- Скрипт `scripts/docs/docs_sync.sh` виконує `git fetch` / `git pull` для `origin/main`.
+
+### systemd unit (шаблон)
+```
+[Unit]
+Description=Sync DAARION repo (docs + code)
+After=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=/opt/microdao-daarion/scripts/docs/docs_sync.sh
+User=daarion
+Group=daarion
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### Cron-варіант
+```
+*/15 * * * * /opt/microdao-daarion/scripts/docs/docs_sync.sh >> /var/log/daarion_docs_sync.log 2>&1
+```
+
+## 5. Подальші кроки
+- Додати Jupyter-звіти (`lab-notes/*.ipynb`).
+- Розширити Grafana dashboard (`infra/logging/grafana-provisioning/dashboards`).
+- Інтегрувати Node Registry + DAIS метадані (agents vs nodes).
+
--- a/docs/internal/infra/monitoring_overview.md
+++ b/docs/internal/infra/monitoring_overview.md
@@ -0,0 +1,25 @@
+# Monitoring Overview
+
+## Поточні компоненти
+- **Prometheus** — збирає метрики сервісів (router, gateway, swapper).
+- **Grafana** — dashboards (NODE1:3000).
+- **node-exporter** (planned) — системні метрики.
+
+## Що додає Infra Automation Pack
+- **Loki + Promtail** — централізовані логи Docker та системи.
+- **Daily Log Summary** — markdown-звіти з ключовими подіями.
+- **Docs Sync** — гарантує, що інфраструктурні інструкції однакові на всіх нодах.
+
+## Мережеві порти
+| Сервіс | Порт |
+|--------|------|
+| Prometheus | 9090 |
+| Grafana | 3000 |
+| Loki | 3100 |
+| Promtail | 9080 |
+
+## Наступні кроки
+1. Додати алерти (Alertmanager).
+2. Інтегрувати NATS JetStream події в Loki (через Promtail pipeline).
+3. Створити спільний Grafana dashboard для City Map / Agent Presence.
+
--- a/docs/internal/infra/nodes_registry_v0.md
+++ b/docs/internal/infra/nodes_registry_v0.md
@@ -0,0 +1,24 @@
+# Nodes Registry v0 (Draft)
+
+## Мета
+Створити єдину базу даних про всі вузли (NODE1, NODE2, майбутні регіони) з метою:
+- відстеження конфігурацій і версій ПЗ;
+- автоматизації Node Join Protocol;
+- розподілу завдань агентів та сервісів.
+
+## Поточний статус
+- NODE1 та NODE2 ведуться вручну в INFRASTRUCTURE.md.
+- Автоматичного API немає.
+
+## План
+1. **Схема таблиці `nodes`:**
+   - `node_id`, `hostname`, `role`, `env`, `ip_public`, `ip_private`, `gpu`, `status`.
+2. **Service:** FastAPI (Node Registry) з CRUD + auth.
+3. **Sync агенти:** кожен node-agent шле heartbeat в регістр через NATS.
+4. **UI:** вкладка "Nodes" в admin-панелі.
+
+## Інтеграції
+- Node Join Protocol (draft).
+- DAIS (CORE) — зберігає прив'язку agent → node.
+- Infra Automation Pack — використовує registry для автоматизації sync/логів.
+
--- a/docs/internal/specs/city_map_spec.md
+++ b/docs/internal/specs/city_map_spec.md
@@ -0,0 +1,18 @@
+# City Map Spec (2D MVP)
+
+## Дані
+- Таблиця `city_rooms`: `map_x`, `map_y`, `map_w`, `map_h`, `room_type`, `zone`, `color`, `icon`.
+- API `GET /city/map` → `{ config, rooms[] }` з кешем (30 c).
+- Presence з aggregator додає `online`, `typing`, `agents`.
+
+## Фронтенд
+- Компонент `CityMap` (Next.js) з SVG / CSS grid.
+- Тайли кімнат + online indicator + typing.
+- Agent badges (до 3, потім `+N`).
+- Перемикач "Map / List" на `/city`.
+
+## Подальші кроки
+1. **Zone layers:** відображення районів міста.
+2. **Events overlay:** показ останніх подій (NATS) на мапі.
+3. **3D режим:** pivot до WebGL після стабілізації presence v2.
+
--- a/docs/internal/specs/matrix_presence_aggregator.md
+++ b/docs/internal/specs/matrix_presence_aggregator.md
@@ -0,0 +1,40 @@
+# Matrix Presence Aggregator Spec (v2)
+
+## Огляд
+Aggregator збирає дані з Matrix Synapse + PostgreSQL (agents) і транслює їх через REST/SSE.
+
+## Потік даних
+1. `rooms_source` читає `city_rooms` (`matrix_room_id`, координати).
+2. `agents_source` читає `agents` (online/busy/offline, `current_room_id`).
+3. `MatrixClient` полить членів кімнат (`/_matrix/client/v3/rooms/.../members`).
+4. Presence API (`/_matrix/client/v3/presence/.../status`) → з Heartbeat hook у фронті.
+5. Snapshot → `GET /presence/summary`, `GET /presence/stream` (SSE).
+
+## Формат Snapshot
+```json
+{
+  "type": "presence_update",
+  "timestamp": "2025-11-27T15:10:00Z",
+  "city": {
+    "online_total": 7,
+    "rooms_online": 4,
+    "agents_online": 3
+  },
+  "rooms": [
+    {
+      "room_id": "room_city_general",
+      "matrix_room_id": "!abc:daarion.space",
+      "online": 5,
+      "typing": 1,
+      "agents": [ { "agent_id": "ag_atlas", "status": "online" } ]
+    }
+  ],
+  "agents": [ ... ]
+}
+```
+
+## План розвитку
+- Presence diffs (щоб зменшити трафік SSE).
+- Aggregated analytics (average online per room).
+- Події для Agent Presence v2 (агент перемістився).
+
--- a/docs/internal/specs/node_join_protocol_draft.md
+++ b/docs/internal/specs/node_join_protocol_draft.md
@@ -0,0 +1,24 @@
+# Node Join Protocol (Draft)
+
+## Цілі
+- Дозволити новим нодам приєднуватися до мережі DAARION.
+- Автоматично налаштовувати агенти, Matrix аккаунти, інфраструктуру.
+
+## Етапи
+1. **Registration:** admin додає запис у Node Registry (`pending`).
+2. **Bootstrap Script:** node виконує `scripts/bootstrap-node.sh`, який:
+   - встановлює Docker, git, базові сервіси;
+   - додає SSH ключ;
+   - запускає docs-sync.
+3. **Validation:** node-agent передає метрики через NATS.
+4. **Activation:** статус `active`, нода отримує роль (prod/dev/edge).
+
+## Безпека
+- Всі запити підписані (JWT + node secret).
+- Node agent працює від окремого користувача `daarion`.
+
+## TODO
+- Фіналізувати API Node Registry.
+- Додати інтеграцію з DAIS (agent identity vs node identity).
+- Автоматизувати видачу TLS/SSL через ACME.
+