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/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,38 @@
+name: Build and Deploy Docs
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yml"
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install mkdocs and dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-dev.txt
+
+      - name: Build docs
+        run: |
+          mkdocs build --clean
+
+      - name: Deploy to GitHub Pages
+        if: ${{ github.ref == 'refs/heads/main' }}
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          publish_branch: gh-pages
--- a/.github/workflows/log-notes.yml
+++ b/.github/workflows/log-notes.yml
@@ -0,0 +1,30 @@
+name: Push Lab Notes
+
+on:
+  workflow_dispatch:
+
+jobs:
+  push-lab-notes:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure git user
+        run: |
+          git config user.name "DAARION Bot"
+          git config user.email "bot@daarion.city"
+
+      - name: Commit lab-notes
+        run: |
+          git add lab-notes/
+          if git diff --cached --quiet; then
+            echo "No lab-notes changes"
+            exit 0
+          fi
+          git commit -m "chore: update lab-notes"
+          git push origin HEAD:main
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
--- 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).
+
--- a/infra/logging/docker-compose.logging.yml
+++ b/infra/logging/docker-compose.logging.yml
@@ -0,0 +1,37 @@
+version: "3.8"
+
+services:
+  loki:
+    image: grafana/loki:2.9.0
+    container_name: loki
+    command: -config.file=/etc/loki/config/config.yml
+    volumes:
+      - ./loki-config.yml:/etc/loki/config/config.yml:ro
+      - loki-data:/loki
+    ports:
+      - "3100:3100"
+    restart: unless-stopped
+
+  promtail:
+    image: grafana/promtail:2.9.0
+    container_name: promtail
+    command: -config.file=/etc/promtail/config.yml
+    volumes:
+      - ./promtail-config.yml:/etc/promtail/config.yml:ro
+      - /var/log:/var/log:ro
+      - /var/lib/docker/containers:/var/lib/docker/containers:ro
+    restart: unless-stopped
+
+  grafana:
+    image: grafana/grafana:10.4.0
+    container_name: grafana
+    ports:
+      - "3000:3000"
+    volumes:
+      - grafana-data:/var/lib/grafana
+      - ./grafana-provisioning:/etc/grafana/provisioning
+    restart: unless-stopped
+
+volumes:
+  loki-data:
+  grafana-data:
--- a/infra/logging/grafana-provisioning/dashboards/daarion-logs.json
+++ b/infra/logging/grafana-provisioning/dashboards/daarion-logs.json
@@ -0,0 +1,23 @@
+{
+  "title": "DAARION Logs",
+  "schemaVersion": 38,
+  "version": 1,
+  "panels": [
+    {
+      "type": "logs",
+      "title": "Recent Logs",
+      "gridPos": { "x": 0, "y": 0, "w": 24, "h": 10 },
+      "options": {
+        "dedupStrategy": "none",
+        "showLabels": true,
+        "wrapLogMessage": true
+      },
+      "targets": [
+        {
+          "datasource": { "type": "loki", "uid": "loki" },
+          "expr": "{job=\"docker\"}"
+        }
+      ]
+    }
+  ]
+}
--- a/infra/logging/grafana-provisioning/datasources/loki.yaml
+++ b/infra/logging/grafana-provisioning/datasources/loki.yaml
@@ -0,0 +1,9 @@
+apiVersion: 1
+
+datasources:
+  - name: Loki
+    type: loki
+    access: proxy
+    url: http://loki:3100
+    isDefault: true
+    editable: true
--- a/infra/logging/loki-config.yml
+++ b/infra/logging/loki-config.yml
@@ -0,0 +1,43 @@
+auth_enabled: false
+
+server:
+  http_listen_port: 3100
+
+ingester:
+  lifecycler:
+    address: 127.0.0.1
+    ring:
+      kvstore:
+        store: inmemory
+      replication_factor: 1
+  chunk_idle_period: 5m
+  chunk_retain_period: 30s
+  max_transfer_retries: 0
+
+schema_config:
+  configs:
+    - from: 2020-10-24
+      store: boltdb-shipper
+      object_store: filesystem
+      schema: v11
+      index:
+        prefix: index_
+        period: 24h
+
+storage_config:
+  boltdb_shipper:
+    active_index_directory: /loki/index
+    shared_store: filesystem
+  filesystem:
+    directory: /loki/chunks
+
+limits_config:
+  ingestion_rate_mb: 10
+  max_query_series: 10000
+
+chunk_store_config:
+  max_look_back_period: 0s
+
+table_manager:
+  retention_deletes_enabled: true
+  retention_period: 168h
--- a/infra/logging/promtail-config.yml
+++ b/infra/logging/promtail-config.yml
@@ -0,0 +1,26 @@
+server:
+  http_listen_port: 9080
+  grpc_listen_port: 0
+
+positions:
+  filename: /tmp/positions.yaml
+
+clients:
+  - url: http://loki:3100/loki/api/v1/push
+
+scrape_configs:
+  - job_name: system
+    static_configs:
+      - targets:
+          - localhost
+        labels:
+          job: varlogs
+          __path__: /var/log/*.log
+
+  - job_name: docker
+    static_configs:
+      - targets:
+          - localhost
+        labels:
+          job: docker
+          __path__: /var/lib/docker/containers/*/*-json.log
--- a/lab-notes/.gitignore
+++ b/lab-notes/.gitignore
@@ -0,0 +1,2 @@
+*.ipynb
+*.html
--- a/lab-notes/README.md
+++ b/lab-notes/README.md
@@ -0,0 +1,6 @@
+# Lab Notes
+
+Ця директорія містить щоденні лог-дайджести (`log_summary_YYYY-MM-DD.md`) та розширені ноутбуки.
+
+Файли генеруються скриптом `scripts/logs/daily_log_summary.sh` і можуть бути комічені вручну або через GitHub Actions (`log-notes.yml`).
+
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -0,0 +1,32 @@
+site_name: DAARION Documentation
+site_url: https://IvanTytar.github.io/microdao-daarion/
+theme:
+  name: material
+  language: en
+  features:
+    - navigation.sections
+    - navigation.instant
+    - content.code.copy
+nav:
+  - Home: public/index.md
+  - Getting Started: public/getting-started.md
+  - Architecture: public/architecture-overview.md
+  - DAIS & DAOS: public/daiS_daos_overview.md
+  - Internal:
+      - Infra:
+          - Infra Automation Pack v1: internal/infra/INFRA_AUTOMATION_PACK_V1.md
+          - Monitoring Overview: internal/infra/monitoring_overview.md
+          - Nodes Registry v0: internal/infra/nodes_registry_v0.md
+      - Specs:
+          - Matrix Presence Aggregator: internal/specs/matrix_presence_aggregator.md
+          - City Map Spec: internal/specs/city_map_spec.md
+          - Node Join Protocol (Draft): internal/specs/node_join_protocol_draft.md
+markdown_extensions:
+  - admonition
+  - codehilite
+  - toc:
+      permalink: true
+  - footnotes
+  - attr_list
+docs_dir: docs
+site_dir: site
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -0,0 +1,2 @@
+mkdocs==1.5.3
+mkdocs-material==9.5.18
--- a/scripts/docs/docs_sync.sh
+++ b/scripts/docs/docs_sync.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_DIR="${REPO_DIR:-/opt/microdao-daarion}"
+BRANCH="${SYNC_BRANCH:-main}"
+
+cd "$REPO_DIR"
+
+if [ ! -d .git ]; then
+  echo "[docs-sync] Missing git repo in $REPO_DIR" >&2
+  exit 1
+fi
+
+echo "[docs-sync] Fetching origin/$BRANCH"
+git fetch origin "$BRANCH"
+
+LOCAL=$(git rev-parse @)
+REMOTE=$(git rev-parse "origin/$BRANCH")
+
+if [ "$LOCAL" = "$REMOTE" ]; then
+  echo "[docs-sync] Already up to date"
+  exit 0
+fi
+
+echo "[docs-sync] Updating from origin/$BRANCH"
+git pull --ff-only origin "$BRANCH"