main

2026-05-20 19:33:02 +03:00
commit f4bca8449e
30 changed files with 4152 additions and 0 deletions
@@ -0,0 +1,162 @@
+# INSTALL — Что делать после клонирования репозитория
+
+Этот документ — единая точка входа после `git clone git@git.zetit.ru:zuevav/ZBrain.git`. Здесь только команды и checkpoints, без объяснений (объяснения — в `docs/`).
+
+## Предусловия
+
+- [ ] Виртуалка создана: **Ubuntu 22.04 LTS, 4 vCPU, 8 GB RAM, 80 GB SSD**
+- [ ] SSH-доступ настроен
+- [ ] Внутренний DNS `brain.zetit.local` указывает на эту VM
+- [ ] (Опционально) Внешний DNS `brain.zetit.ru` указывает на edge-сервер или эту VM
+- [ ] Создан **mirror gbrain** в твоём git:
+  ```bash
+  # на любой машине с GitHub доступом, ОДИН РАЗ
+  git clone --mirror https://github.com/garrytan/gbrain.git
+  cd gbrain.git
+  git push --mirror git@git.zetit.ru:zuevav/gbrain-mirror.git
+  ```
+
+## Шаг 1 — Bootstrap VM
+
+```bash
+# На VM
+sudo mkdir -p /opt && sudo chown $USER:$USER /opt
+git clone git@git.zetit.ru:zuevav/ZBrain.git /opt/zbrain
+cd /opt/zbrain
+
+# Запуск (правь параметры под себя!)
+sudo TOTAL_RAM_GB=8 \
+     FNA_PROXY="http://client_001:ВСТАВЬ_ПАРОЛЬ@fna.zetit.ru:3128" \
+     GBRAIN_REPO="https://git.zetit.ru/zuevav/gbrain-mirror.git" \
+     GBRAIN_VERSION="master" \
+     bash scripts/bootstrap-vm.sh
+```
+
+**Проверка:** последняя строчка вывода — "Bootstrap готов" + список Next Steps.
+
+## Шаг 2 — Postgres пароли
+
+```bash
+sudo -u postgres psql
+```
+
+```sql
+ALTER USER postgres PASSWORD 'СГЕНЕРИРОВАТЬ_24_СИМВОЛА';
+CREATE USER brainhub WITH PASSWORD 'ДРУГИЕ_24_СИМВОЛА';
+GRANT ALL PRIVILEGES ON DATABASE brainhub TO brainhub;
+\q
+```
+
+**Сохрани оба пароля в KeePass!**
+
+## Шаг 3 — Заполнить `.env`
+
+```bash
+sudo cp /etc/zbrain/env.example /etc/zbrain/.env
+sudo chmod 600 /etc/zbrain/.env
+sudo chown zbrain:zbrain /etc/zbrain/.env
+
+# Сгенерировать секреты
+echo "SESSION_SECRET=$(openssl rand -hex 32)"
+echo "JWT_SECRET=$(openssl rand -hex 32)"
+echo "TOKEN_ENCRYPTION_KEY=$(openssl rand -hex 16)"
+
+sudo nano /etc/zbrain/.env
+```
+
+Заполнить:
+- `DATABASE_URL` — с паролем brainhub из шага 2
+- `HTTPS_PROXY`, `HTTP_PROXY` — с реальным паролем FNA
+- `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`
+- Секреты из openssl выше
+- `INITIAL_OWNER_EMAIL`, `INITIAL_OWNER_PASSWORD`
+
+## Шаг 4 — Первый брейн
+
+```bash
+sudo bash /opt/zbrain/scripts/create-brain.sh zetit "ZETIT MSP" 3001
+```
+
+**Проверка:**
+
+```bash
+sudo systemctl status zbrain-gbrain-zetit
+curl -s http://localhost:3001/health || curl -s http://localhost:3001/
+```
+
+## Шаг 5 — Тестовый импорт
+
+Подготовь любую папку с markdown-файлами и:
+
+```bash
+sudo -u zbrain bash -c '
+  export PATH=$HOME/.bun/bin:$PATH
+  source /etc/zbrain/.env
+  export DATABASE_URL=$(jq -r .database_url /var/lib/zbrain/brains/zetit/config.json)
+  cd /var/lib/zbrain/gbrain
+  bun run gbrain import /tmp/test-markdown/
+'
+```
+
+**Проверка:**
+
+```bash
+sudo -u postgres psql -d gbrain_zetit -c '
+SELECT
+  (SELECT count(*) FROM pages) AS pages,
+  (SELECT count(*) FROM content_chunks) AS chunks,
+  (SELECT count(*) FROM content_chunks WHERE embedding IS NOT NULL) AS embedded;
+'
+```
+
+Если `embedded < chunks` — embeddings ещё генерируются (проверь логи) или OPENAI_API_KEY не работает (проверь curl через FNA proxy).
+
+## Шаг 6 — Опционально: подключить Claude Code напрямую
+
+Пока brainhub не написан (Sprint 2+), можно подключиться к gbrain через SSH-туннель:
+
+```bash
+# С твоей машины
+ssh -L 3001:127.0.0.1:3001 admin@<vm-ip>
+```
+
+В `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "zbrain-zetit-direct": {
+      "transport": "http",
+      "url": "http://127.0.0.1:3001"
+    }
+  }
+}
+```
+
+Перезапустить Claude Code, проверить MCP инструменты.
+
+После Sprint 2-3 эта прямая связь будет заменена на `https://brain.zetit.ru/mcp/zetit` с токеном.
+
+## Что дальше
+
+См. **[docs/ROADMAP.md](docs/ROADMAP.md)** — план по спринтам.
+
+Следующая большая задача — **Sprint 2**: каркас brainhub с auth и UI. Это уже работа в коде:
+
+```bash
+cd /opt/zbrain
+claude  # запустить Claude Code в репо
+# В Claude Code:
+# > Прочитай CLAUDE.md и docs/ROADMAP.md, начнём Sprint 2.
+```
+
+## Если что-то пошло не так
+
+См. **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)** раздел "Типовые проблемы" и **[docs/OPERATIONS.md](docs/OPERATIONS.md)** раздел "Runbook'и инцидентов".
+
+Логи везде:
+- bootstrap: stdout скрипта + `/var/log/syslog`
+- Postgres: `/var/log/postgresql/postgresql-16-main.log`
+- gbrain: `journalctl -u zbrain-gbrain-<name>` и `/var/log/zbrain/<name>.log`
+- brainhub (когда будет): `/var/log/zbrain/brainhub.log`
+- nginx: `/var/log/nginx/zbrain-*.log`