Настроить TLS-сертификаты для ELMA Cortex

Перед установкой ELMA Cortex задайте настройки TLS‑сертификатов для защиты HTTPS-соединений. Поддерживаются три режима управления сертификатами:

Internal — самоподписанные сертификаты генерируются автоматически. Этот режим подходит для тестирования и используется по умолчанию;
Custom — используются сертификаты от публичного или частного удостоверяющего центра (УЦ), либо самоподписанные сертификаты;
ACME — используются сертификаты, автоматически выпущенные по протоколу ACME с помощью удостоверяющего центра Let’s Encrypt.

Для управления сертификатами используется сервер Caddy.

Режим Internal

Чтобы сервер Caddy автоматически создавал самоподписанные сертификаты и управлял ими:

В файле .env раскомментируйте строку с параметром TLS_MODE и убедитесь, что для него задано значение internal.
Параметры применятся автоматически при установке ELMA Cortex.

Если вы обновляете настройки после её завершения, для применения новых параметров используйте команду:

./install.sh

Экспортируйте корневой сертификат Caddy:

chmod +x manage-certs.sh
./manage-certs.sh export-caddy-ca

Установите экспортированный сертификат caddy_root.crt на клиентских машинах в качестве доверенного сертификата. Нужные для этого действия зависят от операционной системы.

Режим Custom

В этом режиме можно использовать собственный TLS-сертификат:

от публичного УЦ;
от частного корпоративного УЦ;
самоподписанный.

Требования к сертификатам для режима Custom

Рассмотрим, каким условиям должны соответствовать сертификаты в ELMA Cortex:

формат — PEM (base64 encoded);
ключ — RSA или ECDSA, незашифрованный;
цепочка — если вы используете промежуточные сертификаты, они указываются в файле сертификата сервера;
расширение SAN (Subject Alternative Names) — в поле для указания дополнительных доменов, для которых действителен сертификат, нужно ввести имя хоста, заданное в файле .env в переменной ELMA_CORTEX_HOSTNAME.

Включение режима Custom

Подготовьте файлы сертификата:

server.crt — сертификат сервера. Если используется цепочка промежуточных сертификатов, их нужно объединить с основным сертификатом в этом файле;
server.key — приватный ключ в незашифрованном виде;
ca.crt — сертификат удостоверяющего центра. Этот файл требуется, только если вы используете частный корпоративный УЦ.

Создание самоподписанного сертификата

Создайте папку для файлов сертификата:

./manage-certs.sh init

Скопируйте файлы в папку:

cp /path/to/your/certificate.crt certs/server.crt
cp /path/to/your/private.key certs/server.key

Если вы используете частный УЦ, также скопируйте его сертификат:

cp /path/to/your/ca.crt certs/ca.crt

В файле переменных окружения .env раскомментируйте и заполните параметры:

TLS_MODE=custom
TLS_CERT_PATH=./certs/server.crt
TLS_KEY_PATH=./certs/server.key

Если вы используете сертификат УЦ, заполните путь к нему, чтобы сервисы ELMA Cortex могли взаимодействовать по HTTPS:

TLS_CA_PATH=./certs/ca.crt

Сертификат УЦ передаётся сервисам как Docker secret (caddy_root_ca), который добавляется в системное хранилище доверия.

Параметры применятся автоматически при установке ELMA Cortex. Если она завершена, для использования новых параметров выполните команду:

./install.sh

Обновление TLS-сертификатов

Если ваш сертификат истекает или требует замены, обновите его одним из способов:

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

./manage-certs.sh update /path/to/new/cert.crt /path/to/new/key.key

последовательно выполните команды, вставив путь к новому файлу:

cp /path/to/new/cert.crt certs/server.crt
cp /path/to/new/key.key certs/server.key
./install.sh

Режим ACME (Let’s Encrypt)

В этом режиме сервер Caddy автоматически получает сертификаты от Let’s Encrypt и обновляет их.

Требования для использования режима ACME

Проверьте, что соблюдаются условия:

для доменного имени, указанного в переменной ELMA_CORTEX_HOSTNAME, настроена DNS-запись, указывающая на IP-адрес сервера ELMA Cortex;
на сервере порты 80 и 443 доступны из интернета;
существует действующий адрес электронной почты для уведомлений Let’s Encrypt.

Включение режима ACME

В файле переменных окружения .env установите режим ACME и укажите адрес электронной почты для уведомлений:

TLS_MODE=acme
ACME_EMAIL=admin@your-domain.com

Параметры применятся автоматически при установке ELMA Cortex. Если она завершена, для использования новых параметров используйте команду:

./install.sh

После этого сервер Caddy будет:

получать сертификаты от Let’s Encrypt;
перенаправлять запросы с HTTP на защищённый протокол HTTPS;
автоматически обновлять сертификат перед истечением срока.

Устранение неполадок ACME

Если выпуск сертификата не удался, используйте команды для проверки, указывая в них адрес вашего сервера ELMA Cortex:

Проверьте разрешение DNS:

nslookup ${ELMA_CORTEX_HOSTNAME}

Проверьте доступность портов:

curl -v http://${ELMA_CORTEX_HOSTNAME}/.well-known/acme-challenge/test

Проверьте логи сервера Caddy:

docker service logs elma-cortex_caddy

Проверка корректности настроек TLS

Чтобы проверить настройки перед развёртыванием ELMA Cortex, используйте команду:

./manage-certs.sh check

Для просмотра текущей конфигурации:

./manage-certs.sh info

Устранение неполадок с сертификатами

Рассмотрим часто встречающиеся ошибки и способы их устранения.

Сертификат не работает после обновления

Перезапустите сервис Caddy для обновления сертификатов:

docker service update --force elma-cortex_caddy

Ошибка “Certificate file not found”

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

./manage-certs.sh check

Ошибка проверки SSL для внутренних сервисов

Проверьте настройки:

для режима Internal — убедитесь, что корневой сертификат Caddy установлен на машины, где используется ELMA Cortex;
для режима Custom с использованием частного УЦ — убедитесь, что в файле .env в переменной TLS_CA_PATH указан корректный путь к сертификату УЦ.

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

./install.sh

cortex-environment-variables.html cortex-auth-settings.html

Была ли статья полезной?