UniBPM Enterprise / Community Distribution — DevOps Deployment Runbook

1. Назначение документа

Документ предназначен для:

• DevOps инженеров
• инженеров по инфраструктуре
• системных администраторов

Документ описывает:

• развертывание UniBPM в Docker;
• подключение к внешним PostgreSQL, Kafka, Keycloak и nginx;
• настройку интеграции UniBPM с внешними сервисами;
• базовую валидацию развертывания.

Инструкция не описывает установку PostgreSQL, Kafka, Keycloak и nginx. Предполагается, что данные сервисы уже развернуты и доступны.

2. Отличия от инструкции по установке Community дистрибутива

В данной инструкции:

• PostgreSQL — внешний;
• Kafka — внешняя;
• Keycloak — внешний;
• nginx — внешний reverse proxy;
• UniBPM разворачивается как набор контейнеров приложений.

Локальные Docker-инстансы PostgreSQL, Kafka и Keycloak не используются.

3. Системные требования

3.1 Рекомендуемые ресурсы

Минимальная конфигурация:

Рекомендуемая конфигурация:

3.2 Поддерживаемые версии

4. DNS и TLS требования

4.1 DNS

Необходимы DNS-записи:

uni.company.com
id.company.com

Опционально:

camunda.company.com

Все DNS-записи должны указывать на reverse proxy/nginx.

4.2 TLS

Рекомендуется использование HTTPS.

Требования:

• TLS termination на nginx;
• корректный reverse proxy;
• валидные сертификаты;
• поддержка WebSocket proxying.

Поддерживаются:

• Let’s Encrypt;
• корпоративные сертификаты.

4.3 Сетевые подключения и порты

Входящие подключения

Исходящие подключения UniBPM

Порты контейнеров UniBPM

При использовании Docker bridge network публикация внутренних портов наружу обычно не требуется.

Рекомендуется публиковать наружу только nginx.

5. Внешние зависимости

5.1 PostgreSQL

Требования

• PostgreSQL 15+;
• UTF-8 encoding;
• доступ по TCP;
• отдельные базы для UniBPM и Camunda.

Создание пользователей

CREATE USER unibpm WITH PASSWORD '<strong_password>';
CREATE USER camunda WITH PASSWORD '<strong_password>';

Создание баз

CREATE DATABASE unibpm OWNER unibpm;
CREATE DATABASE camunda OWNER camunda;

Права для базы unibpm

\c unibpm

GRANT ALL PRIVILEGES ON DATABASE unibpm TO unibpm;
GRANT USAGE, CREATE ON SCHEMA public TO unibpm;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO unibpm;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO unibpm;

Права для базы camunda

\c camunda

GRANT ALL PRIVILEGES ON DATABASE camunda TO camunda;
GRANT USAGE, CREATE ON SCHEMA public TO camunda;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO camunda;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO camunda;

Настройка UniBPM

Файл:

generated/unibpm/application.yaml

spring:
  datasource:
    url: jdbc:postgresql://postgres.company.com:5432/unibpm
    username: unibpm
    password: ${UNIBPM_DB_PASSWORD}

Настройка Camunda Engine

Файл:

generated/engine/application.yaml

spring:
  datasource:
    url: jdbc:postgresql://postgres.company.com:5432/camunda
    username: camunda
    password: ${CAMUNDA_DB_PASSWORD}

5.2 Kafka

Требования

Поддерживаются:

• single-node Kafka;
• multi-node Kafka cluster.

Рекомендуется:

• replication.factor >= 3 для production;
• min.insync.replicas >= 2;
• retention согласно требованиям компании.

Topics

Основные topics создаются приложением автоматически.

Основной topic событий:

reunico.unibpm.task.events.prod

При отключенном auto topic creation topics необходимо создать вручную.

Настройка UniBPM

Файл:

generated/unibpm/application.yaml

spring:
  kafka:
    bootstrap-servers: kafka.company.com:9092

Настройка Engine

Файл:

generated/engine/application.yaml

spring:
  kafka:
    bootstrap-servers: kafka.company.com:9092

Kafka с SASL/SSL

spring:
  kafka:
    bootstrap-servers: kafka.company.com:9093
    properties:
      security.protocol: SASL_SSL
      sasl.mechanism: SCRAM-SHA-512
      sasl.jaas.config: >
        org.apache.kafka.common.security.scram.ScramLoginModule required
        username="${KAFKA_USERNAME}"
        password="${KAFKA_PASSWORD}";

5.3 Keycloak

Требования

• Keycloak 26.x;
• доступ по HTTPS.

Обязательные clients

Типы clients

Рекомендуемые типы:

Client secrets

Получение secrets:

Realm
  → Clients
  → <client>
  → Credentials
  → Client secret

Обязательные роли

Для:

camunda-identity-service

назначить:

realm-management → realm-admin

Настройка UniBPM

Файл:

generated/unibpm/application.yaml

identity:
  keycloak:
    base-url: https://id.company.com
    realm: unibpm

OAuth2 конфигурация

spring:
  security:
    oauth2:
      client:
        registration:
          unibpm-keycloak:
            client-id: unibpm-app
            client-secret: ${UNIBPM_APP_SECRET}
            authorization-grant-type: client_credentials

          unibpm-camunda:
            client-id: unibpm-camunda-client
            client-secret: ${UNIBPM_CAMUNDA_SECRET}
            authorization-grant-type: client_credentials

        provider:
          unibpm-keycloak:
            token-uri: https://id.company.com/realms/unibpm/protocol/openid-connect/token

Настройка Camunda Keycloak plugin

Файл:

generated/engine/application.yaml

plugin.identity.keycloak:
  keycloakIssuerUrl: https://id.company.com/realms/unibpm
  keycloakAdminUrl: https://id.company.com/admin/realms/unibpm
  clientId: camunda-identity-service
  clientSecret: ${CAMUNDA_IDENTITY_SECRET}

5.4 nginx

Требования

nginx используется как reverse proxy.

Требования:

• HTTPS termination;
• WebSocket support;
• proxy headers;
• large request support.

Пример конфигурации nginx

server {
    listen 443 ssl;
    server_name uni.company.com;

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    location / {
        proxy_pass http://unibpm-frontend:80;

        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 300;
        proxy_connect_timeout 300;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

6. Устанавливаемые компоненты

Разворачиваются следующие контейнеры:

Пример Docker Compose

version: '3.9'

services:
  unibpm:
    image: cr.yandex/crp1uqso77nujlub6a96/unibpm-app:1.0.0
    platform: linux/amd64
    volumes:
      - ./generated/unibpm/application.yaml:/config/application.yaml:ro
    env_file:
      - .env
    ports:
      - "${BACKEND_PUBLIC_PORT:-8099}:8099"
    networks:
      - unibpm
    restart: unless-stopped

  unibpm-engine:
    image: cr.yandex/crp1uqso77nujlub6a96/unibpm-engine:1.0.0
    platform: linux/amd64
    volumes:
      - ./generated/engine/application.yaml:/config/application.yaml:ro
    env_file:
      - .env
    ports:
      - "${CAMUNDA_PUBLIC_PORT:-8081}:8080"
    networks:
      - unibpm
    restart: unless-stopped

  unibpm-frontend:
    image: cr.yandex/crp1uqso77nujlub6a96/unibpm-frontend:1.0.0
    platform: linux/amd64
    depends_on:
      - unibpm
      - unibpm-engine
    ports:
      - "${FRONT_PUBLIC_PORT:-8080}:80"
    networks:
      - unibpm
    restart: unless-stopped

networks:
  unibpm:
    driver: bridge

В отличие от Community compose, в данном варианте отсутствуют контейнеры PostgreSQL, Kafka, Keycloak, nginx и certbot.

7. Переменные окружения

Обязательные secrets

UNIBPM_DB_PASSWORD
CAMUNDA_DB_PASSWORD
UNIBPM_APP_SECRET
UNIBPM_CAMUNDA_SECRET
CAMUNDA_IDENTITY_SECRET
KAFKA_USERNAME
KAFKA_PASSWORD

Secrets не должны храниться в Git.

Рекомендуется использовать:

• Vault;
• Kubernetes Secrets;
• Docker Secrets;
• CI/CD variables.

8. Validation / Smoke Test

Проверка доступности UI

Открыть:

https://uni.company.com

Ожидаемый результат:

• открывается frontend;
• выполняется redirect в Keycloak;
• успешная авторизация.

Проверка Kafka

Проверить логи:

docker compose logs -f unibpm-app

В логах отсутствуют ошибки:

Bootstrap broker disconnected
TimeoutException
Topic not found

Проверка Keycloak

Проверить получение token:

curl -i -X POST "https://id.company.com/realms/unibpm/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=camunda-identity-service" \
  --data-urlencode "client_secret=<secret>"

Ожидаемый результат:

HTTP 200
access_token

Проверка PostgreSQL

Проверить успешное выполнение миграций.

В логах отсутствуют ошибки:

permission denied
no schema has been selected
relation does not exist

Проверка backend health endpoint

curl http://localhost:8099/actuator/health

Ожидаемый результат:

{"status":"UP"}

Проверка engine health endpoint

curl http://localhost:8080/actuator/health

Ожидаемый результат:

{"status":"UP"}

Health endpoints рекомендуется использовать для:

• readiness probes;
• liveness probes;
• monitoring;
• external load balancer health checks.

9. Архитектурная диаграмма

10. Troubleshooting

401 Unauthorized

Причина:

• неверный client secret;
• неверный realm;
• неверный token-uri.

403 Forbidden

Причина:

• отсутствует role:

realm-management → realm-admin

Kafka connection errors

Причина:

• неверный bootstrap server;
• firewall;
• SASL misconfiguration.

PostgreSQL schema errors

Причина:

• отсутствуют права на schema public.

11. Итог

После выполнения инструкции:

• UniBPM frontend доступен через nginx;
• backend успешно подключается к PostgreSQL;
• backend успешно подключается к Kafka;
• OAuth2 authentication выполняется через внешний Keycloak;
• Camunda интегрирована с Keycloak;
• smoke test выполняется успешно.