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

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

Настройка CMS Engine для delivery-процесса проекта

Delivery-процесс на основе сервера

В этом разделе вы узнаете, как настроить ваш проект для delivery-окружения.

Настройка цели развертывания

DC CMS предоставляет встроенный скрипт для упрощения создания цели развертывания для delivery-окружения.

В папке bin в вашем delivery-окружении мы будем использовать скрипт init-site.sh, который поможет нам создать целевой объект для развертывания.

Из командной строки перейдите в {CMS-delivery-environment-directory}/bin/ и выполните скрипт init-site. Ниже объяснение, как использовать этот скрипт:

usage: init-site [options] [site] [repo-path]
 -a,--notification-addresses <addresses>   A comma-separated list of email
                                           addresses that should receive
                                           deployment notifications
 -b,--branch <branch>                      The name of the branch to clone
                                           (live by default)
 -f,--passphrase <passphrase>              The passphrase of the private
                                           key (when the key is passphrase
                                           protected)
 -h,--help                                 Show usage information
 -k,--private-key <path>                   The path to the private key, when
                                           using private-key authentication
                                           through SSH to the remote Git repo
 -p,--password <password>                  The password for the remote Git
                                           repo, when using basic
                                           authentication
 -u,--username <username>                  The username for the remote Git
                                           repo, when using basic
                                           authentication
 --addresses <>                            A comma-separated list of email
                                           addresses that should receive deployment notifications

EXAMPLES:
 Init a site from the default repo path (../../cms-authoring/data/repos/sites/{sitename}/published)
     init-site mysite
 Init a site from a specific local repo path
     init-site mysite /opt/cms/authoring/data/repos/sites/mysite/published
 Init a site from a specific local repo path, cloning a specific branch of the repo
     init-site -b master mysite /opt/cms/authoring/data/repos/sites/mysite/published
 Init a site that is in a remote HTTPS repo with username/password authentication
     init-site -u jdoe -p jdoe1234 mysite https://github.com/jdoe/mysite.git
 Init a site that is in a remote SSH repo with public/private key authentication (specific private key path
 with no passphrase)
     init-site -k ~/.ssh/jdoe_key mysite ssh://myserver/opt/crater/sites/mysite
 Init a site that is in a remote SSH repo with public/private key authentication (specific private key path
 with passphrase)
     init-site -k ~/.ssh/jdoe_key -f jdoe123 mysite ssh://myserver/opt/crater/sites/mysite
Copy-icon

Помните, что при использовании SSH-аутентификации с закрытым ключом путь к ключу должен быть задан с помощью параметра -k. Пример: init-site -k ~/.ssh/jdoe_key myeditorial ssh://myserver/opt/crater/sites/myeditorial.

Мы рекомендуем использовать Secure Shell (SSH) с опубликованным URL-адресом Git репозитория вашего проекта, а для аутентификации использовать либо аутентификацию по имени пользователя/паролю, либо аутентификацию по открытому/закрытому ключу.

Формат URL-адреса SSH Git таков: ssh://[user@]host.xz[:port]/path/to/repo/, где разделы между [] необязательны.

Пример №1: ssh://server1.example.com/path/to/repo

Пример №2: ssh://jdoe@server2.example.com:63022/path/to/repo

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

DC CMS предписывает использование исключительно ключей RSA и не поддерживает ключи, созданные с использованием альтернативных алгоритмов, таких как OpenSSH. Библиотека Jsch, используемая Jgit, ограничивается ключами RSA и не предоставляет поддержки для других типов ключей. Кроме того, на данный момент DC CMS не позволяет использовать пароли с SSH-ключами.

Для создания ваших ключей Secure Shell (SSH) для аутентификации выполните следующую команду: ssh-keygen -m PEM -b 4096 -t rsa. Полученный вами результат должен быть похож на это:

✗ ssh-keygen -m PEM -b 4096 -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/Users/myuser/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/myuser/.ssh/id_rsa.
Your public key has been saved in /Users/myuser/.ssh/id_rsa.pub.
.
.
Copy-icon

Убедитесь, что файл начинается с заголовка -----BEGIN RSA PRIVATE KEY-----, чтобы подтвердить использование ключа RSA.

После создания закрытого и открытого ключей важно включить ваш только что созданный открытый ключ в место, где расположен ваш удаленный Git-репозиторий. Если GitHub - ваша выбранная платформа, добавьте ваш открытый ключ (например, id_rsa.pub) в ваш аккаунт GitHub. В противном случае, если ваш удаленный Git-репозиторий размещен на сервере, передайте ваш открытый ключ (например, id_rsa.pub) на сервер хостинга.

Если вы работаете с другой директорией на диске для вашего delivery-процесса, вы можете использовать файловую систему. Если ваш репозиторий локальный, обязательно используйте абсолютный путь. Вот пример Git URL опубликованного репозитория проекта при использовании локального репозитория: /opt/cms/authoring/data/repos/sites/my-project/published.

Тестовый просмотр вашего сайта

Чтобы протестировать ваш проект, откройте браузер и введите URL-адрес вашего проекта.

Если у вас настроено несколько проектов, для просмотра определенного проекта в вашем браузере введите следующее: {Server URL}?cmsSite={siteName}.

На скриншоте ниже у нас есть пример настройки delivery-процесса в другой директории на диске (локальном), где есть два проекта, "ecom" и "cms".

Изображение статьи

Чтобы настроить cmsSite для проекта "ecom", введите в своем браузере: http://localhost:9080?cmsSite=ecom.

Чтобы настроить сайт для проекта "cms", введите в вашем браузере: http://localhost:9080?cmsSite=cms.

Помимо параметра cmsSite, есть возможность включить заголовок с именем X-Cms-Site для указания имени сайта и внесения изменений в текущий сайт. Это особенно полезно при использовании CMS Engine в сочетании с CDN, способными отправлять заголовки, такими как AWS CloudFront.

Для успешной реализации этой конфигурации необходимо обеспечить, чтобы начальный запрос указывал имя сайта либо через параметр cmsSite, либо через заголовок X-Cms-Site. Это гарантирует, что значение сайта правильно установлено в cookie для последующих запросов.

Определение проекта для рендеринга в CMS Engine основано на следующем порядке приоритетов:

  1. Заголовки (X-Cms-Site={site})
  2. QSA (Параметры строки запроса: cmsSite={site})
  3. Cookie (cmsSite={site})

Более того, если cookie не соответствует другим параметрам, cookie будет сброшено, чтобы соответствовать предшествующим значениям. Важно отметить, что упомянутые условия применимы только тогда, когда CMS Engine не работает в режиме предварительного просмотра.

Бессерверный delivery-процесс

DC CMS можно настроить для хостинга веб-сайтов непосредственно с использованием служб AWS. Следуя этому руководству, вы сможете:

  1. Настроить домен AWS ElasticSearch (опционально).

  2. Настроить CMS Studio в authoring-окружении для вызова CMS Deployer с целью создания AWS CloudFormation с CloudFront и отдельным бакетом S3 для каждого сайта.

  3. Настроить CMS Engine в delivery-окружении для доступа к файлам из соответствующего бакета S3 и взаимодействия с AWS ElasticSearch (опционально).

Предварительные требования:

  • Учетная запись AWS
  • Authoring-окружение в DC CMS
  • Delivery-окружение в DC CMS

Шаг 1: Создание домена ElasticSearch для delivery-процесса (опционально)
Для эффективного бессерверного delivery-процесса важно установить единую конечную точку ElasticSearch, доступную всем экземплярам CMS Engine. Мы рекомендуем настроить домен AWS ElasticSearch для этой цели. В противном случае, если вы решите не использовать домен AWS ElasticSearch, вам нужно будет создать и управлять собственным кластером ElasticSearch.

Следует отметить, что authoring-процесс также может использовать домен ElasticSearch. Однако в кластеризованном authoring-окружении каждый authoring-экземпляр требует отдельного экземпляра ElasticSearch. Попытка использовать один и тот же домен ElasticSearch может привести к тому, что несколько предварительных deployer-ов будут записывать в один и тот же индекс.

Для создания домена AWS ElasticSearch выполните следующие шаги:

  1. Перейдите в верхнюю строку навигации консоли AWS, щелкните по выпадающему меню Аналитика и найдите Amazon ElasticSearch Service.

  2. Выберите Создать домен.

  3. Нажмите на Тип развертывания и выберите ближайшую к v2.8.0 версию ElasticSearch.

  4. На следующем экране введите имя домена. Сохраните настройки по умолчанию или измените их в соответствии с вашими требованиями, затем перейдите к следующему шагу.

  5. На экране Конфигурация сети рекомендуется выбрать VPC, где находятся ваши узлы доставки. Если вы не используете Amazon VPC, выберите общий доступ.

  6. Выберите политику доступа, соответствующую вашему окружению CMS. Нажмите Далее.

  7. Проверьте настройки и нажмите Подтвердить.

  8. Подождите несколько минут, пока домен не будет готов. Скопируйте эндпоинт, поскольку вам понадобится этот URL позже для настройки CMS Deployer и Delivery Engine, которым требуется доступ к ElasticSearch.

Шаг 2: Настройка delivery-процесса для бессерверного режима
Отредактируйте файл переопределения сервисов, чтобы включить бессерверный режим S3 (DELIVERY_INSTALL_DIR/bin/apache-tomcat/shared/classes/cms/engine/extension/services-context.xml):

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">

  <import resource="classpath*:cms/engine/mode/multi-tenant/simple/services-context.xml" />
  <!-- S3 Serverless Mode -->
  <import resource="classpath*:cms/engine/mode/serverless/s3/services-context.xml" />

</beans>
Copy-icon

Отредактируйте файл переопределения свойств, чтобы указать CMS Engine, который будет использовать содержимое сайта из S3 (DELIVERY_INSTALL_DIR/bin/apache-tomcat/shared/classes/cms/engine/extension/server-config.properties). Свойства, которые вам необходимо обновить, следующие:

  • cms.engine.site.default.rootFolder.path
  • cms.engine.s3.region
  • cms.engine.s3.accessKey
  • cms.engine.s3.secretKey

Примером того, как файл server-config.properties будет выглядеть с конфигурацией для чтения из бакета S3 для каждого сайта (что является наиболее распространенным вариантом использования), является следующее (значения в X не отображаются, поскольку они конфиденциальны):

# Content root folder when using S3 store. Format is s3://<BUCKET_NAME>/<SITES_ROOT>/{siteName}
cms.engine.site.default.rootFolder.path=s3://serverless-test-site-{siteName}/{siteName}
...

# S3 Serverless properties
# S3 region
cms.engine.s3.region=us-east-1
# AWS access key
cms.engine.s3.accessKey=XXXXXXXXXX
# AWS secret key
cms.engine.s3.secretKey=XXXXXXXXXXXXXXXXXXXX
Copy-icon

URL корневой папки S3 включает префикс и название сайта. Этот префикс упоминается как “пространство имен” позже в бессерверной конфигурации CMS Studio.

Мы рекомендуем, чтобы настроенные учетные данные AWS принадлежали пользователю только со следующей политикой разрешений (все строки, такие как $VAR, должны быть заменены):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:ListAllMyBuckets",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation",
                "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::$BUCKET_NAME_PREFIX-*"
        }
    ]
}
Copy-icon

Отредактируйте SEARCH_URL в переменных окружения, чтобы указать на конечную точку ElasticSearch, которую вы создали на предыдущем шаге:

export SEARCH_URL=https://vpc-serverless-test-jpwyav2k43bb4xebdrzldjncbq.us-east-1.es.amazonaws.com
Copy-icon

Убедитесь, что у вас есть load balancer приложений (ALB), предшествующий экземплярам Delivery Engine, и что он доступен через AWS CloudFront.

Шаг 3: Настройка authoring-процесса для бессерверного развертывания
Вместо использования CMS Deployer для каждого узла при delivery-процессе, бессерверное развертывание требует всего одного Deployer, ответственного за загрузку файлов в S3. Если есть только один authoring-узел, Deployer предварительного просмотра authoring может также служить для бессерверного развертывания. Однако в случаях с несколькими authoring-узлами, формирующими кластер, требуется отдельный Deployer. Этот Deployer должен извлекать данные из сбалансированного по нагрузке URL SSH/HTTPS, который представляет репозитории Git Studio.

В обоих случаях важно настроить CMS Studio на вызов Deployer для создания бессерверных целей при создании сайта. Соответствующие настройки конфигурации можно найти в файле CMS_HOME/bin/apache-tomcat/shared/classes/cms/studio/extension/studio-config-override.yaml. Хотя в файле предоставлена полная документация по свойствам, важно отметить некоторые существенные детали:

  • Вам нужно добавить URL-адрес домена ElasticSearch, созданного на предыдущем шаге, в разделе studio.serverless.delivery.deployer.target.template.params.search_url:

studio.serverless.delivery.deployer.target.template.params:
  # The delivery search endpoint (optional is authoring is using the same one, specified in the SEARCH_URL env variable)
  search_url: https://vpc-serverless-test-jpwyav2k43bb4xebdrzldjncbq.us-east-1.es.amazonaws.com
Copy-icon
  • При использовании шаблона цели aws-cloudformed-s3 по умолчанию, Deployer инициирует создание стека AWS CloudFormation. В этот стек входит бакет S3, предназначенный для загрузки контента сайта, а также настройка CloudFront, который обслуживает /static-assets напрямую. Кроме того, он перенаправляет все другие запросы на load balancer Delivery Engine, указанный в параметрах шаблона цели studio.serverless.delivery.deployer.target.template.params.aws.cloudformation.deliveryLBDomainName.
  • aws.cloudformation.namespace, по сути, служит префиксом для упомянутого ранее бакета S3. Этот префикс становится неотъемлемой частью имен, присвоенных большинству ресурсов AWS, созданных Deployer-ом серверных приложений в процессе развертывания.
  • Вам необходимо указать соответствующие учетные данные AWS для создания стека CloudFormation и загрузки файлов в S3, что можно сделать следующими способами:
    • В качестве переменных окружения или по пути к учетным данным AWS по умолчанию. Подробнее можно узнать здесь.
    • В свойствах aws.default_access_key и aws.default_secret_key в studio.serverless.delivery.deployer.target.template.params:

studio.serverless.delivery.deployer.target.template.params:
  aws:
    # AWS access key (optional if specified through default AWS chain)
    default_access_key: XXXXXXXXXX
    # AWS secret key (optional if specified through default AWS chain)
    default_secret_key: XXXXXXXXXXXXXXXXXXXX
Copy-icon
  • Мы рекомендуем, чтобы настроенные учетные данные AWS принадлежали пользователю только со следующей политикой разрешений (все строки, такие как $VAR, должны быть заменены):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudformation:CreateStack",
                "cloudformation:DescribeStacks",
                "cloudformation:DeleteStack"
            ],
            "Resource": "arn:aws:cloudformation:$REGION:$ACCOUNT_ID:stack/$CLOUDFORMATION_NAMESPACE-*/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "cloudfront:CreateDistribution",
                "cloudfront:GetDistribution",
                "cloudfront:GetDistributionConfig",
                "cloudfront:UpdateDistribution",
                "cloudfront:DeleteDistribution",
                "cloudfront:CreateInvalidation",
                "cloudfront:TagResource",
                "cloudfront:UntagResource"
            ],
            "Resource": "arn:aws:cloudfront::$ACCOUNT_ID:distribution/*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "cloudfront:CreateCloudFrontOriginAccessIdentity",
                "cloudfront:GetCloudFrontOriginAccessIdentityConfig",
                "cloudfront:GetCloudFrontOriginAccessIdentity",
                "cloudfront:DeleteCloudFrontOriginAccessIdentity"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:CreateBucket",
                "s3:ListBucket",
                "s3:DeleteBucket",
                "s3:GetBucketLocation",
                "s3:GetBucketPolicy",
                "s3:PutBucketPolicy",
                "s3:DeleteBucketPolicy",
                "s3:PutBucketCORS",
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::$CLOUDFORMATION_NAMESPACE-*"
        }
    ]
}
Copy-icon

Ниже приведен пример конфигурации бессерверного развертывания, в которой имеется один authoring-экземпляр и отсутствуют конкретные требования к доменному имени:

##########################################################
##                 Serverless Delivery                  ##
##########################################################
# Indicates if serverless delivery is enabled
studio.serverless.delivery.enabled: true
# The URL for the serverless delivery deployer create URL
studio.serverless.delivery.deployer.target.createUrl: ${studio.preview.createTargetUrl}
# The URL for the serverless delivery deployer delete URL
studio.serverless.delivery.deployer.target.deleteUrl: ${studio.preview.deleteTargetUrl}
# The template name for serverless deployer targets
studio.serverless.delivery.deployer.target.template: aws-cloudformed-s3
# Replace existing target configuration if one exists?
studio.serverless.delivery.deployer.target.replace: false
# The URL the deployer will use to clone/pull the site's published repo. When the deployer is in a separate node
# (because of clustering), this URL should be an SSH/HTTP URL to the load balancer in front of the Studios
studio.serverless.delivery.deployer.target.remoteRepoUrl: ${env:CMS_DATA_DIR}/repos/sites/{siteName}/published
# The deployer's local path where it will store the clone of the published site. This property is not needed if
# the deployer is not the preview deployer, so you can leave an empty string ('') instead
studio.serverless.delivery.deployer.target.localRepoPath: ${env:CMS_DATA_DIR}/repos/aws/{siteName}
# Parameters for the target template. Please check the deployer template documentation for the possible parameters.
# The following parameters will be sent automatically, and you don't need to specify them: env, site_name, replace,
# disable_deploy_cron, local_repo_path, repo_url, use_cms_search
studio.serverless.delivery.deployer.target.template.params:
   # The delivery search endpoint (optional if authoring is using the same one, specified in the SEARCH_URL env variable)
   search_url: https://vpc-serverless-test-jpwyav2k43bb4xebdrzldjncbq.us-east-1.es.amazonaws.com
   aws:
     # AWS access key (optional if specified through default AWS chain)
     default_access_key: XXXXXXXXXX
     # AWS secret key (optional if specified through default AWS chain)
     default_secret_key: XXXXXXXXXXXXXXXXXXXX
     cloudformation:
       # Namespace to use for CloudFormation resources (required when target template is aws-cloudformed-s3)
       namespace: serverless-test
       # The domain name of the serverless delivery LB (required when target template is aws-cloudformed-s3)
       deliveryLBDomainName: serverless-test-lb-1780491458.us-east-1.elb.amazonaws.com
Copy-icon

Шаг 4: Создание сайта в authoring-окружении

  1. Перейдите в CMS Studio в authoring-окружении через ваш веб-браузер.
  2. Нажмите на кнопку Создать сайт.
  3. Выберите шаблон Web Blog.
  4. Введите идентификатор и название сайта (например, blog), затем нажмите на Обзор > Создать.
  5. Перейдите в консоль AWS с использованием вашего веб-браузера. В выпадающем списке сервисов найдите CloudFormation. Найдите экземпляр CloudFormation, связанный с сайтом, который вы недавно создали; его статус должен изначально отображаться как CREATE_IN_PROGRESS. Через несколько минут статус должен перейти в CREATE_COMPLETE, что указывает на то, что CMS Deployer теперь может начать загрузку файлов в S3.
    Подождите минимум 2 минуты для завершения загрузки файлов CMS Deployer.
  • deployer.log

2019-12-20 20:48:58.780  INFO 18846 --- [deployment-3] llCloudFormationStackUsableLifecycleHook : CloudFormation stack 'serverless-test-site-editorial' is usable (status 'CREATE_COMPLETE')
2019-12-20 20:48:58.781  INFO 18846 --- [deployment-3] ru.dc.cms.deployer.impl.TargetImpl  : Creating deployment pipeline for target 'editorial-serverless-delivery'
2019-12-20 20:48:58.854  INFO 18846 --- [deployment-3] ru.dc.cms.deployer.impl.TargetImpl  : Checking if deployments need to be scheduled for target 'editorial-serverless-delivery'
2019-12-20 20:48:58.855  INFO 18846 --- [deployment-3] ru.dc.cms.deployer.impl.TargetImpl  : Deployments for target 'editorial-serverless-delivery' scheduled with cron 0 * * * * *
2019-12-20 20:49:00.001  INFO 18846 --- [deployment-8] ru.dc.cms.deployer.impl.TargetImpl  : ============================================================
2019-12-20 20:49:00.001  INFO 18846 --- [deployment-8] ru.dc.cms.deployer.impl.TargetImpl  : Deployment for editorial-serverless-delivery started
2019-12-20 20:49:00.001  INFO 18846 --- [deployment-8] ru.dc.cms.deployer.impl.TargetImpl  : ============================================================
...
...
...
2019-12-20 20:49:15.882  INFO 18846 --- [deployment-8] org.cmscms.deployer.impl.TargetImpl  : ============================================================
2019-12-20 20:49:15.882  INFO 18846 --- [deployment-8] org.cmscms.deployer.impl.TargetImpl  : Deployment for editorial-serverless-delivery finished in 15.878 secs
2019-12-20 20:49:15.882  INFO 18846 --- [deployment-8] org.cmscms.deployer.impl.TargetImpl  : ============================================================
Copy-icon
  • engine.log

[INFO] 2019-12-20T20:50:00,061 [pool-3-thread-10] [] [context.SiteContextManager] | ==================================================
[INFO] 2019-12-20T20:50:00,061 [pool-3-thread-10] [] [context.SiteContextManager] | <Creating site context: editorial>
[INFO] 2019-12-20T20:50:00,061 [pool-3-thread-10] [] [context.SiteContextManager] | ==================================================
...
...
...
[INFO] 2019-12-20T20:50:04,393 [pool-3-thread-10] [] [context.SiteContextManager] | ==================================================
[INFO] 2019-12-20T20:50:04,393 [pool-3-thread-10] [] [context.SiteContextManager] | </Creating site context: editorial>
[INFO] 2019-12-20T20:50:04,393 [pool-3-thread-10] [] [context.SiteContextManager] | ==================================================
Copy-icon

Шаг 5: Тестирование Delivery-сайта
Откройте браузер и перейдите на страницу https://DOMAIN_OF_YOUR_CLOUDFRONT. После этого вам должен отобразиться ваш сайт.

Следующая ошибка появляется в логах Deployer-а (CMS_HOME/logs/deployer/cms-deployer.out), когда сайт не был опубликован:

2020-07-07 15:33:00.004 ERROR 22576 --- [deployment-9] l.processors.AbstractDeploymentProcessor : Processor 'gitDiffProcessor' for target 'ed-serverless-delivery' failed
ru.dc.cms..deployer.api.exceptions.DeployerException: Failed to open Git repository at /home/ubuntu/dccms/authoring/data/repos/sites/ed/published;

Как только сайт опубликуется, ошибка исчезнет.

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

CMS Engine может быть настроен на уровне проекта/сайта или на уровне экземпляра.

Уровень проекта/сайта

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

Основные конфигурационные файлы могут быть изменены через пользовательский интерфейс по пути Инструменты сайта> Конфигурация либо через Git. К этим файлам относятся:

Файл конфигурации Описание
config/engine/site-config.xml Содержит проектные свойства, используемые CMS Engine
config/engine/application-context.xml Содержит определения bean-ов для контекста сайта, связанного с веб-приложением
config/engine/urlrewrite.xml Содержит правила перезаписи URL-адресов
config/engine/proxy-config.xml Настраивает прокси-серверы для сервера предварительного просмотра (CMS Engine в режиме предварительного просмотра)

Все файлы конфигурации могут быть переопределены окружением. Узнайте больше о поддержке нескольких окружений в статье “Поддержка нескольких окружений CMS Engine”.

Конфигурационный файл site-config.xml может быть определен в:

  1. /config/engine/env/{envName}/site-config.xml: этот файл служит переопределением окружения и загружается первым, если он существует.

  2. /config/engine/site-config.xml: это основной конфигурационный файл для проекта или сайта, который загружается, когда переопределение окружения отсутствует.

Все свойства будут доступны разработчикам в шаблонах Freemarker и скриптах Groovy с использованием переменной siteConfig. Переменная siteConfig является экземпляром класса XMLConfiguration.

Уровень экземпляра

К основным файлам конфигурации на уровне экземпляра относятся:

Файл конфигурации Описание
server-config.properties Содержит настраиваемые параметры сервера, такие как URL-адреса, пути и т.д.
services-context.xml Содержит bean-определение для уровня сервисов
rendering-context.xml Содержит bean-определение для рендеринга
logging.xml Содержит логгеры, аппендеры и т.д.

Конфигурационные файлы для CMS Engine можно найти в папке CMS_HOME/bin/apache-tomcat/shared/classes/cms/engine/extension, где CMS_HOME представляет собой директорию установки вашего delivery- или authoring-окружения.

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

Свойства конфигурации CMS Engine

В этом разделе мы рассмотрим некоторые из наиболее часто используемых свойств в конфигурации CMS Engine. Большинство свойств вы можете найти в файле server-config.properties, а дополнительные файлы конфигурации и свойства - в разделе “Файлы конфигурации”.

Корневая папка CMS Engine

Для CMS Engine требуется настроить путь к корневой папке, если значения по умолчанию не используются.

Стандартный корневой путь папки имеет следующий формат: cms.engine.site.default.rootFolder.path=file:${CMS_DATA_DIR}/repos/sites/{siteName}/. Этот шаблон предполагает, что переменная окружения CMS_DATA_DIR настроена. Затем CMS Engine будет заменять переменную {siteName} на имя указанного сайта.

Чтобы изменить корневой путь пупки нужно либо установить переменную окружения CMS_DATA_DIR, либо изменить стандартный корневой путь папки в файле server-config.properties. Переменная для изменения:

cms.engine.site.default.rootFolder.path=file:${CMS_DATA_DIR}/repos/sites/{siteName}/
Copy-icon

Отключение отображения ошибок

На этапе разработки шаблонов в DС CMS сообщения об ошибках внутри шаблонов визуально отображаются рядом с контентом для помощи разработчикам в выявлении проблем при кодировании. Однако рекомендуется отключить эту функцию в production-окружении, чтобы избежать раскрытия потенциальных проблем на сайте и конфиденциальной информации. Чтобы отключить отображение ошибок вместе с контентом, выполните следующие шаги:

1. Добавьте в файл server-config.properties следующее свойство и значение:

display.errors.inline=false
Copy-icon

2. Сохраните изменения в файле.

3. Перезапустите приложение CMS Engine или сервис Tomcat, чтобы применить изменения конфигурации.

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

Заголовки HTTP-ответов

DC CMS позволяет добавлять заголовки к ответам при наличии соответствующих шаблонов конфигурации в файле конфигурации проекта CMS Engine. Чтобы установить заголовки HTTP-ответов, выполните следующие шаги:

1. Настройте шаблон пути Ant для добавления заголовков в ответ в headerMappings.mapping.urlPattern.

2. Настройте элементы <header> и <value>  желаемыми значениями в разделе headerMappings.mapping.headers.

<headerMappings>
  <mapping>
    <urlPattern>/**/*.pdf</urlPattern>
    <headers>
      <header>
        <name>X-Cms-Document</name>
        <value>true</value>
      </header>
    </headers>
  </mapping>
</headerMappings>
Copy-icon

Настройка заголовков кэша

Заголовки кэша позволяют определить политику кэширования, например, устанавливают как элемент кэшируется, задают максимальное время до истечения срока действия и др. Эти заголовки играют ключевую роль в передаче информации о времени жизни кэша (Time-To-Live, TTL) в сети доставки контента (Content Delivery Networks, CDN) и браузерам для конкретных запросов.

Для настройки заголовков кэша выполните следующие шаги:

  1. Настройте шаблон пути Ant для сопоставления при добавлении заголовков к ответу в headerMappings.mapping.urlPattern.

  2. Настройте элемент <header> со значением Cache-Control и элемент <value> с выбранной вами директивой Cache-Control в пределах headerMappings.mapping.headers.

Список доступных директив для использования с Cache-Control.

Ваша настройка должна быть похожа на это:

<headerMappings>
  <mapping>
    <urlPattern>/articles/**</urlPattern>
    <headers>
      <header>
        <name>Cache-Control</name>
        <value>max-age=60, s-maxage=300</value>
      </header>
    </headers>
  </mapping>
</headerMappings>
Copy-icon

Важно отметить, что заголовок Cache-Control по умолчанию изначально настроен на No-Cache. Скорректируйте конфигурацию в соответствии с вашими конкретными требованиями кэширования.

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

Когда выполняется скрипт Groovy, каждая часть кода проходит проверку на соответствие списку небезопасных выражений, чтобы защитить от потенциально вредоносного кода, который может поставить под угрозу систему. Когда вы попытаетесь выполнить скрипт, содержащий небезопасные выражения, вы увидите ошибку, подобную этой:

UnsupportedOperationException: Insecure call staticMethod java.lang.Runtime getRuntime ...
Copy-icon

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

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

Свойства Groovy Sandbox

Следующее позволяет настроить Groovy Sandbox:

# Indicates if the sandbox should be enabled for all sites
cms.engine.groovy.sandbox.enable=true
# Indicates if the blacklist should be enabled for all sites (this will have no effect if the sandbox is disabled)
cms.engine.groovy.sandbox.blacklist.enable=true
# The location of the default blacklist to use for all sites (this will have no effect if the sandbox is disabled)
cms.engine.groovy.sandbox.blacklist.path=classpath:cms/engine/groovy/blacklist
Copy-icon

Groovy Sandbox включено по умолчанию и может быть отключено путем изменения свойства cms.engine.groovy.sandbox.enable на значение false.

Использование черного списка

CMS Engine поставляется с черным списком по умолчанию. Важно тщательно изучить конкретную ветку или тег, которые вы используете.

Чтобы использовать черный список, выполните следующее:

1. Скопируйте файл черного списка по умолчанию в ваш classpath. Например, CMS_HOME/bin/apache-tomcat/shared/classes/cms/engine/extension/groovy/blacklist.

2. Удалите или закомментируйте (добавив # в начало строки) выражения, необходимые для ваших скриптов.

3. Обновите файл конфигурации server-config.properties, чтобы включить пользовательский черный список:

# The location of the blacklist to use for all sites (this will have no effect if the sandbox is disabled)
cms.engine.groovy.sandbox.blacklist.path=classpath:cms/engine/extension/groovy/blacklist
Copy-icon

4. Перезапустите DC CMS.

Теперь вы можете выполнить этот скрипт без каких-либо проблем.

Отключение черного списка Groovy Sandbox

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

# Indicates if the blacklist should be enabled for all sites (this will have no effect if the sandbox is disabled)
cms.engine.groovy.sandbox.blacklist.enable=false
Copy-icon

Конфигурация перезаписи URL-адреса CMS Engine

Подробную информацию можно найти здесь.

Single Page Application (SPA)

Этот раздел позволяет вам настроить режим SPA:

(Single Page Application Properties (React JS, Angular, Vue.js, etc.))
<spa>
    <enabled /> (Enable/disable SPA mode, default is false)
    <viewName /> (The view name for the SPA (Single Page Application). Current view names can be a page URL (like /) or a template name (like /template/web/app.ftl). Default is /)
</spa>
Copy-icon

CORS

Этот раздел позволяет настроить заголовки CORS в ответах REST API, когда режим предварительного просмотра отключен.

(CORS Properties)
<cors>
    <enable>true</enable> (Enable/disable CORS headers, default is false)
    (Values for each of the headers that will be added to responses)
    <accessControlMaxAge>3600</accessControlMaxAge>
    <accessControlAllowOrigin>*</accessControlAllowOrigin>
    <accessControlAllowMethods>GET\, OPTIONS</accessControlAllowMethods>
    <accessControlAllowHeaders>Content-Type</accessControlAllowHeaders>
    <accessControlAllowCredentials>true</accessControlAllowCredentials>
</cors>
Copy-icon

где:

  • значения <accessControlAllowOrigin> разделяются с помощью “,”. Запятые внутри шаблонов должны экранироваться символом “\”, вот так: <accessControlAllowOrigin>http://localhost:[8000\,3000],http://*.other.domain</accessControlAllowOrigin>
  • значения <accessControlAllowMethods> и <accessControlAllowHeaders> разделяются с помощью “,”. Не забудьте экранировать запятые, разделяя значения следующим образом: <accessControlAllowHeaders>X-Custom-Header\, Content-Type</accessControlAllowHeaders> или <accessControlAllowMethods>GET\, OPTIONS</accessControlAllowMethods>

Когда CMS Engine находится в режиме предварительного просмотра, он действует как прокси, поэтому не будет добавлять заголовки CORS в ответы REST API, даже если CORS включен.

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

Подробнее можно узнать здесь.

Кэш

CMS Engine включает в себя встроенный cach engine с использованием политики вытеснения LRU (least recently used). Этот кэш служит хранилищем активного набора данных, обеспечивая эффективное извлечение контента из памяти во время процесса рендеринга.

В режиме предварительного просмотра (в CMS Studio) кэш Engine отключен, чтобы авторы контента сразу могли увидеть свои изменения.

Лимит на количество

Следующее позволяет вам настроить максимальное количество объектов в кэше CMS Engine:

# The max number of items that each site cache can have
cms.engine.site.default.cache.maxAllowedItems=250000
Copy-icon

Cache warming

Следующее позволяет вам настроить элементы для warming (предварительной загрузки) в кэш:

#################
# Cache Warm Up #
#################
# Indicates if cache warming should be enabled. This means the site cache will be warmed up (according to a list of
# cache warmers) on context init and instead of cache clear, a new cache will be warmed up and switched with the
# current one
cms.engine.site.cache.warmUp.enabled=false
# The descriptor folders that need to be preloaded in cache, separated by comma. Specify the preload depth with
# :{depth} after the path. If no depth is specified, the folders will be fully preloaded.
cms.engine.site.cache.warmUp.descriptor.folders=/site:3
# The content folders that need to be preloaded in cache, separated by comma. Specify the preload depth with
# :{depth} after the path. If no depth is specified, the folders will be fully preloaded.
cms.engine.site.cache.warmUp.content.folders=/scripts,/templates
Copy-icon

где:

  • папки-дескрипторы - это пути, содержащие XML, которое нужно парсить, загружать и объединять, например, для наследования. В большинстве случаев это будут папки внутри /site.
  • папки контента в основном представляют собой статический, необработанный контент, например, скрипты, шаблоны, статические активы

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

Кэш преобразований URL

Следующее позволяет вам настроить, будет ли кэшироваться преобразование URL, выполняемое view resolver-ом:

# Flag that indicates if the URL transformations performed by the view resolver should be cached
cms.engine.page.view.resolver.url.transformation.cache=false
Copy-icon

Объект S3

Следующее позволяет вам настроить белый список путей для кэширования памяти при использовании хранилища S3. Кроме того, оно позволяет определить максимальную допустимую длину содержимого для объектов S3, которые могут быть кэшированы в памяти.

# Maximum content length (in bytes) for S3 objects to be cached in memory. Larger files will be retrieved
# directly from S3 every time they are requested.
# Default set to 10M = 10 * 1024 * 1024
cms.engine.store.s3.cache.contentMaxLength=10485760
# White list of paths to be cached in memory when using S3 store.
cms.engine.store.s3.cache.allowedPaths=\
  /config/.*,\
  /site/.*,\
  /scripts/.*,\
  /templates/.*,\
  /static-assets/css/.*,\
  /static-assets/js/.*,\
  /static-assets/fonts/.*
Copy-icon

Конфигурация фильтрации запросов

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

cms.security.forbidden.urls=/templates/**
Copy-icon

Forwarded-заголовки

Forwarded-заголовки настраиваются для определения фактического имени хоста и протокола, когда CMS Engine находится за load balancer (ом) или reverse proxy. По умолчанию forwarded-заголовки отключены.

# Indicates if Forwarded or X-Forwarded headers should be used when resolving the client-originated protocol and
# address. Enable when Engine is behind a reverse proxy or load balancer that sends these
cms.engine.forwarded.headers.enabled=false
Copy-icon

Policy Headers

Referer Policy

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

# The value of the Referer-Policy header that should be set in all requests. Supported
# values are: no-referrer, no-referrer-when-downgrade, same-origin, origin, strict-origin,
# origin-when-cross-origin, strict-origin-when-cross-origin, unsafe-url
cms.security.headers.referrerPolicy.value=no-referrer
Copy-icon

Политика безопасности контента

Вы можете настроить, какие ресурсы могут быть загружены (например, JavaScript, CSS, изображения и т. д.) и с каких URL-адресов они могут быть загружены.

# Value for the Content-Security-Policy header
cms.security.headers.contentSecurityPolicy.value: default-src 'unsafe-inline'
# Set to true to enable the Content-Security-Policy-Report-Only header (this will report in the user agent console instead of actually blocking the requests)
cms.security.headers.contentSecurityPolicy.reportOnly: true
Copy-icon

Чтобы блокировать нежелательные запросы, установите для cms.security.headers.contentSecurityPolicy.reportOnly значение false. По умолчанию для этого свойства установлено значение true.

X-Permitted-Cross-Domain-Policies

Вы можете настраивать, какие дополнительные домены могут получать доступ к вашему домену. По умолчанию заголовок X-PERMITTED-CROSS-DOMAIN-POLICIES установлен в none, что означает, что внедрение не разрешено.

# Value for the X-PERMITTED-CROSS-DOMAIN-POLICIES header
cms.security.headers.permittedCrossDomainPolicies.value: none
Copy-icon

Проверка работоспособности

На каждом проекте есть возможность настроить индивидуальный скрипт проверки состояния работоспособности. По умолчанию CMS Engine ищет файл с именем health-check.groovy. Этот файл содержит пользовательский скрипт для проведения проверки состояния всякий раз, когда анализируется статус проекта. Конкретное расположение этого скрипта определяется конфигурацией в файле site-config.xml проекта, как показано ниже:

# The path of the Groovy script for site health check
cms.engine.site.default.health-check.script.path=/scripts/health-check.groovy
Copy-icon

Навигация

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

(Navigation Properties)
<navigation>
    <additionalFields /> (List of additional fields to include for dynamic navigation items)
</navigation>
Copy-icon

Тайм-ауты поиска

Следующее позволяет настроить тайм-аут подключения клиента поиска, тайм-аут сокета и количество потоков.

# The connection timeout in milliseconds, if set to -1 the default will be used
cms.engine.search.timeout.connect=-1
# The socket timeout in milliseconds, if set to -1 the default will be used
cms.engine.search.timeout.socket=-1
# The number of threads to use, if set to -1 the default will be used
cms.engine.search.threads=-1
Copy-icon

Content-Length заголовки

Эта опция позволяет настраивать заголовки content-length, отправляемые в ответах. По умолчанию заголовок content-length отправляется для всех ответов.

# Indicates if the 'etag' header should be added
cms.engine.header.etag.enable=false
# Indicates the urls that will have the 'etag' header (comma separated ant matchers)
cms.engine.header.etag.include.urls=/**
Copy-icon

Статические методы в шаблонах Freemarker

Эта опция позволяет настраивать доступ к статическим методам в шаблонах Freemarker. По умолчанию доступ к статическим методам в шаблонах Freemarker отключен.

# Indicates if access for static methods should be allowed in Freemarker templates
cms.engine.freemarker.statics.enable=false
Copy-icon

Язык выражений Spring (SpEL)

Следующее позволяет вам настроить выражения SpEL для пользовательских контекстов приложения. Поддержка выражений SpEL по умолчанию отключена.

# Indicates if the custom site application contexts should support SpEL expressions
cms.engine.context.expressions.enable=false
# Indicates if the whole servlet & spring context should be available for templates & scripts
cms.engine.disableVariableRestrictions=false
# Patterns for beans that should always be accessible from the site application context
cms.engine.defaultPublicBeans=cms\\.(targetIdManager|targetedUrlStrategy)
Copy-icon

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

Каждый проект может иметь свой собственный контекст приложения Spring. Как и в случае с site-config.xml, bean-ы могут быть перезаписаны в следующих местах:

  • /config/engine/application-context.xml. Вы можете получить доступ к этому файлу из любого проекта, созданного с использованием стандартных шаблонов. Перейдите в боковую панель CMS Studio, нажмите на “Инструменты сайта” > “Конфигурация” и выберите “Контекст приложения Engine Project”.
  • /config/engine/env/{envName}/application-context.xml.

Контекст приложения наследуется от service-context.xml CMS Engine, и может использоваться любой класс из classpath данного Engine, включая классы Groovy, объявленные в /scripts/classes/*.

В качестве примера, предположим, что вы определили класс Groovy в /scripts/classes/mypackage/MyClass.groovy, тогда вы можете определить bean следующим образом:

<?xml version="1.0" encoding="UTF-8"?>
      <beans xmlns="http://www.springframework.org/schema/beans"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">

  <bean class="org.springframework.context.support.PropertySourcesPlaceholderConfigurer" parent="cms.properties"/>

  <bean id="greeting" class="mypackage.MyClass">
    <property name="myproperty" value="${myvalue}"/>
  </bean>

</beans>
Copy-icon

Вы можете включить экземпляр org.springframework.context.support.PropertySourcesPlaceholderConfigurer в контекст, что позволит использовать свойства из site-config.xml в качестве плейсхолдеров, таких как ${myvalue}. Сделав конфигуратор плейсхолдера наследуемым от cms.properties, вы также получите доступ к глобальным свойствам CMS Engine (например, cms.engine.preview).

CMS Engine не сможет загрузить контекст вашего проекта, если ваш файл контекста содержит недопустимый XML, неверную конфигурацию или если ваши bean-ы неправильно обрабатывают свои собственные ошибки при инициализации.

Поддержка нескольких окружений CMS Engine Copy-icon

Подробную информацию можно найти здесь.

Поддержка нескольких целей публикации CMS Engine Copy-icon

В некоторых случаях становится необходимым настраивать значения в конфигурационных файлах CMS Engine в соответствии с конкретными целями публикации. Например, в production-окружении, включающем staging для тестирования проекта и live для взаимодействия с конечными пользователями, может потребоваться использование различных механизмов аутентификации SAML или перенаправлений URL.

В статье “Поддержка нескольких окружений CMS Engine” можно найти информацию о настройке файлов CMS Engine для каждого окружения. DC CMS не только облегчает переопределение конфигурационных файлов CMS Engine на основе окружений, но также позволяет настраивать их на основе конкретной цели публикации. Это позволяет создавать основную конфигурацию для каждого окружения, предоставляя при этом гибкость переопределения конфигураций для каждой цели публикации.

Следующие файлы конфигурации CMS Engine могут быть настроены для различных целей публикации:

  1. site-config.xml
  2. application-context.xml
  3. urlrewrite.xml

Поддерживаемые цели публикации для вышеперечисленных файлов конфигурации включают:

  • preview
  • staging
  • live

Переопределение файлов конфигурации CMS Engine для каждой цели публикации Copy-icon

1. Добавьте новые конфигурационные файлы для переопределения в Инструменты сайта > Конфигурация > Конфигурации. Предопределяющий файл конфигурации должен иметь имя configuration-to-be-overridden.publishing-target.xml. Точное имя будет зависеть от конкретной цели публикации, которую вы намерены использовать для замены файла конфигурации, и может быть одним из следующих:

  • configuration-to-be-overridden.preview.xml
  • configuration-to-be-overridden.staging.xml
  • configuration-to-be-overridden.live.xml

Например, чтобы добавить переопределение файла urlrewrite.xml для staging-окружения, добавьте следующее в Конфигурации:

<file>
  <module>engine</module>
  <path>urlrewrite.staging.xml</path>
  <title>Engine URL Rewrite (XML Style) Staging</title>
  <description>Engine URL Rewrite (XML Style) Staging</description>
  <samplePath>sample-urlrewrite.xml</samplePath>
</file>
Copy-icon

Подробнее о конфигурационном файле в разделе “Конфигурации” можно узнать здесь.

2. Введите необходимые добавления/изменения в файл конфигурации переопределения. Обновите свой браузер, чтобы убедиться, что изменения вступили в силу. Теперь добавленный файл должен отображаться в Инструменты сайта > Конфигурация. Откройте данный файл конфигурации и внесите необходимые добавления/изменения, а затем сохраните внесенные изменения.

3. Если файл конфигурации, предназначенный для переопределения, не предназначен для preview, опубликуйте файл конфигурации в предполагаемом месте публикации (staging или live).

Настройка пользовательских сервисов

При создании шаблонов или скриптов можно воспользоваться лишь ограниченным перечнем сервисов. Расширить список доступных сервисов можно способами, описанными ниже.

Сервисы DC CMS

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

# Patterns for beans that should be accessible from the site application context
cms.engine.defaultPublicBeans=cms\\.(targetIdManager|targetedUrlStrategy),someOtherBean
Copy-icon

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

Системные сервисы

Эта настройка отключает ограничения для всех проектов/сайтов.

Нельзя открыть системные объекты, такие как ServletContext, просто добавив их в список. Вместо этого необходимо внести изменения в следующую конфигурацию в файле server-config.properties.

# Expose all services
cms.engine.disableVariableRestrictions=true
Copy-icon

Добавление зависимостей с помощью Grape

Если вашему коду на Groovy требуются внешние зависимости, вы можете использовать Grapes. Однако, когда активирована Groovy Sandbox, зависимости могут быть получены только во время первичной компиляции, а не во время выполнения. Поэтому необходимо добавить дополнительный параметр, initClass=false, в аннотации, чтобы предотвратить их копирование в классы.

@Grab(group='org.apache.commons', module='commons-pool2', version='2.8.0', initClass=false)
@Grab(value='org.apache.commons:commons-pool2:2.8.0', initClass=false)
Copy-icon

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

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

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