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.
+
--- a/docs/public/architecture-overview.md
+++ b/docs/public/architecture-overview.md
@@ -0,0 +1,36 @@
+# Architecture Overview
+
+## Сервери
+| Нода | Роль | Розташування |
+|------|------|--------------|
+| NODE1 | Production + Gateway | Hetzner GEX44 (144.76.224.179) |
+| NODE2 | Development / Multimodal | MacBook Pro M4 Max |
+
+## Головні сервіси
+- **City Service (FastAPI)** — міські кімнати, Matrix bootstrap.
+- **Matrix Gateway** — видача токенів, presence heartbeat.
+- **Matrix Presence Aggregатор** — збір online + агентів → SSE.
+- **Agents Service / MicroDAO Service** — профілі агентів та DAO.
+- **Next.js фронтенд** — `apps/web`, Vite dev server.
+
+## Потік користувача
+1. Login через Auth Service.
+2. `/city` → City Map з live presence.
+3. `/city/[slug]` → Matrix Chat (matrix-js-sdk).
+4. Presence Heartbeat → Matrix Gateway → Synapse.
+5. Aggregator читає presence + agents та транслює SSE.
+
+## Мережа
+- Docker network `dagi-network`.
+- Nginx/Traefik на 80/443.
+- Matrix Synapse всередині мережі, доступ через `app.daarion.space` проксі.
+
+## Дані
+- PostgreSQL (`dagi-postgres`).
+- Redis (presence/cache).
+- NATS JetStream (події).
+
+## Моніторинг
+- Prometheus, Grafana (локально на NODE1).
+- Infra Automation Pack додає Loki + Promtail.
+
--- a/docs/public/daiS_daos_overview.md
+++ b/docs/public/daiS_daos_overview.md
@@ -0,0 +1,21 @@
+# DAIS & DAOS Overview
+
+DAIS (Decentralized AI Identity Stack) — стандарт для агентів DAARION. DAOS — їхня система автономності.
+
+## DAIS Модулі
+1. **CORE** — цифрова ідентичність, ключі, профіль.
+2. **VIS** — аватар, voice, мультимедійні прояви.
+3. **COG** — LLM + пам'ять, RAG, аналітика.
+4. **ACT** — Matrix, DAO, зовнішні API, wallet.
+
+## DAOS
+- Регламентує життєвий цикл агента.
+- Визначає permissions, audit trail, self-upgrade.
+- Працює поверх Node Registry та MicroDAO governance.
+
+## План впровадження
+1. **Infra Automation Pack v1** → стабільна база для документації й логів.
+2. **Agent Presence v2** → агенти + DAIS статуси.
+3. **DAIS Framework** → реєстрація та керування агентами.
+4. **DAOS Governance** → мульти-агентні DAO, MetaMorph.
+
--- a/docs/public/getting-started.md
+++ b/docs/public/getting-started.md
@@ -0,0 +1,40 @@
+# Getting Started
+
+Цей гайд допоможе розгорнути DAARION локально або на сервері.
+
+## 1. Клонування репозиторію
+```bash
+git clone https://github.com/IvanTytar/microdao-daarion.git
+cd microdao-daarion
+```
+
+## 2. Необхідні залежності
+- Docker / Docker Compose 1.29+
+- Node.js 20+
+- Python 3.11+
+- pnpm або npm (для фронтенду)
+
+## 3. Основні команди
+```bash
+# Бекенд сервіси
+docker compose up -d
+
+# City frontend (Next.js)
+cd apps/web
+pnpm install
+pnpm dev
+```
+
+## 4. Ноди
+- **NODE1 (production):** `/opt/microdao-daarion`, IP `144.76.224.179`.
+- **NODE2 (dev MacBook):** `/Users/apple/github-projects/microdao-daarion`.
+
+## 5. CI/CD
+1. Код → `main`.
+2. `git pull` на NODE1.
+3. `docker compose up -d --build`.
+
+## 6. Корисні скрипти
+- `smoke.sh` — базовий health check.
+- `scripts/docs/docs_sync.sh` — автоматичний pull (див. Infra Pack).
+
--- a/docs/public/index.md
+++ b/docs/public/index.md
@@ -0,0 +1,21 @@
+# DAARION.city — MicroDAO Infrastructure
+
+DAARION.city — це міське середовище для мікро-спільнот з агентами, Matrix-чатами та модульною інфраструктурою. Ця документація описує ядро платформи, архітектурні принципи та дорожню карту розвитку.
+
+## Чим є DAARION
+- **Мультисерверна інфраструктура:** NODE1 (продакшн) + NODE2 (дев) зі спільним кодовим репозиторієм.
+- **Міські сервіси:** City Service, MicroDAO Service, Agents Core, Matrix Gateway.
+- **Realtime-шар:** Matrix presence, Global Presence Aggregator, 2D City Map.
+- **Дорога до DAIS/DAOS:** Ідентичності агентів, агенти-горожани, автономні модулі.
+
+## Як читати документацію
+- Розділ **Getting Started** допоможе швидко підняти репозиторій локально.
+- **Architecture Overview** описує основні сервіси, мережеві правила й деплой.
+- **DAIS & DAOS** — вступ до наступної фази агентів.
+- **Internal** — інфраструктура, специфікації, стандарти (лише для внутрішнього користування).
+
+## Поточний статус
+- Production-ready основний стек (FastAPI + React + Matrix).
+- City Map з live presence та агентами — впроваджено.
+- Наступний крок: Infra Automation Pack v1 (документація, логінг, sync).
+