Конфигурация CMS Deployer

В этой статье содержится информация о настройке различных элементов CMS Deployer.
Изображение статьи

CMS Deployer - это агент развертывания (deployment agent) DC CMS.

Администрирование

Запуск/остановка CMS Deployer

Если DC CMS установлено на сервере, запуск и остановка CMS Deployer - достаточно простой процесс. Просто перейдите в {env-directory} из командной строки (в папку delivery- или authoring-окружения). Внутри папки bin выполните команду ./cms.sh start_deployer, чтобы начать работу CMS Deployer, или ./cms.sh stop_deployer, чтобы завершить его операцию.

Конфигурация

Глобальная конфигурация

CMS Deployer включает в себя два основных конфигурационных файла, расположенных в {env-directory}/bin/cms-deployer/config:

  1. application.yaml: этот файл включает в себя глобальные настройки приложения, такие как порт сервера и пути к другим конфигурационным файлам.

  2. base-target.yaml: этот файл содержит общие свойства, применимые ко всем целям (targets). В нем содержатся конфигурации для задач, таких как индексация с использованием CMS Search и настройка уведомлений по электронной почте о развертывании.

Загрузка файла application.yaml автоматизирована Spring Boot. Его свойства можно изменять, переопределяя их в стандартных внешних местах, определенных Spring Boot:

  • application.yaml в папке config в текущей директории
  • application.yaml в текущей директории
  • application.yaml в директории config в classpath
  • application.yaml в корне classpath

Кроме того, у вас есть возможность переопределить свойства application.yaml, указав их как системные свойства, например, -Dserver.port=7171.

Ниже расположен образец файла application.yaml:

deployer:
  main:
    config:
      environment:
        active: ${CMS_ENVIRONMENT}
    targets:
      config:
        folderPath: ${targets.dir}
    deployments:
      folderPath: ${deployments.dir}
      output:
        folderPath: ${logs.dir}
      processedCommits:
        folderPath: ${processedCommits.dir}
    logging:
      folderPath: ${logs.dir}
    management:
      # Deployer management authorization token
      authorizationToken: ${DEPLOYER_MANAGEMENT_TOKEN}
    security:
      encryption:
        # The key used for encryption of configuration properties
        key: ${CMS_ENCRYPTION_KEY}
        # The salt used for encryption of configuration properties
        salt: ${CMS_ENCRYPTION_SALT}
      ssh:
        # The path of the folder used for the SSH configuration
        config: ${CMS_SSH_CONFIG}
Copy-icon

Обработка файла base-target.yaml немного отличается. Каждый раз, когда добавляется новая цель (target), CMS Deployer загружает этот файл и объединяет его с конкретными свойствами цели, придавая приоритет свойствам цели. Местоположение по умолчанию для переопределения этого файла конфигурации - ./config/base-target.yaml, но его можно изменить, используя свойство deployer.main.targets.config.baseYaml.overrideLocation в файле application.yaml.

Ниже расположен образец файла base-target.yaml:

target:
  localRepoPath: ${deployer.main.deployments.folderPath}/${target.siteName}
  engineUrl: ${env:ENGINE_URL}
  engineManagementToken: ${env:ENGINE_MANAGEMENT_TOKEN}
  studioUrl: ${env:STUDIO_URL}
  studioManagementToken: ${env:STUDIO_MANAGEMENT_TOKEN}
  translation:
    # Indicates if the translation features should be enabled for the target
    enable: false
  search:
    elasticSearch:
      # Single Cluster
      urls:
        - ${env:SEARCH_URL}
      username: ${env:SEARCH_USERNAME}
      password: ${env:SEARCH_PASSWORD}
      timeout:
        # The connection timeout in milliseconds, if set to -1 the default will be used
        connect: -1
        # The socket timeout in milliseconds, if set to -1 the default will be used
        socket: -1
      # The number of threads to use, if set to -1 the default will be used
      threads: -1
      # Indicates if keep alive should be enabled for sockets used by the search client, defaults to false
      keepAlive: false

      # Multiple Clusters
      #      readCluster:
      #        urls:
      #        username:
      #        password:
      #      writeClusters:
      #        - urls:
      #          username:
      #          password:
      #        - urls:
      #          username:
      #          password:

      # Settings used for all indices
      indexSettings:
        - key: "index.mapping.total_fields.limit"
          value : 3000
        - key: "index.mapping.depth.limit"
          value: 40

      notifications:
        mail:
          server:
            host: ${env:MAIL_HOST}
            port: ${env:MAIL_PORT}
Copy-icon

где:

  • переменные engineURL и engineManagementToken используются для вызова API CMS Engine, и их значения задаются в переменных окружения
  • переменные studioURL и studioManagementToken необходимы для вызова API CMS Studio, и их значения задаются в переменных окружения

Настройка цели (target)

Каждая цель развертывания (deployment target) имеет свой файл конфигурации в формате YAML, который содержит сведения о свойствах данной цели и всей цепочке развертывания. В случае отсутствия этого файла CMS Deployer не будет знать о существовании данной цели. Обычно эти файлы конфигурации расположены в ./config/targets. Для установок DC CMS на сервере они могут быть найдены в CMS_HOME/data/deployer/targets.

Конфигурации целей имеют значительные различия в зависимости от окружения (delivery или authoring). Authoring-цель работает с локальным репозиторием, в то время как delivery-цель извлекает файлы из удаленного репозитория. Однако конфигурации целей в одном и том же окружении остаются относительно постоянными. Следующие два примера можно взять за основу для большинства целевых конфигурационных файлов для authoring или delivery:

  • пример конфигурации authoring-цели

target:
  # Environment name
  env: preview
  # Site name
  siteName: editorial
  # CMS Engine base URL
  engineUrl: http://localhost:8080
  # Path to the sandbox repository of the site
  localRepoPath: /opt/cms/authoring/data/repos/sites/editorial/sandbox
  deployment:
    scheduling:
      # Scheduling is disabled since Studio will call deploy on file save
      enabled: false
    pipeline:
      # Calculates the Git differences with the latest commit processed
      - processorName: gitDiffProcessor
      # Performs CMS Search indexing
      - processorName: searchIndexingProcessor
      # Calls Rebuild Context when a file under /scripts is changed
      - processorName: httpMethodCallProcessor
        includeFiles: ["^/?scripts/.*$"]
        method: GET
        url: ${target.engineUrl}/api/1/site/context/rebuild.json?cmsSite=${target.siteName}
      # Calls Clear Cache
      - processorName: httpMethodCallProcessor
        method: GET
        url: ${target.engineUrl}/api/1/site/cache/clear.json?cmsSite=${target.siteName}
      # Generates a deployment output file
      - processorName: fileOutputProcessor
Copy-icon
  • пример конфигурации delivery-цели

target:
  # Environment name
  env: dev
  # Site name
  siteName: editorial
  # CMS Engine base URL
  engineUrl: http://localhost:9080
  deployment:
    pipeline:
      # Pulls the remote Git repository of the site
      - processorName: gitPullProcessor
        remoteRepo:
          # URL of the remote repo
          url: /opt/cms/authoring/data/repos/sites/editorial/published
          # Live of the repo to pull
          branch: live
      # Calculates the Git differences with the latest commit processed
      - processorName: gitDiffProcessor
      # Performs CMS Search indexing
      - processorName: searchIndexingProcessor
      # Calls Rebuild Context when a file under /scripts is changed
      - processorName: httpMethodCallProcessor
        includeFiles: ["^/?scripts/.*$"]
        method: GET
        url: ${target.engineUrl}/api/1/site/context/rebuild.json?cmsSite=${target.siteName}
      # Calls Clear Cache
      - processorName: httpMethodCallProcessor
        method: GET
        url: ${target.engineUrl}/api/1/site/cache/clear.json?cmsSite=${target.siteName}
      # Generates a deployment output file
      - processorName: fileOutputProcessor
Copy-icon

Из примеров выше видно, что большая часть конфигурации относится к разделу pipeline-а развертывания. Каждая запись в списке YAML представляет собой экземпляр прототипа bean-а DeploymentProcessor в Spring, который предопределен в файле base-context.xml. Если вы хотите определить собственный набор bean-ов DeploymentProcessor, вы можете включить их в новый файл контекста Spring на основе имени YAML-файла цели. На основе примера, упомянутого ранее, где YAML-файл назван editorial-preview.yaml, соответствующий файл контекста Spring будет называться editorial-preview-context.xml.

По умолчанию в CMS Deployer включены следующие bean-процессоры (bean processors):

  1. gitPullProcessor: клонирует удаленный репозиторий в локальный путь. Если репозиторий уже был клонирован, выполняется Git pull. Он особенно полезен для delivery-целей, которым необходимо извлекать изменения из сервера authoring-контента во время развертывания. Он должен быть первым процессором в списке, так как последующие процессоры работают с локальным репозиторием.

  2. gitDiffProcessor: вычисляет разницу между последним коммитом в локальном репозитории и последним обработанным коммитом, обычно сохраненным в ./processed-commits (в папке CMS_HOME/data/deployer/processed-commits). Вычисленная разница затем используется для построения набора изменений для развертывания. Следовательно, этот процессор должен быть вторым в списке.

  3. searchIndexingProcessor: извлекает файлы из набора изменений и передает их в CMS Search для индексации. Он выполняет обработку XML перед отправкой файлов, включая такие задачи, как выравнивание (рекурсивное включение компонентов), объединение унаследованных XML и извлечение метаданных для структурированных документов, таких как PDF и Word Docs.

  4. httpMethodCallProcessor: выполняет вызов HTTP-метода по указанному URL-адресу.

  5. fileOutputProcessor: генерирует вывод развертывания и сохраняет его в CSV-файле.

  6. mailNotificationProcessor: Этот процессор отправляет уведомление по электронной почте в случае успешного развертывания с изменениями файлов или в случае сбоя развертывания.

Управление целью (target)

Создание цели (target)

Есть два метода создания конфигурационного файла цели:

  • Использование конечной точки API createTarget, которая генерирует новую цель с использованием предопределенного шаблона. По умолчанию CMS Deployer включает два встроенных шаблона: один для локальных репозиториев (подходит для authoring-окружения), а другой для удаленных репозиториев (подходит для delivery-окружения). Кроме того, у вас есть возможность определить свои собственные шаблоны, расположенные в ./config/templates/targets. Та же конечная точка API может использоваться для создания целей на основе этих пользовательских шаблонов.
  • Размещение файла конфигурации цели в формате YAML в папке ./config/targets или CMS_HOME/data/deployer/targets, как уже упоминалось выше. CMS Deployer автоматически загрузит файл в соответствии с расписанием, и он будет обновляться при каждом изменении.

Обновление цели (target)

Обновление цели напоминает процесс её создания:

  • Используйте тот же API-эндпоинт, что и в процессе создания, но установите параметру replace значение true.
  • Внесите изменения напрямую в файл конфигурации цели. При следующем запланированном сканировании целей CMS Deployer обнаружит изменения файла и автоматически перезагрузит его.

Удаление цели (target)

Существует два способа удаления цели:

  • Вызовите эндпоинт API deleteTarget.
  • Удалите файл конфигурации цели в файловой системе.

Запуск развертывания

CMS Deployer обеспечивает возможность выполнения запланированных развертываний для указанной цели через опцию deployment.scheduling.enabled, которая по умолчанию включена. Однако, если вы хотите инициировать развертывание вручную, вы можете просто вызвать эндпоинт API deployTarget (или deployAllTargets). Это действие запустит развертывание, при условии, что запрос сформулирован правильно. Для отслеживания хода выполнения как запланированного, так и вручную запущенного развертывания обратитесь к логам CMS Deployer. По завершении развертывания, если цель включает fileOutputProcessor в pipeline-е развертывания, будет создан и сохранен CSV-файл, содержащий окончательный результат конкретного развертывания, по пути ./logs (или CMS_HOME/logs/deployer).

Обработанные коммиты

CMS Deployer сохраняет запись о идентификаторе последнего коммита, обработанного во время предыдущего развертывания, для каждой цели (target). Во время развертывания он использует этот идентификатор коммита для получения списка измененных файлов в репозитории. По умолчанию обработанные коммиты сохраняются в папке (CMS_HOME/data/deployer/processed-commits) с отдельными файлами для каждой цели (например, editorial-preview.commit). Каждый файл содержит только идентификатор коммита для отслеживания изменений во время развертывания. Например: 0be0d2e52283c17b834901e9cda6332d06fb05b6.

Если репозиторий изменяется вручную с помощью команд Git вместо обновления файлов через CMS Studio, существует потенциальная возможность конфликтов во время развертывания, например, если определенный коммит удален из репозитория. В большинстве случаев CMS Deployer спроектирован для обнаружения и автоматического разрешения таких конфликтов. Однако, если развертывание не удается успешно завершиться, можно использовать шаги устранения неполадок, описанные в разделе "Устранение неполадок с CMS Deployer".

Изменение или удаление файла обработанного коммита следует осуществлять осторожно, так как это может привести к переиндексации неизмененных файлов.

Процессоры CMS Deployer

CMS Deployer обладает обширным набором процессоров развертывания, которые могут быть легко интегрированы в любую цель (target) для удовлетворения конкретных потребностей. Несколько примеров сценариев, которые можно обработать с использованием этих процессоров развертывания:

  1. Передача контента, созданного или измененного в CMS Studio, во внешний сервис.
  2. Получение контента, созданного или отредактированного из внешнего сервиса.
  3. Выполнение действий после каждого успешного или неудачного развертывания.

При внедрении процессоров или настройке последовательности развертывания для цели порядок выполнения определяется конфигурационным файлом. Кроме того, определенные процессоры требуют определенных позиций в pipeline-е развертывания.

Основные процессоры развертывания

Основные процессоры развертывания способны выполнять различные задачи, связанные с выявлением измененных файлов или обработкой файлов, выявленных другими процессорами как измененные. Для обработки измененных файлов процессор может взаимодействовать с любым необходимым внешним сервисом по мере необходимости.

Все процессоры развертывания поддерживают следующие свойства:

Название Обязательно/необязательно Значение по умолчанию Описание
processorLabel Необязательно None Лейбл, что другие процессоры могут перейти к данному
jumpTo Необязательно None Лейбл процессора, к которому нужно перейти, после успешного выполнения
includeFiles Необязательно None Список регулярных выражений для проверки файлов, которые следует включить
excludeFiles Необязательно None Список регулярных выражений для проверки файлов, которые следует исключить
alwaysRun Необязательно false Указывает, следует ли запускать процессор даже в случае отсутствия изменений в текущем развертывании
failDeploymentOnFailure Необязательно false Включает возможность прерывания развертывания в случае сбоя процессора

Процессор Git Pull

Процессор, осуществляющий копирование или извлечение удаленного репозитория Git в локальный путь файловой системы.

Должен быть первым процессором в pipeline-е.

Свойства:

Название Обязательно/необязательно Значение по умолчанию Описание
remoteRepo.url Обязательно   URL-адрес удаленного Git репозитория для извлечения
remoteRepo.name Необязательно origin Имя, которое будет использоваться для удаленного репозитория при извлечении из него
remoteRepo.branch Необязательно Ветвь по умолчанию в репозитории Ветвь удаленного Git-репозитория для извлечения
remoteRepo.username Необязательно   Имя пользователя для аутентификации в удаленном Git-репозитории. Не требуется, если используется SSH с аутентификацией по паре ключей RSA
remoteRepo.password Необязательно   Пароль для аутентификации в удаленном Git-репозитории. Не требуется, если используется SSH с аутентификацией по паре ключей RSA
remoteRepo.ssh.privateKey.path Необязательно   Путь к закрытому ключу SSH, если используется SSH с аутентификацией по паре ключей RSA
remoteRepo.ssh.privateKey.passphrase Необязательно   Фраза-пароль закрытого ключа SSH, если используется SSH с аутентификацией по паре ключей RSA
failDeploymentOnFailure Необязательно true Включает сбой развертывания при сбое процессора

Примеры:

  • Процессор Git Pull, использующий базовую аутентификацию

- processorName: gitPullProcessor
  remoteRepo:
    url: https://github.com/myuser/mysite.git
    branch: live
    username: myuser
    password: mypassword
Copy-icon
  • Процессор Git Pull, использующий SSH с парой ключей RSA

- processorName: gitPullProcessor
  remoteRepo:
    url: https://github.com/myuser/mysite.git
    branch: live
    ssh:
      privateKey:
        path: /home/myuser/myprivatekey
        passphrase: mypassphrase
Copy-icon

Процессор Git Diff

Процессор, который, используя ранее обработанный сохраненный коммит, сравнивает его с текущим коммитом развертывания для определения набора изменений. Если ранее обработанный коммит отсутствует, весь репозиторий считается набором изменений.

Этот процессор должен быть размещен после gitPullProcessor и перед любым другим процессором, таким как searchIndexingProcessor.

Свойства:

Название Обязательно/необязательно Значение по умолчанию Описание
includeGitLog Небязательно false Указывает, следует ли включать сведения логов git в набор изменений
updateCommitStore Необязательно true Указывает, следует ли изменить значение обработанного коммита
failDeploymentOnFailure Необязательно true Включает сбой развертывания при сбое процессора

Пример:

- processorName: gitDiffProcessor
  includeGitLog: true
Copy-icon

Процессор Git Push

Процессор, который отправляет локальный репозиторий в удаленный репозиторий Git.

Свойста:

Название Обязательно/необязательно Значение по умолчанию Описание
localRepoBranch Обязательно   Ветвь локального репозитория для отправки
remoteRepo.url Обязательно   URL-адрес удаленного Git-репозитория, в который нужно отправить
remoteRepo.branch Необязательно Ветвь удаленного Git-репозитория, в который нужно отправить  
remoteRepo.username Необязательно   Имя пользователя для аутентификации в удаленном Git-репозитории. Не требуется, если используется SSH с аутентификацией по паре ключей RSA
remoteRepo.password Необязательно   Пароль для аутентификации в удаленном Git-репозитории. Не требуется, если используется SSH с аутентификацией по паре ключей RSA
remoteRepo.ssh.privateKey.path Необязательно   Путь к закрытому ключу SSH, если используется SSH с аутентификацией по паре ключей RSA
remoteRepo.ssh.privateKey.passphrase Необязательно   Фраза-пароль закрытого ключа SSH, если используется SSH с аутентификацией по паре ключей RSA
force Необязательно false Устанавливает предпочтение использования принудительной (force) передачи данных при отправке
pushAll Необязательно false Указывает, все ли локальные ветви должны быть отправлены в удаленный репозиторий

Пример:

  • Git Push-процессор, использующий базовую аутентификацию

- processorName: gitPushProcessor
  remoteRepo:
    url: https://github.com/myuser/mysite.git
    branch: deployed
    username: myuser
    password: mypassword
Copy-icon
  • Git Push-процессор, использующий SSH с парой ключей RSA

- processorName: gitPushProcessor
  remoteRepo:
    url: https://github.com/myuser/mysite.git
    branch: deployed
    ssh:
      privateKey:
        path: /home/myuser/myprivatekey
        passphrase: mypassphrase
Copy-icon

Процессор обновления идентификатора коммита в Git

Процессор, который обновляет значение обработанных коммитов текущим коммитом.

Пример:

- processorName: gitUpdateCommitIdProcessor
Copy-icon

Процессор Groovy Script

Процессор, который может обрабатывать опубликованный контент.

Свойства:

Название Обязательно/необязательно Значение по умолчанию Описание
scriptPath Обязательно   Относительный путь к исполняемому скрипту

Путь по умолчанию, по которому загружаются скрипты, - $CMS_HOME/bin/cms-deployer/processors/scripts

Пример:

- processorName: scriptProcessor
  scriptPath: 'myscripts/mychanges.groovy'
Copy-icon

Следующие переменные доступны для использования в ваших скриптах:

Имя переменной Описание
logger Логгер (logger) процессора: http://www.slf4j.org/api/org/slf4j/Logger.html
applicationContext Контекст приложения текущей цели (target): https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/ApplicationContext.html
deployment Текущее развертывание
execution Выполнение этого процессора
filteredChangeSet Подмножество исходного набора изменений, которое соответствует шаблону includeFiles и не соответствует шаблону excludeFiles для данного процессора
originalChangeSet Начальный набор изменений, возвращенный предыдущими процессорами в pipeline-е

Рассмотрим пример скрипта для использования в процессоре Groovy Script. Вот скрипт, который добавляет файл из набора изменений только в случае, если в развертывании присутствует определенный параметр:

import ru.dc.cms.deployer.api.ChangeSet

logger.info("starting script execution")

def specialFile = "/site/website/expensive-page-to-index.xml"

// if the file has been changed but the param was not sent then remove it from the change set
if (originalChangeSet.getUpdatedFiles().contains(specialFile) && !deployment.getParam("index_expensive_page")) {
    originalChangeSet.removeUpdatedFile(specialFile)
}

// return the new change set
return originalChangeSet
Copy-icon

Процессор событий развертывания на основе файлов

Процессор, который отвечает за запуск события развертывания, на которое могут подписаться пользователи репозитория (CMS Engines) путем чтения файла из репозитория.

Свойства:

Название Обязательно/необязательно Значение по умолчанию Описание
deploymentEventsFileUrl Необязательно deployment-events.properties Относительный путь к файлу событий развертывания
eventName Обязательно   Имя события для запуска

Пример:

- processorName: fileBasedDeploymentEventProcessor
  eventName: 'events.deployment.rebuildContext'
Copy-icon

Процессор командной строки

Процессор, который запускает процесс командной строки.

Название Обязательно/необязательно Значение по умолчанию Описание
workingDir Небязательно Директория CMS Deployer Директория, из которой будет запущен процесс
command Обязательно   Полная команда, которую будет выполнять процесс
processTimeoutSecs Необязательно 30 Количество секунд, в течение которых необходимо дождаться завершения процесса
includeChanges Необязательно   Добавлены дополнительные параметры
Пример: script.sh SITE_NAME OPERATION (CREATE/UPDATE/DELETE) FILE (относительный путь к файлу)

Пример:

- processorName: commandLineProcessor
  workingDir: '/home/myuser/myapp/bin'
  command: 'myapp -f --param1=value1'
Copy-icon

Процессор индексирования поиска

Процессор, осуществляющий индексацию файлов в наборе изменений с использованием одного или нескольких BatchIndexer. После завершения процесса индексации, процессор осуществляет отправку коммита.

Свойства:

Название Обязательно/необязательно Значение по умолчанию Описание
ignoreIndexId Небязательно false Указывает на то, должен ли быть проигнорирован ID индекса
indexId Необязательно Значение siteName Конкретный ID индекса для использования
reindexItemsOnComponentUpdates Необязательно true Флаг, определяющий, что при обновлении компонента также необходимо обновить все другие страницы и компоненты, которые его включают

Пример:

- processorName: searchIndexingProcessor
Copy-icon

Процессор вызова HTTP-метода

Выполняет вызов HTTP-метода.

Свойства:

Название Обязательно/необязательно Значение по умолчанию Описание
url Обязательно
URL-адрес для вызова
method Обязательно
HTTP-метод

Пример:

- processorName: httpMethodCallProcessor
  method: GET
  url: 'http://localhost:8080/api/1/site/cache/clear.json?cmsSite=mysite'
Copy-icon

Процессор задержки

Процессор, который останавливает выполнение pipeline-а на заданное количество секунд.

Свойства:

Название Обязательно/необязательно Значение по умолчанию Описание
seconds Необязательно 5 Количество секунд ожидания

Пример:

- processorName: delayProcessor
  seconds: 10
Copy-icon

Процессор поиска и замены

Процессор, заменяющий шаблон в содержимом созданных или обновленных файлов.

Файлы, измененные этим процессором, не будут зафиксированы в репозитории Git и будут удалены при следующем запуске развертывания.

Свойства:

Название Обязательно/необязательно Значение по умолчанию Описание
textPattern Обязательно   Регулярные выражения для поиска в файле
replacement Обязательно   Выражение для замены совпадений
failDeploymentOnFailure Необязательно true Включает сбой развертывания при сбое процессора

Пример:

- processorName: findAndReplaceProcessor
  textPattern: (/static-assets/[^"<]+)
  replacement: 'http://mycdn.com$1'
Copy-icon

Процессоры AWS

Все процессоры развертывания, связанные со службами AWS, поддерживают следующие свойства:

Название Обязательно/необязательно Значение по умолчанию Описание
region Необязательно Если не предоставлено, будут использоваться значения AWS SDK по умолчанию Регион AWS
accessKey Необязательно Если не предоставлено, будут использоваться значения AWS SDK по умолчанию Ключ доступа AWS
secretKey Необязательно Если не предоставлено, будут использоваться значения AWS SDK по умолчанию Секретный ключ AWS
url Обязательно
URL-адрес S3 бакета AWS для загрузки файлов
failDeploymentOnFailure Необязательно true Включает сбой развертывания при сбое процессора
Процессор синхронизации S3

Процессор, который синхронизирует файлы с S3 бакетом AWS.

Пример:

- processorName: s3SyncProcessor
  url: s3://serverless-sites/site/mysite
Copy-icon
Процессор событий развертывания S3

Процессор, который загружает события развертывания в S3 бакет AWS.

Свойства:

Название Обязательно/необязательно Значение по умолчанию Описание
deploymentEventsFileUrl Необязательно deployment-events.properties URL-адрес файла событий развертывания, относящийся к локальному репозиторию git

Пример:

- processorName: s3DeploymentEventsProcessor
  region: ${aws.region}
  accessKey: ${aws.accessKey}
  secretKey: ${aws.secretKey}
  url: {{aws.s3.url}}
Copy-icon
Процессор аннулирования Cloudfront

Процессор, который делает недействительными измененные файлы в данных дистрибутивах AWS Cloudfront.

Свойства:

Название Обязательно/необязательно Значение по умолчанию Описание
distributions Обязательно   Список идентификаторов дистрибутивов

Пример:

- processorName: cloudfrontInvalidationProcessor
  distributions:
    - E15UHQPTKROC8Z
Copy-icon

Процессоры постразвертывания

Процессоры постразвертывания работают основываясь на предположении о том, что все измененные файлы были обработаны, и результат развертывания известен (либо успешный, либо неудачный). Следовательно, эти процессоры должны находиться после всех основных процессоров развертывания для эффективной работы, так как они реагируют в соответствии с установленными результатами.

Процессор вывода файлов

Постпроцессор, сохраняющий результат развертывания в выходной CSV-файл в директории CMS_HOME/logs/deployer, предназначен для последующего доступа в случае сбоя развертывания или обработки файлов.

Пример:

- processorName: fileOutputProcessor
Copy-icon

Процессор почтовых уведомлений

Постпроцессор, предназначенный для отправки уведомления по электронной почте с результатом развертывания, активируется в случае сбоя развертывания или успешной обработки файлов. Если присутствует выходной файл, созданный fileOutputProcessor, он прикрепляется к электронному письму.

Свойства:

Название Обязательно/необязательно Значение по умолчанию Описание
templateName Необязательно default Название шаблона Freemarker, используемого для создания электронного письма
from Необязательно noreply@example.com Значение поля “Отправитель” в электронных письмах
to Обязательно
Значение поля “Получатель” в электронных письмах
subject Необязательно Deployment Report Значение поля “Тема” в электронных письмах
html Необязательно true Указывает, являются ли письма HTML
serverName Необязательно Текущее имя локального хоста Имя хоста почтового сервера
dateTimePattern Необязательно MM/dd/yyyy hh:mm:ss.SSS a z Шаблон даты и времени, который следует использовать при указании даты в электронном письме
status Необязательно ON_ANY_STATUS Указывает, для какого статуса развертывания следует отправлять электронные письма.
Возможные значения:
  • ON_ANY_STATUS - отправлять уведомления для всех развертываний
  • ON_ANY_FAILURE - отправлять уведомления для развертываний, в которых произошел сбой по крайней мере одного процессора
  • ON_TOTAL_FAILURE - отправлять уведомления для развертываний, в которых общий статус указывает на сбой

Пример:

- processorName: mailNotificationProcessor
  to:
    - admin@example.com
    - author@example.com
  status: ON_ANY_FAILURE
Copy-icon

Пример полного pipeline

В примере ниже показано, как процессоры развертывания работают вместе для бессерверного сайта с использованием сервисов AWS.

pipeline:
  # -------------------- START OF MAIN PIPELINE --------------------

  # First clone or update the local repository from github
  - processorName: gitPullProcessor
    remoteRepo:
      url: https://github.com/myuser/mysite.git
      branch: live
      username: myuser
      password: my_secret_password

  # Then find the added/changed/deleted files since the previous pull (if any)

  - processorName: gitDiffProcessor

  # Change all references to static-assets to use a CDN URL instead of the local URL
  - processorName: findAndReplaceProcessor
    includeFiles: ['^/site/.*$', '^/templates/.*$', '^/static-assets/.*(js|css|html)$']
    textPattern: (/static-assets/[^"<]+)
    replacement: 'http://d111111abcdef8.cloudfront.net$1'

  # Index the changes in search
  - processorName: searchIndexingProcessor

  # Sync the changes in a S3 bucket
  - processorName: s3SyncProcessor
    url: s3://serverless-sites/site/mysite

  # Add a small delay to allow the S3 changes to propagate
  - processorName: delayProcessor

  # Invalidate the changed files in the CDN
  - processorName: cloudfrontInvalidationProcessor
    includeFiles: ['^/static-assets/.*$']
    distributions:
      - E15UHQPTKROC8Z

  # Trigger deployment events so any CMS Engine listening can update accordingly:
  # Rebuild the site context if any config or script has changed
  - processorName: fileBasedDeploymentEventProcessor
    includeFiles: ["^/?config/.*$", "^/?scripts/.*$"]
    excludeFiles: ['^/config/studio/content-types/.*$']
    eventName: 'events.deployment.rebuildContext'

  # Clear the cache if any static-asset has changed
  - processorName: fileBasedDeploymentEventProcessor
    excludeFiles: ['^/static-assets/.*$']
    eventName: 'events.deployment.clearCache'

  # Rebuild the GraphQL schema if any content-type has changed
  - processorName: fileBasedDeploymentEventProcessor
    includeFiles: ['^/config/studio/content-types/.*$']
    eventName: 'events.deployment.rebuildGraphQL'

  # Push the updated events to the S3 bucket
  - processorName: s3SyncProcessor
    includeFiles: ['^/?deployment-events\.properties$']
    url: s3://serverless-sites/site/mysite

  # -------------------- END OF MAIN PIPELINE --------------------
  # Only Post Processors can be in this section

  # Record the result of the deployment to a CSV file
  - processorName: fileOutputProcessor

  # Notify the site admin & an author if there were any failures during the deployment
  - processorName: mailNotificationProcessor
    to:
      - admin@example.com
      - author@example.com
    status: ON_ANY_FAILURE
Copy-icon

Кастомные процессоры

CMS Deployer можно легко настроить на соответствие различным требованиям. Если возникает потребность в расширении функциональности, вы также можете внедрить пользовательские библиотеки, следуя этим инструкциям:

Шаг 1: Создайте кастомный процессор
Пользовательские процессоры могут использовать любую библиотеку или набор инструментов от сторонних разработчиков. Единственное требование - определить класс, реализующий интерфейс DeploymentProcessor.

Настоятельно рекомендуется расширять либо AbstractDeploymentProcessor, либо AbstractMainDeploymentProcessor, а не только реализовывать интерфейс.

Для доступа к этим классам просто добавьте зависимость в ваш проект:

<dependency>
  <groupId>ru.dc.cms</groupId>
  <artifactId>cms-deployer</artifactId>
  <version>${dccms.version}</version>
</dependency>
Copy-icon

Шаг 2: Добавьте кастомный процессор
Пользовательские процессоры интегрируются в CMS Deployer путем размещения всех необходимых JAR-файлов в папке INSTALL_DIR/bin/cms-deployer/lib.

Обязательно внимательно проверьте все зависимости в вашем проекте, чтобы избежать конфликтов с библиотеками, используемыми CMS Deployer или другими пользовательскими процессорами.

Шаг 3: Настройте кастомный процессор
После размещения пользовательского процессора в classpath остается всего лишь один шаг — создать или обновить цель (target) для его включения. Все файлы конфигурации для целей будут храниться в папке INSTALL_DIR/data/deployer/targets.

Для начала необходимо создать или обновить файл контекста, который определяет все bean-ы, необходимые для пользовательского процессора. Файл должен иметь имя {site}-{env}-context.xml.

<bean id="externalService" class="com.example.Service">
  <property name="url" value="${service.url}"/>
  <property name="port" value="${service.port}"/>
</bean>

<bean id="myCustomProcessor" class="com.example.CustomProcessor" parent="deploymentProcessor">
  <property name="service" ref="externalService"/>
</bean>
Copy-icon

Родительский bean предоставляется CMS Deployer и включает общие конфигурации, используемые классами AbstractDeploymentProcessor и AbstractMainDeploymentProcessor.

После того как bean определен, его можно добавить в конвейер цели в файле YAML с соответствующим именем {site}-{env}.yaml.

target:
  env: preview
  siteName: mySite
  deployment:
    scheduling:
      enabled: false
    pipeline:
      - processorName: myCustomProcessor
        username: john
        password: passw0rd!
service:
  url: http://www.example.com
  port: 8080
Copy-icon

Любые изменения в classpath потребуют перезапуска CMS Deployer, в то время как изменения в файлах конфигурации будут применены при перезагрузке цели.

Шаблоны цели (target)

При создании цели в CMS Deployer можно воспользоваться одним из встроенных шаблонов, который легко настраивается с использованием дополнительных параметров при его создании.

Встроенные шаблоны

Все шаблоны целей поддерживают следующие параметры:

Название Обязательно/необязательно Описание
env Обязательно Окружение цели (например, dev)
site_name Обязательно Название сайта цели (например, website)
repo_url Обязательно URL-адрес репозитория цели

Authoring-цель

Этот шаблон используется CMS Studio при создании нового проекта или сайта. Он настраивает цель, специально предназначенный для функционала поиска CMS Studio, включая индексацию XML-файлов, бинарных файлов, а также дополнительных метаданных Git из репозитория сайта.

Эта цель предназначена для:

  1. Определения измененных файлов на основе истории локального Git-репозитория.
  2. Индексации всего контента сайта для поиска.

Для этого целевого объекта не требуется дополнительных параметров.

При использовании этой цели необходимо установить значение repo_url как локальный путь к файловой системе.

Локальная цель

Это второй шаблон, используемый CMS Studio при создании нового проекта. Этот шаблон настраивает цель для предварительного просмотра проекта.

Цель предназначена для:

  1. Определения измененных файлов на основе истории локального Git-репозитория.
  2. Индексации всего содержимого проекта для поиска.
  3. Пересборки контекста сайта CMS Engine при изменениях в файлах конфигурации или Groovy-скриптах.
  4. Очистки кэша CMS Engine.
  5. Пересборки схемы GraphQL проекта CMS Engine при изменениях в определениях типов контента.
  6. Отправки уведомлений по электронной почте, если это включено.

Параметры:

Название Обязательно/необязательно Описание
disable_deploy_cron Необязательно Отключает запланированное задание (cron job), которое выполняет развертывание с определенной периодичностью
notification_addresses Необязательно Адреса электронной почты, на которые должны приходить уведомления о развертывании

Когда используется эта цель, значение repo_url должно быть путем к локальной файловой системе.

Удаленная цель

Это шаблон по умолчанию, используемый CMS Engine в delivery-окружении. Он напоминает локальную цель, но поддерживает удаленные Git-репозитории.

Эта цель настроена на:

  1. Клонирование удаленного репозитория при необходимости.
  2. Извлечение последних изменений из удаленного репозитория (с удалением всех локальных незафиксированных или конфликтующих файлов).
  3. Определение измененных файлов на основе истории Git-репозитория.
  4. Индексацию всего содержимого проекта в соответствующем поисковом механизме.
  5. Пересборку контекста сайта CMS Engine при изменениях в файлах конфигурации или Groovy-скриптах.
  6. Очистку кэша CMS Engine.
  7. Пересборку схемы GraphQL проекта CMS Engine при изменениях в определениях типов контента.
  8. Отправку уведомлений по электронной почте (если включено).

Параметры:

Название Обязательно/необязательно Описание
disable_deploy_cron Необязательно Отключает запланированное задание (cron job), которое выполняет развертывание с определенной периодичностью
repo_branch Необязательно Имя ветви удаленного Git-репозитория, из которого нужно извлечь
repo_username Необязательно Имя пользователя для доступа к удаленному репозиторию
repo_password Необязательно Пароль для доступа к удаленному репозиторию
ssh_private_key_path Необязательно Путь к закрытому ключу для доступа к удаленному репозиторию
ssh_private_key_passphrase Необязательно Фраза-пароль к закрытому ключу для доступа к удаленному репозиторию ( если ключ защищен парольной фразой)
notification_addresses Необязательно Адреса электронной почты, на которые должны приходить уведомления о развертывании

Когда используется эта цель, значение repo_url должно быть поддерживаемым Git URL (HTTP или SSH).

Цель AWS S3 Copy-icon

Этот шаблон используется для CMS Engine в бессерверном delivery-окружении. Он напоминает удаленную цель, но поддерживает синхронизацию файлов с бакетом AWS S3 и также управляет инвалидациями AWS Cloudfront.

Эта цель настроена для:

  1. Клонирования удаленного репозитория при необходимости.
  2. Извлечение последних изменений из удаленного репозитория (с удалением всех локальных незафиксированных или конфликтующих файлов).
  3. Определения измененных файлов на основе истории Git-репозитория.
  4. Индексации всего содержимого проекта для поиска.
  5. Синхронизации всех новых, обновленных и удаленных файлов с бакетом AWS S3.
  6. Выполнения инвалидации для всех обновленных файлов в одном или нескольких дистрибутивах AWS Cloudfront.
  7. Отправки событий развертывания для всех экземпляров CMS Engine:
    • Пересборки контекста сайта при изменениях в файлах конфигурации или Groovy-скриптах.
    • Очистки кэша проекта.
    • Пересборки схемы GraphQL сайта при изменениях в определениях типов контента.
  8. Отправки уведомлений по электронной почте (если включено).

Параметры:

Название Обязательно/необязательно Описание
aws.region Необязательно Регион AWS для использования
aws.access_key Необязательно Ключ доступа AWS для использования
aws.secret_key Необязательно Секретный ключ AWS для использования
aws.distribution.ids Необязательно Массив идентификаторов распределения AWS Cloudfront для выполнения инвалидаций
aws.s3.url Обязательно Полный AWS S3 URI папки для синхронизации файлов
disable_deploy_cron Необязательно Отключает запланированное задание (cron job), которое выполняет развертывание с определенной периодичностью
local_repo_path Необязательно Локальный путь, по которому следует поместить удаленный клон Git-репозитория
repo_branch Необязательно Имя ветви удаленного Git-репозитория, из которого нужно извлечь
repo_username Необязательно Имя пользователя для доступа к удаленному репозиторию
repo_password Необязательно Пароль для доступа к удаленному репозиторию
ssh_private_key_path Необязательно Путь к закрытому ключу для доступа к удаленному репозиторию
ssh_private_key_passphrase Необязательно Фраза-пароль к закрытому ключу для доступа к удаленному репозиторию (если ключ защищен парольной фразой)
notification_addresses Необязательно Адреса электронной почты, на которые должны приходить уведомления о развертывании


Когда используется эта цель, значение repo_url должно быть поддерживаемым Git URL (HTTP или SSH).

Дополнительные сведения о настройке бессерверного delivery-процесса можно найти здесь.

Цель AWS CloudFormation

Этот шаблон упрощает создание серверного delivery-окружения без необходимости вручную создавать ресурсы в AWS. Он работает аналогично цели AWS S3, но использует шаблон AWS CloudFormation для создания основных ресурсов AWS во время создания цели. Эти ресурсы включают в себя S3-бакет, предназначенный для хранения контента сайта, и дистрибутив CloudFront, отвечающий за обслуживание балансировщика нагрузки CMS Engine и прямую доставку статических активов из S3-бакета. При удалении цели эти ресурсы автоматически удаляются.

Данная цель настроена для:

  1. Клонирования удаленного репозитория при необходимости.
  2. Извлечение последних изменений из удаленного репозитория (с удалением всех локальных незафиксированных или конфликтующих файлов).
  3. Определения измененных файлов на основе истории Git-репозитория.
  4. Индексации всего содержимого проекта для поиска.
  5. Синхронизации всех новых, обновленных и удаленных файлов с бакетом AWS S3.
  6. Выполнения инвалидации для всех обновленных файлов в дистрибутиве AWS Cloudfront.
  7. Отправки событий развертывания для всех экземпляров CMS Engine:
    • Пересборки контекста сайта при изменениях в файлах конфигурации или Groovy-скриптах.
    • Очистки кэша проекта.
    • Пересборки схемы GraphQL сайта при изменениях в определениях типов контента.
  8. Отправки уведомлений по электронной почте (если включено).

Параметры:

Название Обязательно/необязательно Описание
aws.region Необязательно Регион AWS для использования
aws.default_access_key Необязательно Ключ доступа AWS для использования в S3 и CloudFront
aws.default_secret_key Необязательно Секретный ключ AWS для использования в S3 и CloudFront
aws.cloudformation.namespace Обязательно Префикс, используемый для имен ресурсов CloudFormation
aws.cloudformation.deliveryLBDomainName Обязательно Доменное имя Engine delivery LB
aws.cloudformation.cloudfrontCertificateArn Необязательно RN SSL-сертификата CloudFront
aws.cloudformation.alternateCloudFrontDomainNames Необязательно Альтернативные доменные имена для использования CloudFront (должны совпадать с действительными доменными именами сертификатов)
aws.cloudformation.access_key Необязательно Ключ доступа AWS для использования в CloudFormation
aws.cloudformation.secret_key Необязательно Секретный ключ AWS для использования в CloudFormation
local_repo_path Необязательно Локальный путь, по которому следует поместить удаленный клон Git-репозитория
repo_branch Необязательно Имя ветви удаленного Git-репозитория, из которого нужно извлечь
repo_username Необязательно Имя пользователя для доступа к удаленному репозиторию
repo_password Необязательно Пароль для доступа к удаленному репозиторию
ssh_private_key_path Необязательно Путь к закрытому ключу для доступа к удаленному репозиторию
ssh_private_key_passphrase Необязательно Фраза-пароль к закрытому ключу для доступа к удаленному репозиторию (если ключ защищен парольной фразой)
notification_addresses Необязательно Адреса электронной почты, на которые должны приходить уведомления о развертывании

Когда используется эта цель, значение repo_url должно быть поддерживаемым Git URL (HTTP или SSH).

Конфигурация поиска

CMS Deployer предлагает два способа использования поиска.

Единый поисковый кластер

Это наиболее часто используемая конфигурация, все операции будут выполняться в одном поисковом кластере:

target:
  search:
    elasticSearch:
      # Single cluster
      urls:
        - ${env:SEARCH_URL}
      username: ${env:SEARCH_USERNAME}
      password: ${env:SEARCH_PASSWORD}
      timeout:
        # The connection timeout in milliseconds, if set to -1 the default will be used
        connect: -1
        # The socket timeout in milliseconds, if set to -1 the default will be used
        socket: -1
      # The number of threads to use, if set to -1 the default will be used
      threads: -1
      # Indicates if keep alive should be enabled for sockets used by the search client, defaults to false
      keepAlive: false
Copy-icon

Множественные поисковые кластеры

При использовании данной конфигурации все операции чтения будут осуществляться на одном поисковом кластере, тогда как операции записи будут выполняться на нескольких поисковых кластерах:

target:
   search:
     elasticSearch:
       # Global auth, used for all clusters
       username: search
       password: passw0rd
       # Cluster for read operations
       readCluster:
         urls:
           - 'http://read-cluster-node-1:9200'
           - 'http://read-cluster-node-2:9200'
           # This cluster will use the global auth
       # Clusters for write operations
       writeClusters:
         - urls:
           - 'http://write-cluster-1-node-1:9200'
           - 'http://write-cluster-1-node-2:9200'
           # This cluster will use the global auth
         - urls:
           - 'http://write-cluster-2-node-1:9200'
           - 'http://write-cluster-2-node-2:9200'
           # Override the global auth for this cluster
           username: search2
           password: passw0rd2
Copy-icon

Файлы конфигурации

Конфигурацию поиска можно изменить в двух местах:

  1. В глобальном файле конфигурации, расположенном по пути $CMS_HOME/bin/cms-deployer/config/base-target.yaml, изменения будут применены ко всем загруженным целям.

  2. В файле конфигурации индивидуальной цели по пути $CMS_HOME/data/deployer/targets/{siteName}-{environment}.yaml.

Связанные статьи

Общая конфигурация DC CMS

Документация для системного администратора