From 80d665e948a563d5b0893b1c4a95bc51509e57dd Mon Sep 17 00:00:00 2001
From: keboss-m <85340750+keboss-m@users.noreply.github.com>
Date: Wed, 10 Jun 2026 14:27:35 +0300
Subject: [PATCH] Document deploy workflow in README.md and AGENTS.md

---
 AGENTS.md | 36 +++++++++++++++++++++++++
 README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 114 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 8c01da7..9143a1f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -49,3 +49,39 @@ through OpenCode.
 - sqlite-vec недоступен → numpy cosine in-memory.
 - Embedding-модель не загрузилась → BM25-only режим.
 
+## Deploy
+
+**Архитектура: код в git, модели отдельно (rsync).**
+
+- `Makefile` — основные цели: `init`, `pull-models`, `up`, `down`, `restart`, `logs`, `status`, `test`, `deploy`.
+- `scripts/pull_models.sh` — `MODELS_SOURCE=user@host:path` → rsync моделей; fallback на `download_models.py` из интернета.
+- `scripts/deploy.sh` — rsync кода + `.env` + `make pull-models && make up` на удалённом сервере.
+- `.env.example` — коммитится. `.env` — нет (в `.gitignore`).
+
+### Что в git / что нет
+
+| В git (~2 MB) | НЕ в git |
+|---|---|
+| `src/`, `backend/`, `tests/`, `scripts/`, `Makefile` | `models/` (5.83 GB) |
+| `Dockerfile*`, `docker-compose*.yml`, `config.yaml` | `processed/`, `uploads/`, `data/` (рантайм) |
+| `AGENTS.md`, `README.md`, `.env.example` | `migrate/*.tar.gz` (9.5 GB) |
+| `openspec/` (спецификации) | `.env` (секреты) |
+
+### Деплой одной командой (с исходной машины)
+
+```bash
+git add -A && git commit -m "..." && git push origin main
+./scripts/deploy.sh user@server /opt/transcription
+```
+
+### Первый запуск на новом сервере
+
+```bash
+git clone https://gts.meratalk.online/keboss/transcription.git /opt/transcription
+cd /opt/transcription
+make init                            # .env из .env.example
+nano .env                            # вписать HF_TOKEN, OPENCODE_API_KEY
+make pull-models MODELS_SOURCE=user@dev-host:/opt/transcription/models/
+make up
+```
+
diff --git a/README.md b/README.md
index 7c7f8e1..f5db2e5 100644
--- a/README.md
+++ b/README.md
@@ -449,6 +449,84 @@ python start_server.py
 | `/api/files/content?path=...` | GET | Содержимое файла |
 | `/api/files/download?path=...` | GET | Скачивание файла |
 
+## 🚀 Деплой (git + rsync моделей)
+
+Архитектура: **только код в git** (~2 MB), **модели отдельно** (5.83 GB через bind-mount). `.env` с секретами исключён из git, разворачивается вручную или через `scripts/deploy.sh`.
+
+### На исходной машине (один раз после изменений)
+
+```bash
+# Коммит и push кода
+git add -A
+git commit -m "..."
+git push origin main
+
+# Деплой на сервер (rsync + remote make)
+./scripts/deploy.sh user@server /opt/transcription
+```
+
+`scripts/deploy.sh` делает:
+1. `rsync` кода (исключая `models/`, `processed/`, `data/`, `migrate/`, `.git`)
+2. Копирует `.env` (с секретами) на сервер
+3. По SSH: `make pull-models MODELS_SOURCE=... && make up`
+
+### На новом сервере (Linux + Docker)
+
+```bash
+# 1. Установить Docker
+curl -fsSL https://get.docker.com | sh
+sudo usermod -aG docker $USER  # перелогиниться
+
+# 2. Клонировать код
+git clone https://gts.meratalk.online/keboss/transcription.git /opt/transcription
+cd /opt/transcription
+
+# 3. Создать .env
+make init          # cp .env.example .env
+nano .env          # вписать HF_TOKEN, OPENCODE_API_KEY, JWT_SECRET
+
+# 4. Загрузить модели (5.83 GB) одним из способов:
+make pull-models MODELS_SOURCE=user@dev-host:/opt/transcription/models/
+# или
+rsync -avz user@dev-host:/opt/transcription/models/ ./models/
+
+# 5. Запустить
+make up            # docker compose up --build -d
+
+# 6. Проверить
+make status        # docker compose ps + curl /api/health
+make logs          # docker compose logs -f transcription
+```
+
+### Make-цели (шпаргалка)
+
+```bash
+make help         # список всех целей
+make init         # создать .env из .env.example
+make pull-models  # rsync моделей (нужна MODELS_SOURCE)
+make up           # build + запуск
+make down         # остановка
+make restart      # перезапуск без rebuild
+make logs         # логи в follow
+make status       # ps + /api/health
+make test         # pytest
+make deploy       # pull-models + up (всё вместе)
+make clean        # down -v (ОСТОРОЖНО: стирает volumes)
+```
+
+### Почему не Git LFS?
+
+5.83 GB моделей в git = тяжёлый clone, раздутая история. Rsync быстрее, проще, безопаснее. Если позже понадобится — добавим Git LFS отдельным шагом.
+
+### Где живут секреты
+
+| Файл | В git? | Где на сервере |
+|---|---|---|
+| `.env.example` | ✅ да | — |
+| `.env` | ❌ нет | копируется `scripts/deploy.sh` или вручную |
+| `config.yaml` | ✅ да | bind-mount `:ro` в compose |
+| `models/` | ❌ нет | bind-mount `./models/huggingface:/root/.cache/huggingface` |
+
 ## Ограничения
 
 - Перекрывающаяся речь (overlap) распознаётся плохо