Skip to content

# 25 — Deployment & Infrastructure (MicroDAO)

Deployment процес, середовища, інфраструктура, CI/CD, моніторинг

## 1. Purpose & Scope

Цей документ описує інфраструктуру розгортання та процеси деплою для:

- microdao (messenger + agents + governance + wallet);
- DAARION.city core (Second Me, Gift Fabric, Citizenship);
- інтеграційних модулів (Embassy, RWA, Energy Union, GREENFOOD та ін.);
- Event-driven шару (NATS/JetStream / Outbox).

Ціль:

- чітко визначити середовища (local/dev/staging/prod);
- описати основні компоненти інфра-стеку;
- стандартизувати CI/CD pipeline та керування міграціями;
- визначити моніторинг, логування, backup/restore.

## 2. Environments

### 2.1 Local

Призначення:

- швидка розробка;
- інтеграційні тести окремого розробника.

Особливості:

- Postgres (може бути Supabase local або Docker);
- NATS/JetStream локально (Docker);
- фронтенд (Next.js / React) — `localhost:3000`;
- backend/edge functions — `localhost:PORT`;
- спрощена конфігурація OAuth/Email.

### 2.2 Dev

Призначення:

- інтеграція гілок;
- тестування нових фіч командою.

Особливості:

- часто автодеплой з `develop` / `dev` гілки;
- нестабільне середовище, допускається breaking changes;
- окремі ресурси БД, NATS, storage.

### 2.3 Staging

Призначення:

- передпродакшн середовище, максимально наближене до прод;
- тестування релізів перед викоткою на prod;
- smoke-тести, регресія, перевірка міграцій.

Особливості:

- конфігурації максимально збігаються з prod;
- ті ж версії Postgres/NATS/Redis;
- мінімум тестових даних, максимально наближені сценарії.

### 2.4 Prod

Призначення:

- бойове середовище для реальних користувачів та агентів;
- висока доступність, резервування, SLA.

Особливості:

- реплікація БД;
- резервні копії (snapshots + PITR);
- горизонтальне масштабування критичних сервісів;
- жорсткі політики безпеки, rate limiting, WAF.

## 3. Core Infrastructure Components

### 3.1 Database Layer

- Postgres (Supabase / керований Postgres):
- основні таблиці: `users`, `teams`, `channels`, `messages`, `projects`, `tasks`, `agents`, `wallets`, `staking_ringk`, `payouts`, `rwa_inventory`, `embassy_*`, `access_keys`, `capabilities`, `bundles`, `audit_log`, `outbox_events`.
- схема й міграції описані в `27_database_schema_migrations.md`.

Рекомендації:

- один кластер на середовище (dev/staging/prod);
- не змішувати dev/staging/prod в одному кластері;
- використовувати read-replicas для prod (аналітика, довгі запити).

### 3.2 Event Bus

- NATS JetStream (або інший стейтовий event bus):
- теми (topics) з `Data Model & Event Catalog`;
- консьюмери: Wallet service, Gift Fabric, Embassies, Telemetry.

Роль:

- децентралізований шар подій;
- відв'язка інтерфейсу, агентів і бекенду;
- реалізація Outbox pattern (`outbox_events` → NATS).

### 3.3 Application Layer

- API Gateway / Edge Functions:
- REST/gRPC/API для frontend, агентів, інтеграцій;
- PEP (Policy Enforcement Point) для capability-check;

- валідація access keys, підписів Embassy, rate limiting.

- Domain Services (можуть бути edge functions / окремі сервіси):

- Messaging Service (channels/messages/followups);
- Projects/Tasks Service;
- Agent Orchestrator (agent_runs, router);
- Wallet & Payouts;
- Embassy Service;
- Governance Service.

### 3.4 Frontend

- SPA/SSR (React/Next.js):
- DAARION.city UI;
- microdao messenger + agents;
- admin-консоль (telemetry, управління платформи).

Рекомендації:

- окремі build'и для user-facing (місто) і admin/ops;
- environment-specific base URLs.

### 3.5 Object Storage

- зберігання файлів/документів/зображень:
- user uploads (файли в каналах, документи);
- логи агентів (якщо великі);
- snapshot-и моделей/конфігів (якщо потрібно).

## 4. High-level Topology

Текстовий опис (спрощено):

- Frontend (Web) → API Gateway
- API Gateway → Postgres / NATS / Services
- Agent Mesh ↔ API Gateway ↔ NATS
- Embassy Webhooks ↔ API Gateway ↔ NATS ↔ Services
- Observability Stack (Prometheus/Grafana/Logs) → читає метрики з усіх компонентів

(Опційно можна додати Mermaid-діаграму у цьому файлі.)

## 5. Deployment Workflows

### 5.1 Local

- `docker-compose` / Supabase local:
- `postgres`, `nats`, `minio` (опційно), `api`, `web`.
- Команди:
- `npm run dev` (web);
- `supabase db push` / `pnpm prisma migrate` / `golang-migrate up` (залежно від стеку);
- запуск background workers для Outbox → NATS.

### 5.2 Dev

Trigger:

- push в `develop` / `dev` гілку.

Кроки:

1. CI: `lint`, `tests`, `typecheck`.
2. Build:
3. web (static/SSR bundle);
4. backend/edge functions (docker image або окремі функції).
5. Deploy:
6. apply DB migrations;
7. деплой API/edge;
8. деплой web (dev URL).
9. Smoke-тести:
10. healthcheck endpoints;
11. простий сценарій (login → створити канал → відправити повідомлення).

### 5.3 Staging

Trigger:

- merge/push у `main` з тегом `rc-*` або окрема `release/*` гілка.

Кроки:

1. CI повторює dev-пайплайн.
2. DB migrations:
3. запуск у режимі dry-run (якщо підтримується);
4. застосування на staging.
5. Deploy API, workers, web (staging domain).
6. Інтеграційні тести:
7. агенти, Embassy вебхуки, payouts, RWA, governance flows.

### 5.4 Prod

Trigger:

- тег `vX.Y.Z` або manual approval релізу.

Кроки:

1. Freeze staging (ті самі артефакти).
2. Backup prod DB (snapshot).
3. Apply migrations на prod.
4. Deploy API/edge з поетапним rollout (canary / по одному інстансу).
5. Deploy web (атомарна заміна, rollback через попередній build).
6. Post-deploy чек-лист:
7. логін/чат;
8. ворк агента;
9. простий payout симуляційний (якщо є test mode);
10. кілька Embassy викликів у test-конфігурації.

## 6. Configuration & Environment Variables

Приклад розділів `.env` (загальні ключі):

### 6.1 Database

- `DB_HOST`
- `DB_PORT`
- `DB_NAME`
- `DB_USER`
- `DB_PASSWORD`
- `DB_SSLMODE` (prod: `require`)

### 6.2 NATS / Event Bus

- `NATS_URL`
- `NATS_USER`
- `NATS_PASSWORD`
- `NATS_STREAM_EVENTS` (ім'я стріму для event catalog)
- `NATS_CONSUMER_WALLET`
- `NATS_CONSUMER_EMBASSY`
- `NATS_CONSUMER_GIFT_FABRIC`

### 6.3 Auth / Security

- `JWT_SECRET` (для capability-token, якщо локально)
- `SESSION_SECRET`
- `E2EE_PUBLIC_KEY` / `E2EE_PRIVATE_KEY` (або інший механізм)
- `RATE_LIMIT_GLOBAL`
- `RATE_LIMIT_PER_KEY`

### 6.4 Embassy

- `EMBASSY_WEBHOOK_SECRET_ENERGY_UNION`
- `EMBASSY_WEBHOOK_SECRET_GREENFOOD`
- `EMBASSY_WEBHOOK_SECRET_WATER_UNION`
- `EMBASSY_WEBHOOK_SECRET_ESSENCE_STREAM`

### 6.5 Wallet / Chain

- `CHAIN_RPC_URL`
- `CHAIN_EXPLORER_URL`
- `WALLET_SAFE_ADDRESS` (якщо multi-sig)
- `WALLET_PRIVATE_KEY` (краще в KMS, не у .env)

## 7. Secrets Management

- Prod/staging secrets не зберігати у `.env` у репозиторії.
- Використовувати:
- KMS (GCP/AWS/Azure) або
- менеджер секретів (Vault, Doppler, SSM Parameter Store тощо).
- Workers/API при старті:
- тягнуть секрети з KMS/secret manager;
- кешують лише в пам'яті (не логувати).

Особливо чутливі:

- ключі Embassy Webhooks;
- wallet private keys / hot signer;
- JWT/Session secrets.

## 8. Database Migrations

Посилання: `27_database_schema_migrations.md`.

Правила:

1. Міграції ніколи не змінюють/ламають дані під час prod розгортання без попередніх data-migrations.
2. `up`/`down` повинні бути ідемпотентними (DROP IF EXISTS / CREATE IF NOT EXISTS).
3. Порядок виконання:
4. local: розробник запускає всі `000XXX_*.sql` + `seeds.sql`;
5. dev/staging/prod: CI/CD застосовує міграції у правильному порядку.

## 9. Event Bus & Outbox Pattern

- Event producer-и (API/Services) не відправляють події напряму в NATS у критичних шляхах — спочатку пишуть у `outbox_events`.
- Background worker:
- читає `outbox_events` з `processed=false`;
- публікує у NATS відповідний topic;
- позначає `processed=true`, `processed_at=NOW()`.

Це зменшує ймовірність втрати подій при часткових збоях.

## 10. Monitoring & Logging

### 10.1 Метрики

- API/Backend:
- latency per endpoint;
- error rate (5xx, 4xx);

- rate limiting triggers.

- DB:

- connections;
- slow queries;

- реплікація (lag).

- NATS/Event Bus:

- backlog per consumer;
- delivery errors;

- redeliveries.

- Agents:

- кількість запусків;
- середня тривалість run;
- помилки агента (LLM/tool errors).

### 10.2 Логи

- централізований збір (ELK / Loki / Cloud Logging);
- кореляційні ID:
- `X-Request-ID` на кожен HTTP-запит;
- propagation у NATS payload (trace_id / correlation_id).

## 11. Backups & Restore

### 11.1 Backups

- Prod:
- щоденні повні snapshots;
- WAL / PITR (Point-In-Time Recovery) на 7–30 днів;
- Staging:
- щоденні або раз на 2–3 дні (за потреби).

### 11.2 Restore Policy

- тестовий restore на окремий тимчасовий кластер мінімум раз на місяць;
- документований сценарій:
- відновлення в новий кластер;
- redirect трафіку (якщо потрібно).

## 12. Rollout Strategies

### 12.1 API/Backend

- Canary:
- невеликий відсоток трафіку на новий реліз;
- моніторинг помилок/латентності;

- поступове збільшення.

- Blue-Green:

- parallel stack (blue/green);
- перемикання через load balancer/DNS.

### 12.2 Frontend

- атомарний switch build'ів (immutable artifacts);
- rollback = переключення на попередній build.

### 12.3 Feature Flags

- складні зміни (особливо агенти, Gift Fabric, RWA) — за feature flags:
- flags зберігаються в БД або у спеціальному конфіг-сервісі;
- викочуються спочатку на dev/staging, потім для частини користувачів у prod.

## 13. CI/CD Pipeline (Reference)

Псевдо-YAML для орієнтира:

    name: deploy

    on:
      push:
        branches: [develop, main]
        tags: ['v*']

    jobs:
      build-and-test:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - uses: actions/setup-node@v4
            with:
              node-version: '20'
          - run: npm ci
          - run: npm run lint
          - run: npm test
          - run: npm run build:web
          - run: npm run build:api

      migrate-and-deploy:
        needs: build-and-test
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          - name: Run DB migrations
            run: |
              ./scripts/migrate.sh up
          - name: Deploy API
            run: |
              ./scripts/deploy_api.sh
          - name: Deploy Web
            run: |
              ./scripts/deploy_web.sh

## 14. Завдання для Cursor

    You are a senior DevOps engineer. Set up deployment infrastructure using:
    - 25_deployment_infrastructure.md
    - 27_database_schema_migrations.md
    - 05_coding_standards.md

    Tasks:
    1) Create docker-compose.yml for local development (postgres, nats, minio).
    2) Create CI/CD pipeline configuration (GitHub Actions / GitLab CI).
    3) Create deployment scripts (migrate.sh, deploy_api.sh, deploy_web.sh).
    4) Set up environment variable templates (.env.example).
    5) Create monitoring dashboard configuration (Grafana / Prometheus).

    Output:
    - list of modified files
    - diff
    - summary

## 15. Результат

Після впровадження цієї інфраструктури:

- чітко визначені середовища та процеси деплою;
- стандартизований CI/CD pipeline;
- готовність до масштабування та production deployment;
- моніторинг та логування для всіх компонентів;
- надійні backup/restore процеси.

Версія: 1.0
Останнє оновлення: 2024-11-14