Add installer script and repository integration guide.

Made-with: Cursor
2026-04-20 22:57:39 +10:00
parent 5f20b0eae6
commit 4c652c7431
4 changed files with 238 additions and 0 deletions
@@ -0,0 +1,114 @@
+# OpenClaude и Git-репозитории
+
+Как организовать работу OpenClaude с GitHub/GitLab/Gitea и похожими сервисами.
+
+## 1) Что значит "научить OpenClaude работать с репозиториями"
+
+Обычно это 3 уровня:
+
+1. **Локальный уровень**: OpenClaude работает в локальном git-репозитории (`clone`, `branch`, `commit`).
+2. **Remote уровень**: пуш/PR/issue через токены и CLI (`gh`, `glab`, `tea`).
+3. **Контекст и автоматизация**: доступ к данным репозитория через MCP-инструменты.
+
+## 2) Базовая схема (рекомендуется)
+
+- Клонировать репозиторий локально.
+- Запускать OpenClaude из корня проекта.
+- Для GitHub использовать `gh auth login`.
+- Для GitLab использовать `glab auth login`.
+- Для Gitea использовать SSH-ключи или PAT в remote URL/credential manager.
+
+Это даёт OpenClaude полный цикл: читать код, редактировать, запускать тесты, делать коммиты и PR.
+
+## 3) Настройка аутентификации без постоянного ввода пароля
+
+### GitHub
+
+```bash
+gh auth login
+gh auth status
+```
+
+### GitLab
+
+```bash
+glab auth login
+glab auth status
+```
+
+### Универсально для git HTTPS
+
+```bash
+git config --global credential.helper store
+```
+
+Лучше и безопаснее - SSH:
+
+```bash
+ssh-keygen -t ed25519 -C "you@example.com"
+# добавить публичный ключ в GitHub/GitLab/Gitea
+git remote set-url origin git@github.com:OWNER/REPO.git
+```
+
+## 4) Минимальный безопасный процесс работы с кодом
+
+1. Создать отдельную feature-ветку.
+2. Делать небольшие коммиты с понятными сообщениями.
+3. Перед push запускать тесты/lint.
+4. Не хранить секреты в репозитории (`.env`, ключи, токены).
+5. Для main/master включить protected branch и PR review.
+
+## 5) Как подключить репозиторий как источник знаний (RAG)
+
+Если цель - чтобы OpenClaude "знал проект":
+
+- индексировать `README`, `docs`, ADR, API-контракты, runbook
+- не индексировать шум (`node_modules`, `dist`, lock-файлы без необходимости)
+- регулярно переиндексировать после merge крупных изменений
+
+Простой путь:
+
+- `git clone` репозиторий
+- копировать нужные папки в `docs/rag-mcp-starter/docs`
+- запускать `index.py`
+- использовать `search_docs` и `answer_with_citations`
+
+## 6) MCP для Git-платформ: что имеет смысл добавить
+
+Полезные MCP-инструменты:
+
+- `list_prs(repo)`
+- `get_pr_diff(repo, pr_number)`
+- `list_issues(repo, label)`
+- `create_issue(repo, title, body)`
+- `comment_pr(repo, pr_number, body)`
+- `get_file_at_ref(repo, path, ref)`
+
+Такой слой позволяет OpenClaude работать не только с локальным checkout, но и с удаленным контекстом.
+
+## 7) Практика для self-hosted Git (Gitea/Forgejo/GitLab self-hosted)
+
+1. Убедиться в доступности API/SSH с сервера.
+2. Создать сервисный токен с минимальными правами (least privilege).
+3. Хранить токен в переменных окружения или secrets manager.
+4. Ограничить доступ по IP/ACL.
+5. Вести аудит действий (кто/когда создал PR/comment/push).
+
+## 8) Частые ошибки
+
+- OpenClaude запущен не из корня репозитория.
+- Нет прав на push в remote.
+- PAT истек или не имеет scope для PR/issues.
+- Смешивание нескольких аккаунтов в одном credential helper.
+- Отсутствуют локальные зависимости проекта (тесты не запускаются).
+
+## 9) Рабочий чек-лист перед началом
+
+```bash
+git status
+git remote -v
+gh auth status || true
+glab auth status || true
+```
+
+Если всё ок - можно давать OpenClaude задачи на полный цикл "изменение -> тест -> commit -> PR".
@@ -6,6 +6,7 @@
 - `index.py` - индексация документов в Qdrant
 - `mcp_server.py` - MCP инструменты `search_docs` и `answer_with_citations`
 - `requirements.txt` - Python зависимости
+- `install.sh` - one-command bootstrap для Ubuntu

 ## Быстрый запуск

@@ -21,6 +22,20 @@ python index.py
 python mcp_server.py
 ```

+## Автоматический bootstrap
+
+```bash
+chmod +x install.sh
+./install.sh
+```
+
+Опции:
+
+```bash
+./install.sh --skip-model-pull
+./install.sh --docs-dir /path/to/my/docs
+```
+
 ## Переменные окружения

 - `QDRANT_URL` (default `http://127.0.0.1:6333`)
@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# One-command bootstrap for OpenClaude local RAG starter on Ubuntu.
+#
+# Usage:
+#   ./install.sh
+#   ./install.sh --skip-model-pull
+#   ./install.sh --docs-dir /path/to/docs
+
+SKIP_MODEL_PULL=0
+DOCS_DIR="${PWD}/docs"
+WORKDIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --skip-model-pull)
+      SKIP_MODEL_PULL=1
+      shift
+      ;;
+    --docs-dir)
+      DOCS_DIR="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown argument: $1"
+      exit 2
+      ;;
+  esac
+done
+
+need_cmd() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "Missing command: $1"
+    exit 1
+  }
+}
+
+echo "==> Installing system packages"
+sudo apt update
+sudo apt install -y curl git docker.io docker-compose-plugin python3 python3-venv python3-pip
+
+echo "==> Enabling Docker"
+sudo systemctl enable docker
+sudo systemctl start docker
+
+echo "==> Installing Ollama if needed"
+if ! command -v ollama >/dev/null 2>&1; then
+  curl -fsSL https://ollama.com/install.sh | sh
+fi
+sudo systemctl enable ollama
+sudo systemctl start ollama
+
+echo "==> Verifying local services"
+curl -fsS "http://127.0.0.1:11434/api/tags" >/dev/null || true
+
+echo "==> Installing OpenClaude CLI"
+if ! command -v openclaude >/dev/null 2>&1; then
+  need_cmd npm
+  npm install -g @gitlawb/openclaude
+fi
+
+echo "==> Starting Qdrant"
+cd "$WORKDIR"
+docker compose up -d
+
+echo "==> Creating Python venv"
+python3 -m venv .venv
+source .venv/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt
+
+echo "==> Preparing docs directory"
+mkdir -p "$DOCS_DIR"
+if [[ "$DOCS_DIR" != "${WORKDIR}/docs" ]]; then
+  echo "Using custom docs directory: $DOCS_DIR"
+fi
+
+if [[ "$SKIP_MODEL_PULL" -eq 0 ]]; then
+  echo "==> Pulling models (qwen2.5-coder:7b + nomic-embed-text)"
+  ollama pull qwen2.5-coder:7b
+  ollama pull nomic-embed-text
+else
+  echo "==> Skipping model pull (--skip-model-pull)"
+fi
+
+cat <<EOF
+
+Bootstrap complete.
+
+Next steps:
+1) Put your files into: $DOCS_DIR
+2) Index docs:
+   cd "$WORKDIR"
+   source .venv/bin/activate
+   RAG_DOCS_DIR="$DOCS_DIR" python index.py
+
+3) Run MCP server:
+   cd "$WORKDIR"
+   source .venv/bin/activate
+   python mcp_server.py
+
+4) Run OpenClaude against local Ollama:
+   export CLAUDE_CODE_USE_OPENAI=1
+   export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
+   export OPENAI_MODEL=qwen2.5-coder:7b
+   openclaude
+EOF