Add pipline/deploy_postgres-compose/readme.MD

pipline/deploy_postgres-compose/readme.MD

@@ -0,0 +1,123 @@
+---
+
+### 📝 Описание пайплайна развёртыванияя PostgreSQL-сервиса через Docker Compose
+
+Данный пайплайн предназначен для **безопасного и гибкого развёртывания контейнеризованного PostgreSQL-сервиса** на удалённых хостах с использованием `docker compose` и mTLS-аутентификации. Поддерживает развёртывание на нескольких серверах в **`dev`-окружении** с предварительной настройкой контекста и параметризацией конфигурации.
+
+---
+
+#### Условия запуска
+
+```yaml
+workflow:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "push"
+      when: never
+    - when: always
+```
+
+-  Пайплайн **не запускается автоматически при `push`** (например, при коммите в ветку)
+-  Может быть запущен **вручную** через интерфейс GitLab или API
+-  Это предотвращает случайные деплои и обеспечивает контроль над процессом
+
+---
+
+####  Основные переменные (с параметризацией)
+
+Пайплайн использует **настраиваемые CI-переменные**, доступные при запуске:
+
+| Переменная | Значение / Опции | Описание |
+|-----------|------------------|--------|
+| `ENV` | `"dev"` | Целевое окружение. Сейчас поддерживается только `dev`. |
+| `HOST` | `$APN1_HOST`, `$APN2_HOST`, `$DBN1_HOST`, `$DBN2_HOST` | Выбор сервера для развёртывания. Определяет, на какой хост будет развернут контейнер. |
+| `POSTGRESQL_HOSTNAME_NAME` | — | Имя контейнера/хоста PostgreSQL (например, `postgres-db`) |
+| `POSTGRES_PORT` | — | Внешний порт, на котором будет доступен PostgreSQL (например, `5432`) |
+| `PROXY_NETWORK` | `proxy` | Сеть Docker, к которой подключается контейнер (по умолчанию — `proxy`) |
+| `POSTGRES_DB` | — | Имя основной базы данных |
+| `POSTGRES_USER` | — | Имя пользователя по умолчанию |
+| `POSTGRES_PASSWORD` | — | Пароль пользователя (передаётся безопасно, base64-кодированный) |
+
+>  Все переменные заполняются **вручную при запуске пайплайна**, что делает его гибким и пригодным для разных сценариев развёртывания.
+
+---
+
+####  Настройка mTLS-аутентификации
+
+Перед запуском задачи выполняется блок `before_script`, в котором устанавливаются переменные для **безопасного подключения к Docker-демону**:
+
+```yaml
+.set_docker_context_vars:
+  case "$HOST" in
+    "$APN1_HOST") ... export CA_FILE, CERT_FILE, KEY_FILE ;;
+    ...
+  esac
+```
+
+- Для каждого `HOST` автоматически подставляются соответствующие пути к сертификатам:
+  - `CA_FILE` — сертификат центра сертификации
+  - `CERT_FILE` — клиентский сертификат
+  - `KEY_FILE` — закрытый ключ
+- Обеспечивается **взаимная аутентификация (mTLS)** при подключении к удалённому Docker-хосту
+
+---
+
+####  Внешний шаблон развёртывания
+
+```yaml
+include:
+  - project: 'devops/services/gitlab-flow/ci-flow'
+    ref: v1.0.1
+    file: 'deploy_docker-compose-context.yml'
+```
+
+- Пайплайн использует **централизованный шаблон развёртывания**, содержащий стандартные шаги:
+  - Вход в реестр
+  - Создание Docker-контекста
+  - Выполнение `docker compose up`
+- Гарантирует **единообразие и безопасность** во всех проектах
+
+---
+
+####  Основная задача: `deploy_compose`
+
+Расширяет шаблон `.deploy_from_registry` и переопределяет ключевые параметры:
+
+| Параметр | Значение |
+|--------|--------|
+| `extends` | `.deploy_from_registry` |
+| `environment` | `dev` |
+| `REGISTRY` | `$SED_DOCKER_REGISTRY` (внутренний прокси-реестр) |
+| `REGISTRY_USER` / `REGISTRY_PASSWORD` | `$SED_NEXUS_USER`, `$SED_NEXUS_PASS_BASE64` |
+| `COMPOSE_FILES` | `-f ./docker-compose.yml` |
+| `before_script` | Установка mTLS-сертификатов через `*set-docker-context-vars` |
+| `tags` | `mmedo` — запуск только на специализированных раннерах с поддержкой mTLS |
+
+---
+
+####  при запуске происходит:
+
+1.  Выбор хоста и параметров PostgreSQL
+2.  Установка mTLS-сертификатов в зависимости от `HOST`
+3.  Вход в Docker-репозиторий nexus (`SED_DOCKER_REGISTRY`)
+4.  Создание защищённого Docker-контекста с подключением к удалённому хосту
+5.  `docker compose pull` — загрузка актуальных образов
+6.  `docker compose up -d --force-recreate` — пересоздание и запуск контейнера
+
+---
+
+
+###  Как запустить
+
+1. Перейдите в **CI/CD → Pipelines** в GitLab
+2. Нажмите **"Run pipeline"**
+3. Укажите:
+   - `HOST` — например, `dbn1.example.com`
+   - `POSTGRESQL_HOSTNAME_NAME` — имя контейнера
+   - `POSTGRES_PORT`, `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`
+4. Запустите — приложение будет развёрнуто на выбранном сервере
+
+---
+
+>  **Важно!!!!!!!!**: Убедитесь, что все переменные с паролями и сертификатами корректно настроены в проекте GitLab как **CI/CD Variables**, желательно с типом **File** или **Masked**.
+
+---