Вот подробное и структурированное **описание пайплайна развертывания с использованием Docker и удалённого хоста**, которое можно использовать как документацию или комментарий в `.gitlab-ci.yml`:

---

### **Описание пайплайна: Развертывание приложения через Docker Compose с аутентификацией в приватном реестре**

Этот пайплайн предназначен для **безопасного развертывания приложения на удалённом Docker-хосте** с использованием `docker context` и `docker compose`. Он поддерживает защищённое подключение к Docker-демону по TLS и аутентификацию в приватном Docker-реестре (например, Nexus).

---

###  **Назначение**
- Автоматическое развертывание сервисов, описанных в `docker-compose.yml`, на удалённом хосте.
- Поддержка развёртывания в разные окружения (например, `test`, `staging`).
- Работа с защищённым Docker-демоном (через TLS-сертификаты).
- Аутентификация в приватном реестре с использованием base64-закодированного пароля.

---

###  **Ключевые компоненты**

####  Аутентификация в Docker-реестре
Используется безопасный способ входа через `--password-stdin`:
```yaml
.docker_login_stdin_base64: &docker-login-stdin-base64
  - echo $REGISTRY_PASSWORD | base64 -d | docker login -u $REGISTRY_USER $REGISTRY --password-stdin
```
> Пароль передаётся в виде **base64-закодированной строки**, чтобы избежать проблем с спецсимволами и повысить безопасность в логах.

####  Удалённое подключение к Docker (Docker Context)
Создаётся отдельный контекст для безопасного подключения к удалённому хосту:
```yaml
.docker_context_create: &docker-context-create
  - docker context create ${CI_PROJECT_NAME}-${ENV} --docker "host=tcp://${HOST},ca=${CA_FILE},cert=${CERT_FILE},key=${KEY_FILE}"
```
> Используются TLS-сертификаты (`ca`, `cert`, `key`) для аутентификации на Docker-хосте.

####  Развертывание через Docker Compose
```yaml
.docker_context_deploy: &docker-context-deploy
  - DOCKER_CONTEXT=... docker compose -f docker-compose.yml pull
  - DOCKER_CONTEXT=... docker compose -f docker-compose.yml up -d --force-recreate
```
> Обновляет образы и перезапускает контейнеры с принудительным пересозданием.

---

### **Этапы выполнения (`deploy`)**

1. **Вывод переменных окружения** (`env | sort`) — для отладки и аудита.
2. **Логин в Docker-реестр** — с расшифровкой пароля из base64.
3. **Создание Docker-контекста** — подключение к удалённому хосту по TLS.
4. **Развертывание сервисов**:
   - Скачивание актуальных образов (`pull`).
   - Запуск сервисов в фоне с пересозданием (`up -d --force-recreate`).

---

### **Переменные окружения**

| Переменная | Обязательная | Описание |
|-----------|-------------|---------|
| `ENV` | Да | Имя окружения (например, `test`, `staging`) |
| `HOST` | Да | Адрес удалённого Docker-хоста (например, `example.com:2376`) |
| `CA_FILE` | Да | Содержимое файла `ca.pem` (TLS) |
| `CERT_FILE` | Да | Содержимое `cert.pem` |
| `KEY_FILE` | Да | Содержимое `key.pem` |
| `REGISTRY_USER` | Да | Пользователь реестра (например, `nexus`) |
| `REGISTRY_PASSWORD` | Да | **Base64-закодированный** пароль для доступа к реестру |
| `REGISTRY` | Да | URL Docker-реестра (например, `nexus.example.com:5000`) |
| `COMPOSE_FILES` | Нет (по умолч. `-f docker-compose.yml`) | Дополнительные файлы Compose (например, `-f docker-compose.prod.yml`) |
| `DOCKER_IMAGE` | Да | Образ, в котором запускается пайплайн (с установленным Docker CLI) |

>  Рекомендуется хранить `CA_FILE`, `CERT_FILE`, `KEY_FILE` и `REGISTRY_PASSWORD` как **CI/CD Variables** в GitLab (с флагом "Masked", если возможно).

---

###  **Теги и образ**
- **Образ**: `${DOCKER_IMAGE}` — должен содержать `docker` CLI и поддерживать `docker context` и `docker compose`.
- **Окружение**: Указывается как `environment: name: ${ENV}` — отображается в GitLab CI.
- **Стадия**: `deploy` — выполняется на этапе развертывания.

---

###  **Безопасность**
- Пароль реестра **не передаётся напрямую**, а декодируется из base64.
- Подключение к Docker-хосту — **по TLS**, с использованием сертификатов.
- Все чувствительные данные передаются через защищённые CI-переменные.

---

###  **Пример использования**
1. Убедитесь, что в CI/CD Variables заданы:
   - `NEXUS_PASS_BASE64` — base64-код пароля.
   - `CA_FILE`, `CERT_FILE`, `KEY_FILE` — содержимое сертификатов.
2. Запустите пайплайн вручную.
3. Выберите окружение (например, `test`) и убедитесь, что переменные `HOST` и `ENV` корректны.

---

###  **Примечания**
- Убедитесь, что удалённый Docker-демон разрешает подключения по TCP с вашего CI-раннера.
- Файлы сертификатов должны быть **полностью вставлены** в переменные (включая `-----BEGIN CERTIFICATE-----` и т.д.).
- Для разных окружений можно создавать отдельные джобы с переопределением `ENV`, `HOST` и т.д.

---

 **Назначение:** Быстрое и безопасное развертывание приложений в тестовых/стейджинг окружениях с использованием Docker и приватного реестра.

 **Рекомендуется использовать с GitLab CI, Docker 20.10+, и настроенным TLS на Docker-хосте.**

---