devops/pipline/deploy_postgres-compose/readme.MD

---

###  Описание пайплайна развёртыванияя 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**.

---