ZBrain/INSTALL.md

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:

  # на любой машине с 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

# На 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 пароли

sudo -u postgres psql

ALTER USER postgres PASSWORD 'СГЕНЕРИРОВАТЬ_24_СИМВОЛА';
CREATE USER brainhub WITH PASSWORD 'ДРУГИЕ_24_СИМВОЛА';
GRANT ALL PRIVILEGES ON DATABASE brainhub TO brainhub;
\q

Сохрани оба пароля в KeePass!

Шаг 3 — Заполнить .env

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 — Первый брейн

sudo bash /opt/zbrain/scripts/create-brain.sh zetit "ZETIT MSP" 3001

Проверка:

sudo systemctl status zbrain-gbrain-zetit
curl -s http://localhost:3001/health || curl -s http://localhost:3001/

Шаг 5 — Тестовый импорт

Подготовь любую папку с markdown-файлами и:

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/
'

Проверка:

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-туннель:

# С твоей машины
ssh -L 3001:127.0.0.1:3001 admin@<vm-ip>

В ~/.claude/mcp.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 — план по спринтам.

Следующая большая задача — Sprint 2: каркас brainhub с auth и UI. Это уже работа в коде:

cd /opt/zbrain
claude  # запустить Claude Code в репо
# В Claude Code:
# > Прочитай CLAUDE.md и docs/ROADMAP.md, начнём Sprint 2.

Если что-то пошло не так

См. docs/DEPLOYMENT.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