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

> [HTML Version](cortex-tls-settings.html)

Перед установкой задайте настройки TLS‑сертификатов. Они обеспечивают защищённый доступ к **ELMA Cortex** через браузер по протоколу HTTPS и позволяют компонентам продукта, таким как AI‑агенты, скачивать файлы.

Поддерживаются три режима управления сертификатами:

- [Internal](#internal) — самоподписанные сертификаты генерируются автоматически. Этот режим подходит для тестирования и используется по умолчанию;

- [Custom](#custom) — используются сертификаты от публичного или частного удостоверяющего центра (УЦ), либо самоподписанные сертификаты;

- [ACME](#acme) — используются сертификаты, автоматически выпущенные по протоколу ACME с помощью удостоверяющего центра Let’s Encrypt.

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

## Режим Internal

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

1. В файле `.env` раскомментируйте строку с параметром `TLS\_MODE` и убедитесь, что для него задано значение `internal`.

2. Параметры применятся автоматически при установке **ELMA Cortex**.

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

````
./install.sh

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

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

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

## Режим Custom

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

- от публичного УЦ;

- от частного корпоративного УЦ;

- самоподписанный.

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

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

- формат — PEM (base64 encoded);

- ключ — RSA или ECDSA, незашифрованный;

- цепочка — если вы используете промежуточные сертификаты, они добавляются в файл сертификата сервера;

- расширение SAN (Subject Alternative Names) — в поле для указания дополнительных доменов, на которые распространяется действие сертификата, нужно ввести имя хоста. Используйте значение, заданное в файле `.env` в переменной `ELMA\_CORTEX\_HOSTNAME`.

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

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

	- **server.crt** — сертификат сервера. Если используется цепочка промежуточных сертификатов, их нужно объединить с основным сертификатом в этом файле;

	- **server.key** — приватный ключ в незашифрованном виде;

	- **ca.crt** — сертификат удостоверяющего центра. Этот файл требуется, только если вы используете частный корпоративный УЦ. 

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

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

````
./manage-certs.sh generate-self-signed

````
  
Также можно сгенерировать сертификат вручную, используя следующие команды с указанием имени хоста **ELMA Cortex**:

````
source .env  
  
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \\  
  -keyout certs/server.key \\  
  -out certs/server.crt \\  
  -subj "/CN=\$\{ELMA\_CORTEX\_HOSTNAME\}" \\  
  -addext "subjectAltName=DNS:\$\{ELMA\_CORTEX\_HOSTNAME\}"
````

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

````
./manage-certs.sh init

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

````
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

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

````
TLS\_MODE=custom  
TLS\_CERT\_PATH=./certs/server.crt  
TLS\_KEY\_PATH=./certs/server.key

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

````
TLS\_CA\_PATH=./certs/ca.crt

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

6. Параметры применятся автоматически при установке **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

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

````
TLS\_MODE=acme  
ACME\_EMAIL=admin@your-domain.com

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

````
./install.sh

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

- получать сертификаты от Let’s Encrypt;

- перенаправлять запросы с HTTP на защищённый протокол HTTPS;

- автоматически обновлять сертификат перед истечением срока.

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

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

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

````
nslookup \$\{ELMA\_CORTEX\_HOSTNAME\}

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

````
curl -v http://\$\{ELMA\_CORTEX\_HOSTNAME\}/.well-known/acme-challenge/test

3. ````
Проверьте логи сервера 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

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

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

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

- для режима **Custom** с использованием частного УЦ — убедитесь, что в файле `.env` в переменной `TLS\_CA\_PATH` указан корректный путь к сертификату УЦ.

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

````
./install.sh
````