201 lines
7.8 KiB
Markdown
201 lines
7.8 KiB
Markdown
// File: specs/200-fullstacks/231-hermes-agent/quickstart.md
|
|
// Change Log:
|
|
// - 2026-05-29: Initial quickstart / verification guide for Hermes Agent staged rollout
|
|
|
|
# Quickstart: Hermes Agent Staged Rollout
|
|
|
|
**Feature**: 231-hermes-agent | **Date**: 2026-05-29
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- [ ] ASUSTOR NAS with Docker support (ADM + Docker add-on)
|
|
- [ ] ASUSTOR IP confirmed (default: `192.168.10.X` — run `df -h` to confirm share paths)
|
|
- [ ] Gitea `hermes-bot` service account created with read-only token (write token created separately for Stage 4)
|
|
- [ ] Telegram bot created via @BotFather → bot token available
|
|
- [ ] Cloud AI API keys (Claude/Anthropic + OpenAI) stored in ASUSTOR secret store
|
|
- [ ] inter-VLAN routing confirmed: ASUSTOR → QNAP (MariaDB :3306, Gitea :3000) — required for Stage 2+
|
|
|
|
---
|
|
|
|
## Stage 0 — Documentation Only (Architecture Team approval required)
|
|
|
|
**Goal**: ADR boundary reviewed, locked decisions captured, no deploy files applied
|
|
|
|
Verification gate:
|
|
- [ ] ADR-031 v2.0 reviewed and all Locked Decisions confirmed
|
|
- [ ] No SQL delta files created
|
|
- [ ] No docker-compose files applied to ASUSTOR
|
|
|
|
✅ **Gate passed** → advance to Stage 1
|
|
|
|
---
|
|
|
|
## Stage 1 — Hermes Container LAN-only (DevOps/Admin approval)
|
|
|
|
```bash
|
|
# บน ASUSTOR shell (SSH ก่อน)
|
|
ssh admin@<ASUSTOR_IP>
|
|
|
|
# ขึ้น stack (hermes-redis + hermes-agent)
|
|
cd /volume1/docker/hermes
|
|
docker compose -f docker-compose.hermes.yml up -d
|
|
|
|
# Verify resource limits enforce จริง
|
|
docker inspect hermes_agent_lcbp3 | grep -E '"Memory"|"NanoCpus"'
|
|
docker stats hermes_agent_lcbp3 --no-stream
|
|
```
|
|
|
|
Verification gate:
|
|
- [ ] Container running: `docker ps | grep hermes_agent_lcbp3`
|
|
- [ ] LAN/VPN-only: Hermes `:8080`, `:8766`, `/mcp` ไม่ accessible จาก public internet
|
|
- [ ] Redis แยกจาก DMS: `docker network inspect lcbp3 | grep hermes-redis` (ต้องอยู่ใน network แยก หรือ isolate ด้วย ACL)
|
|
- [ ] CPU ≤ 2.0 cores, RAM ≤ 4096MB enforce จาก `docker inspect`
|
|
|
|
✅ **Gate passed** → advance to Stage 2
|
|
|
|
---
|
|
|
|
## Stage 2 — Read-only Diagnostics (DBA/Security + DevOps approval)
|
|
|
|
```bash
|
|
# ทดสอบ MariaDB read-only connection (ไม่ควร write ได้)
|
|
docker exec hermes_agent_lcbp3 node -e "
|
|
const mysql = require('mysql2');
|
|
const conn = mysql.createConnection({
|
|
host: process.env.HERMES_MARIADB_READONLY_HOST,
|
|
user: process.env.HERMES_MARIADB_READONLY_USER,
|
|
password: process.env.HERMES_MARIADB_READONLY_PASSWORD,
|
|
database: process.env.HERMES_MARIADB_READONLY_DATABASE
|
|
});
|
|
conn.query('SHOW TABLES', (err, rows) => { console.log(rows); conn.end(); });
|
|
"
|
|
|
|
# ทดสอบ write ต้องล้มเหลว
|
|
# (INSERT statement should return error with read-only user)
|
|
```
|
|
|
|
Verification gate:
|
|
- [ ] Read-only DB grant verified: SELECT pass, INSERT/UPDATE/DELETE fail
|
|
- [ ] Masked/redacted fields verified: no document content, user passwords, storage paths in query results
|
|
- [ ] Gitea read-only token verified: GET repos/issues/PRs pass, POST/PATCH/DELETE fail
|
|
- [ ] No direct storage mount: `docker inspect hermes_agent_lcbp3 | grep Mounts` — no permanent storage paths
|
|
|
|
✅ **Gate passed** → advance to Stage 3
|
|
|
|
---
|
|
|
|
## Stage 3 — Telegram Read-only DevOps (DevOps/Security approval)
|
|
|
|
```bash
|
|
# ทดสอบ webhook secret verification
|
|
curl -X POST http://localhost:8080/api/v1/telegram/webhook \
|
|
-H "X-Telegram-Bot-Api-Secret-Token: WRONG_SECRET" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"message":{"from":{"id":123},"text":"/status","chat":{"id":123}}}' \
|
|
# ต้องได้ 401 Unauthorized
|
|
|
|
# ทดสอบ allowlist rejection
|
|
curl -X POST http://localhost:8080/api/v1/telegram/webhook \
|
|
-H "X-Telegram-Bot-Api-Secret-Token: ${HERMES_TELEGRAM_WEBHOOK_SECRET}" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"message":{"from":{"id":999999999},"text":"/status","chat":{"id":999999999}}}' \
|
|
# ต้องได้ rejected (user ไม่อยู่ใน allowlist)
|
|
|
|
# ทดสอบ /ci_status จาก authorized user
|
|
# (ส่งผ่าน Telegram จริง หรือ simulate ด้วย authorized user ID)
|
|
```
|
|
|
|
Verification gate:
|
|
- [ ] Telegram allowlist verified: non-allowlisted user rejected 100%
|
|
- [ ] Webhook secret verified: wrong secret → 401
|
|
- [ ] Rate limit verified: >10 requests/minute from same user → rejected
|
|
- [ ] `hermes_operations_log` captures inbound/outbound transactions with transactionId
|
|
- [ ] `/ci_status`, `/repo_summary`, `/status`, `/audit_summary` return correct data
|
|
|
|
✅ **Gate passed** → advance to Stage 4
|
|
|
|
---
|
|
|
|
## Stage 4 — Write-with-Confirmation DevOps (Architecture + Security + Repo Owner approval)
|
|
|
|
```bash
|
|
# ทดสอบ forbidden action blocker
|
|
# ส่งคำสั่ง "push to main" ผ่าน Telegram
|
|
# ต้องได้ rejection message โดยไม่มีการดำเนินการใดๆ
|
|
|
|
# ทดสอบ confirmation flow
|
|
# ส่ง "เตรียม branch proposal สำหรับ fix/test-issue"
|
|
# → Hermes แสดง summary + ขอ confirmation
|
|
# → ยืนยัน
|
|
# → ตรวจสอบ Gitea: branch hermes/fix-test-issue ถูกสร้าง
|
|
# → ตรวจสอบ hermes_operations_log: มี entry พร้อม transactionId
|
|
|
|
# ทดสอบ hermes-bot token scope
|
|
git -c http.extraHeader="Authorization: token ${HERMES_BOT_WRITE_TOKEN}" \
|
|
push gitea-origin main
|
|
# ต้องได้ 403 Forbidden (branch protection + token scope block)
|
|
```
|
|
|
|
Verification gate:
|
|
- [ ] Explicit confirmation flow verified: write action requires confirmation before executing
|
|
- [ ] Forbidden action blocklist verified: push main/develop, production deploy, schema migration, direct DB write → rejected
|
|
- [ ] Branch protection + Gitea token scope verified: hermes-bot cannot push to main/develop
|
|
- [ ] `hermes_operations_log` records token identity, target repo/branch for all write actions
|
|
|
|
✅ **Gate passed** → advance to Stage 5
|
|
|
|
---
|
|
|
|
## Stage 5 — Developer AI Proxy (Architecture + Security approval)
|
|
|
|
```powershell
|
|
# บน Windows PowerShell — ทดสอบ hermes proxy
|
|
$env:OPENAI_BASE_URL = "http://<ASUSTOR_IP>:8766/v1"
|
|
$env:OPENAI_API_KEY = "<HERMES_PROXY_API_KEY>"
|
|
|
|
# ทดสอบ basic coding request (no production data)
|
|
codex "scaffold NestJS module for health check"
|
|
# ต้องได้ response พร้อม DMS context
|
|
|
|
# ทดสอบ secret payload rejection
|
|
# ส่ง payload ที่มี "password: secret123" หรือ storage path
|
|
# ต้องได้ rejected + redact ใน log
|
|
```
|
|
|
|
Verification gate:
|
|
- [ ] Proxy LAN/VPN-only: port 8766 ไม่ accessible จาก public internet
|
|
- [ ] No secrets/document payload: test payload ที่มี token/password/storage path ถูก reject และ redact ใน log
|
|
- [ ] Proxy ไม่ wired เข้า DMS AI runtime หรือ DMS document intelligence path
|
|
- [ ] Wrong API key → 401
|
|
|
|
✅ **All stages complete** → Hermes fully operational
|
|
|
|
---
|
|
|
|
## Rollback Procedures
|
|
|
|
| Stage | Rollback |
|
|
|-------|---------|
|
|
| Stage 1 | `docker compose -f docker-compose.hermes.yml down`; verify DMS production unaffected |
|
|
| Stage 2 | Revoke DB/Gitea read-only credentials via Gitea admin; disable MCP servers; confirm no storage mount |
|
|
| Stage 3 | `curl -X DELETE "https://api.telegram.org/bot{TOKEN}/deleteWebhook"`; revoke bot token if needed |
|
|
| Stage 4 | Revoke Gitea write token via Gitea admin; disable write commands in Hermes config |
|
|
| Stage 5 | Unset `OPENAI_BASE_URL` on all clients; stop hermes proxy; revoke proxy API key |
|
|
|
|
---
|
|
|
|
## Health Check Endpoints
|
|
|
|
```bash
|
|
# Hermes health (Stage 1+)
|
|
curl http://<ASUSTOR_IP>:8080/api/v1/health
|
|
|
|
# hermes proxy health (Stage 5)
|
|
curl http://<ASUSTOR_IP>:8766/v1/models
|
|
|
|
# Dev Qdrant health (if deployed)
|
|
curl http://<ASUSTOR_IP>:6334/healthz
|
|
```
|