microdao-daarion/PRODUCTION-DEPLOYMENT-GUIDE.md

# 🚀 Production Deployment Guide

**Дата:** 2026-01-10  
**Версія:** 1.0.0  
**Статус:** Production-ready

---

## ✅ Pre-flight Checklist

### Архітектура (перевірено)
- ✅ Matrix = control-plane
- ✅ NATS JetStream = data-plane
- ✅ Worker Daemon з capability routing
- ✅ Memory Service як write/retrieval boundary
- ✅ Postgres = truth / Qdrant = index

---

## 🔐 Крок 1: Atomic генерація секретів

**ВИКОНАТИ ОДНИМ СЕТОМ, без часткових деплоїв**

```bash
cd infrastructure/auth
./generate-all-secrets.sh
```

**Результат:**
- `secrets/nats-operator.jwt` — NATS operator JWT
- `secrets/nats-system-account.jwt` — System account JWT
- `secrets/nats-*.jwt` — User accounts (memory-service, worker-daemon, matrix-gateway)
- `secrets/qdrant-keys.txt` — Qdrant API keys
- `secrets/memory-jwt-secret.txt` — Memory Service JWT secret

**⚠️ КРИТИЧНО:**
1. Збережіть `secrets/` в безпечне місце
2. Завантажте секрети в Vault
3. НЕ комітьте `secrets/` в Git!

---

## 🔒 Крок 2: Auth Enforcement

**Перевірка, що всі сервіси вимагають auth:**

```bash
./infrastructure/auth/enforce-auth.sh
```

**Очікуваний результат:**
- ✅ NATS operator JWT налаштовано
- ✅ Memory Service JWT secret існує
- ✅ Qdrant API keys Secret існує
- ✅ Memory Service відхиляє запити без JWT

**Якщо перевірки не пройдено:**
1. Завантажте секрети в Vault
2. Оновіть External Secrets Operator
3. Застосуйте auth конфігурації

---

## 🧪 Крок 3: Smoke-test (5 хв)

**Базові перевірки:**

```bash
# Перевірка NATS
kubectl get pods -n nats

# Перевірка streams
kubectl exec -n nats nats-0 -- wget -qO- http://localhost:8222/jsz | python3 -m json.tool | grep streams

# Перевірка Memory Service
kubectl get pods -n daarion -l app=memory-service
```

**Очікування:**
- NATS: Running
- Streams: 4+ streams створено
- Memory Service: Running (опціонально)

---

## 🧪 Крок 4: Full Flow Test (must-pass)

**Запуск повного тесту:**

```bash
./infrastructure/test-full-flow.sh
```

**Очікуваний результат:**
1. ✅ NATS JetStream: Running
2. ✅ NATS Streams: 4+ streams
3. ✅ Job creation via NATS: Success
4. ✅ Streams verification: All found

**Якщо тест провалено:**
- Перевірте логи: `kubectl logs -n nats nats-0`
- Перевірте streams: `kubectl exec -n nats nats-0 -- wget -qO- http://localhost:8222/jsz`

---

## 📊 Крок 5: Observability

### Prometheus Alerting Rules

```bash
kubectl apply -f infrastructure/observability/prometheus-rules.yaml
```

**Алерти:**
- `NATSOnlineBacklogHigh` — backlog > 1000 (critical)
- `NATSRedeliveriesSpike` — redeliveries > 100/min (warning)
- `WorkerOffline` — worker offline > 2 min (critical)
- `WorkerEmbedLatencyHigh` — P95 > 500ms (warning)

### Matrix Alerts Bridge

```bash
# Налаштування Matrix ops room
export MATRIX_HOMESERVER=https://matrix.org
export MATRIX_USER=@ops:matrix.org
export MATRIX_PASSWORD=password
export MATRIX_OPS_ROOM_ID=!ops:matrix.org

# Запуск bridge
python3 infrastructure/observability/matrix-alerts-bridge.py
```

**Результат:**
- Алерти з Prometheus → Matrix `#ops.alerts`
- Критичні алерти → негайне повідомлення
- Попередження → щоденний дайджест

---

## 📋 Крок 6: Policy Layer для пам'яті

**Документація:** `infrastructure/memory-policy/memory-policy-engine.md`

**Ключові правила:**
- Що запам'ятовувати в long-term memory
- Хто має право писати "факт"
- Як підтверджується / видаляється пам'ять
- Retention policies

**Реалізація:**
- Policy rules в Postgres (`memory_policy_rules` table)
- Policy Engine в Memory Service
- User feedback механізм

---

## 🎯 Production Readiness Checklist

### Критичні (must-have)
- [ ] Всі секрети згенеровано та завантажено в Vault
- [ ] Auth enforcement активний (перевірка через `enforce-auth.sh`)
- [ ] Smoke-test пройдено
- [ ] Full flow test пройдено
- [ ] Prometheus alerting rules застосовано
- [ ] Matrix alerts bridge налаштовано

### Важливі (should-have)
- [ ] Policy engine реалізовано
- [ ] Grafana дашборди створено
- [ ] SLO/SLA документовано
- [ ] Backup/restore стратегія налаштована

### Опціональні (nice-to-have)
- [ ] NATS кластер (3+ replicas) для HA
- [ ] mTLS для Memory Service
- [ ] Consul для capability registry

---

## 📈 SLO/SLA (рекомендовані)

### Online Jobs (MM_ONLINE)
- **Latency P95:** < 300ms
- **Availability:** 99.9%
- **Backlog:** < 1000 messages

### Offline Jobs (MM_OFFLINE)
- **Latency P95:** < 60s
- **Availability:** 99.5%
- **Backlog:** < 10000 messages

### Memory Service
- **Latency P95:** < 1s
- **Availability:** 99.9%
- **Error rate:** < 0.1%

---

## 🔄 Scale-out (додавання нод)

**Процес:**
1. Нова нода = тільки worker-daemon
2. Capabilities реєструються автоматично
3. Жодних змін у Matrix / Memory / NATS

**Перевірка:**
```bash
# Перевірка реєстрації
kubectl exec -n daarion postgres-0 -- psql -U daarion -d daarion_main -c "SELECT node_id, tier, status FROM worker_capabilities;"

# Перевірка heartbeat
kubectl exec -n daarion postgres-0 -- psql -U daarion -d daarion_main -c "SELECT node_id, last_heartbeat FROM worker_capabilities WHERE last_heartbeat > NOW() - INTERVAL '2 minutes';"
```

---

## 🚨 Incident Response

### Якщо NATS backlog росте:
1. Перевірте worker status: `kubectl get pods -l app=memory-worker`
2. Перевірте metrics: `kubectl port-forward -n monitoring prometheus-0 9090:9090`
3. Можливо потрібно додати більше воркерів

### Якщо worker offline:
1. Перевірте логи: `kubectl logs -n daarion memory-worker-xxx`
2. Перевірте capability registry: `SELECT * FROM worker_capabilities WHERE node_id='xxx';`
3. Можливо потрібен перезапуск

### Якщо Memory Service недоступний:
1. Перевірте health: `curl http://memory-service.daarion:8000/health`
2. Перевірте логи: `kubectl logs -n daarion memory-service-xxx`
3. Перевірте Postgres/Qdrant connectivity

---

## 📝 Наступні кроки після deployment

1. **Перевести 1-2 реальних агентів у повний прод-цикл**
   - Не тестових, а реальних
   - Прожити з ними 24-72 години
   - Увімкнені алерти

2. **Моніторинг та оптимізація**
   - Аналіз метрик
   - Оптимізація latency
   - Налаштування алертів

3. **Масштабування**
   - Додавання нових нод
   - Оптимізація розподілу навантаження
   - Налаштування HA

---

*Документ створено: 2026-01-10 19:30 CET*