From 762b4ed6ccce4d3a062b402edfa3c4f266c43929 Mon Sep 17 00:00:00 2001 From: 13orlov <13orlov@gmail.com> Date: Sun, 31 Aug 2025 22:40:26 +0100 Subject: [PATCH] docs: Revamp and format README.md --- README.md | 167 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 120 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 46f1c4a..fe7b625 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,120 @@ -Микросервис "Marquiz Metrica Connector" (v2.0) -Версия: 2.0 -Статус: Staging-окружение развернуто -1. Назначение проекта -Marquiz Metrica Connector — это backend-микросервис, который предоставляет безопасный, стабильный и гибкий API для управления счетчиками и целями в Яндекс.Метрике. Он служит "мостом" между frontend-частью Marquiz и сложным Management API Яндекса. -Ключевые функции: -Безопасная OAuth 2.0 авторизация пользователей. -Управление счетчиками: получение списка, создание. -Управление целями: получение списка, создание кастомных целей, массовое удаление. -2. Стек и архитектура -Язык: Python 3.11+ -Фреймворк: FastAPI (асинхронный) -Сервер: Gunicorn + Uvicorn (production-ready) -Зависимости: Poetry -Тестирование: Pytest -Контейнеризация: Docker (multi-stage build) -CI/CD: Gitea + Drone -Управление секретами: git-crypt -3. Локальная разработка -3.1. Первоначальная настройка -Установите git-crypt на вашу машину (sudo apt install git-crypt). -Получите "мастер-ключ" проекта (marquiz-metrics.key) от тимлида/DevOps. -Клонируйте репозиторий. -"Отомкните" репозиторий, чтобы расшифровать секреты: git-crypt unlock /путь/к/marquiz-metrics.key. -Создайте локальные файлы .env и docker-compose.yml из шаблонов. -Выполните make install для установки зависимостей. -3.2. Полезные команды (Makefile) -make dev-up: Запустить сервис локально. -make dev-down: Остановить сервис. -make test: Запустить автотесты. -make save msg="...": Сделать коммит и push. При коммите git-crypt автоматически зашифрует секретные файлы. -4. Процесс CI/CD (Gitea + Drone) -Проект использует CI/CD для автоматического тестирования и развертывания на Staging. -Триггер: git push в ветку staging. -Пайплайн (.drone.yml): -Login: Drone логинится в Docker Hub. -Test: Запускаются автотесты pytest. -Deploy: Drone подключается к Staging VDS по SSH и запускает скрипт scripts/deploy.sh. -Скрипт deploy.sh (на VDS): -git pull: Скачивает последнюю версию кода. git-crypt автоматически расшифровывает секретные файлы, так как репозиторий на VDS был "отперт" мастер-ключом. -cat ... > .env.staging: Собирает финальный файл с переменными. -make staging-up: Пересобирает и перезапускает Docker-контейнер. -5. Управление секретами (git-crypt) -Секреты для каждого окружения (staging, prod) хранятся в папке envs/. -Файл .gitattributes в корне проекта указывает git-crypt, какие файлы (envs/*.env) нужно шифровать. -Шифрование и расшифровка происходят прозрачно и автоматически при выполнении команд git commit / git pull. -Доступ к секретам получают только те, у кого есть мастер-ключ (marquiz-metrics.key). Этот ключ никогда не хранится в Git. \ No newline at end of file +# Микросервис "Marquiz Metrica Connector" (v2.0) + +**Версия:** 2.0 +**Статус:** Staging-окружение развернуто и готово к интеграции. + +--- + +## 1. Назначение проекта + +**Marquiz Metrica Connector** — это backend-микросервис, который предоставляет безопасный, стабильный и гибкий API для управления счетчиками и целями в Яндекс.Метрике. Он служит "мостом" между frontend-частью Marquiz и сложным Management API Яндекса. + +**Ключевые функции:** +* 🔐 **Безопасная OAuth 2.0 авторизация** пользователей. +* 📊 **Управление счетчиками:** получение списка, создание. +* 🎯 **Управление целями:** получение списка, создание кастомных целей, массовое удаление. + +--- + +## 2. Стек и архитектура + +| Компонент | Технология | +| :--- | :--- | +| **Язык** | Python 3.11+ | +| **Фреймворк** | FastAPI (асинхронный) | +| **Сервер** | Gunicorn + Uvicorn (production-ready) | +| **Зависимости** | Poetry | +| **Тестирование** | Pytest | +| **Контейнеризация** | Docker (multi-stage build) | +| **CI/CD** | Gitea + Drone | +| **Управление секретами** | **git-crypt** | + +--- + +## 3. Локальная разработка + +### 3.1. Первоначальная настройка + +1. **Установите необходимое ПО:** + ```bash + # Для Debian/Ubuntu + sudo apt-get update && sudo apt-get install -y git-crypt poetry + ``` + +2. **Получите мастер-ключ проекта** (`marquiz-metrics.key`) от администратора репозитория. + +3. **Клонируйте репозиторий:** + ```bash + git clone [ssh_url_репозитория] marquiz-metrics + cd marquiz-metrics + ``` + +4. **"Отомкните" репозиторий**, чтобы расшифровать секретные файлы: + ```bash + git-crypt unlock /путь/к/вашему/marquiz-metrics.key + ``` + +5. **Создайте локальные файлы конфигурации** из шаблонов. + ```bash + # Создаем .env с вашими тестовыми секретами + cp envs/staging.env .env + + # Создаем docker-compose.yml для локального запуска + cp docker-compose.base.yml docker-compose.yml + ``` + > **Примечание:** Файлы `.env` и `docker-compose.yml` находятся в `.gitignore` и не попадут в репозиторий. + +6. **Установите зависимости проекта:** + ```bash + make install + ``` + +### 3.2. Полезные команды (`Makefile`) + +Для удобства все рутинные операции вынесены в `Makefile`. + +* **Запустить сервис локально:** + ```bash + make dev-up + ``` +* **Остановить сервис:** + ```bash + make dev-down + ``` +* **Смотреть логи:** + ```bash + make dev-logs + ``` +* **Запустить автотесты:** + ```bash + make test + ``` +* **Сделать коммит и push в текущую ветку:** + ```bash + make save msg="feat: Описание ваших изменений" + ``` + +--- + +## 4. Процесс CI/CD (Gitea + Drone) + +Проект использует CI/CD для автоматического тестирования и развертывания на Staging-окружение. + +* **Триггер:** `git push` в ветку `staging`. +* **Пайплайн (`.drone.yml`):** + 1. **Login:** Drone логинится в Docker Hub для скачивания образов-инструментов. + 2. **Test:** Запускаются автотесты `pytest`. В случае ошибки пайплайн останавливается. + 3. **Deploy:** Если тесты прошли, Drone подключается к Staging VDS по SSH и запускает скрипт `scripts/deploy.sh`. +* **Скрипт `deploy.sh` (на VDS):** + 1. `git pull`: Скачивает последнюю версию кода. `git-crypt` на сервере **автоматически расшифровывает** секреты. + 2. `cat ... > .env.staging`: Собирает финальный файл с переменными окружения. + 3. `make staging-up`: Пересобирает и перезапускает Docker-контейнер с новым кодом и конфигурацией. + +--- + +## 5. Управление секретами (git-crypt) + +* Секреты для каждого окружения (`staging`, `prod`) хранятся в папке `envs/` в **зашифрованном** виде прямо в Git. +* Файл `.gitattributes` в корне проекта указывает `git-crypt`, какие именно файлы (`envs/*.env`) подлежат шифрованию. +* Шифрование/расшифровка происходят **прозрачно и автоматически** при выполнении команд `git commit` / `git pull` на "отпертом" репозитории. +* Доступ к секретам получают только те разработчики и серверы, у которых есть **мастер-ключ**. Ключ **никогда не хранится в Git**. \ No newline at end of file