Процесс установки Sherpa Orchestrator#

Для новой установки с БД на отдельном сервере применяется инструкция по внешней PostgreSQL.

Распаковка клиентских файлов#

Для установки необходимо распаковать клиентские файлы Sherpa Orchestrator и подготовить скрипты к выполнению.

Распаковка архива с обновлением#

Архив распаковывается в каталог установки следующей командой.

# Найдите и распакуйте архив обновления (автоматически выбирается самая свежая версия)
tar -xvzf "$(ls docker_orchestrator_client_files_*.tgz | sort -V | tail -n 1)"

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

Копировать

sudo ./sh_scripts/install.sh

Скрипт проведет через все этапы установки: выбор БД, загрузку образов, настройку .env, генерацию SSL-сертификатов и запуск контейнеров.

Подготовка скриптов к выполнению#

Скриптам установки необходимо предоставить право исполнения.

# Перейдите в директорию sh_scripts
# Сделайте все скрипты исполняемыми
# Вернитесь в корневую директорию проекта
cd sh_scripts && chmod +x *.sh && cd ..

Загрузка Docker-образов#

Следующая команда загружает образы из скачанных архивов в локальное хранилище Docker.

# Запустите скрипт загрузки Docker-образов
sudo ./sh_scripts/load_all_docker_images.sh

Создание конфигурации системы#

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

# Запустите скрипт создания настроек
sudo ./sh_scripts/create_config.sh

Копирование SSL-сертификатов#

Для обеспечения безопасного HTTPS-соединения необходимо скопировать SSL-сертификаты:

# Создайте директорию для сертификатов (если не существует)
mkdir -p ./nginx/config/certs/

# Переименуйте и скопируйте сертификат и ключ для вашего домена
# Замените пути на реальные пути к вашим сертификатам
cp /path/to/your/certificate.crt ./nginx/config/certs/orchestrator.crt
cp /path/to/your/private.key ./nginx/config/certs/orchestrator.key

Важно: Сертификатам необходимо предоставить следующие права доступа:

# Установите правильные права на сертификаты(могут понадобиться sudo права)
chmod 644 ./nginx/config/certs/orchestrator.crt
chmod 600 ./nginx/config/certs/orchestrator.key
chown 101:101 ./nginx/config/certs/orchestrator.key ./nginx/config/certs/orchestrator.crt

ВНИМАНИЕ: Получить сертификаты необходимо у администратора сети либо в вашем корпоративном центре сертификации. В случае отсутствия данных сертификатов применяются инструкции по получению сертификатов Let's Encrypt или других центров сертификации.

Настройка TLS для протокола LDAPS (опциональный пункт)#

Этот пункт требуется только при использовании LDAPS. Файл /opt/SherpaOrchestrator/backend/config/certs/ca-certificates.crt должен содержать стандартные доверенные сертификаты образа и сертификат центра сертификации LDAPS-сервера. Порядок создания общего файла описан в подразделе "Создание файла доверенных сертификатов" раздела "Настройка сертификатов для IMAP-сервера (опциональный пункт)" этой статьи. При совместном использовании IMAP и LDAPS в файл добавляются сертификаты обоих серверов.

Для подключения общего файла в сервисе orchestrator файла docker-compose.yml необходимо раскомментировать строку:

- ./backend/config/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro

Настройка сертификатов для IMAP-сервера (опциональный пункт)#

Важно: Если использование Триггеров с запуском по электронной почте не планируется, данный пункт не требуется.

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

Если сертификат почтового сервера выдан корпоративным центром сертификации или является самоподписанным, необходимо добавить корневой сертификат в список доверенных сертификатов Оркестратора. Без этого Триггер не может проверить почту, а на экране "Аудит" появляется сообщение вида:

Schedule:Имя Триггера; Email:robot@company.ru; IMAP connection failed: Certificate failure for mail.company.ru: unable to get local issuer certificate

Важно: Сертификат проверяется, даже если в настройках Триггера не установлен чекбокс "Использовать SSL". Если почтовый сервер поддерживает STARTTLS, Оркестратор включает шифрование соединения автоматически.

Важно: Сертификаты, скопированные в каталог ./backend/config/certs/imap_certs, Оркестратор не использует. Необходимо выполнить действия, описанные ниже.

Все команды выполняются в каталоге /opt/SherpaOrchestrator.

Проверка сертификата почтового сервера#

Перед настройкой необходимо проверить сертификат почтового сервера по стандартному списку доверенных сертификатов образа. В командах необходимо заменить mail.company.ru на значение поля "Почтовый сервер" и указать порт из настроек Триггера. Для IMAP с установленным чекбоксом "Использовать SSL" обычно используется порт 993, для STARTTLS — порт 143:

# Выведите цепочку сертификатов почтового сервера
# Замените mail.company.ru на значение поля "Почтовый сервер" из настроек Триггера
docker run --rm --entrypoint openssl orchestrator s_client -connect mail.company.ru:993 -servername mail.company.ru -verify_hostname mail.company.ru -showcerts </dev/null

# Если в поле "Порт" указан порт 143, используйте команду
docker run --rm --entrypoint openssl orchestrator s_client -connect mail.company.ru:143 -servername mail.company.ru -verify_hostname mail.company.ru -starttls imap -showcerts </dev/null

Подготовка сертификата#

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

Сертификат должен быть в текстовом формате PEM: файл начинается со строки -----BEGIN CERTIFICATE-----. Сертификат в двоичном формате DER, например файл .cer, выгруженный из Windows, необходимо преобразовать:

# Преобразуйте сертификат из формата DER в формат PEM
# Замените пути на реальные пути к сертификату
docker run --rm -i --entrypoint openssl orchestrator x509 -inform der < /path/to/root-ca.cer > /path/to/root-ca.crt

Важно: Сертификат Оркестратора orchestrator.crt и закрытые ключи для этого пункта не подходят.

Создание файла доверенных сертификатов#

Файл доверенных сертификатов должен содержать стандартный список сертификатов из образа Оркестратора и корневой сертификат центра сертификации:

Перед созданием файла требуется сохранить существующий ca-certificates.crt под свободным резервным именем. Новый файл должен содержать стандартные сертификаты образа и все собственные доверенные сертификаты, включая используемые для LDAPS. Приведенная команда перезаписывает файл, поэтому этот состав необходимо подготовить заранее.

# Выгрузите стандартный список доверенных сертификатов из образа Оркестратора
docker run --rm --entrypoint cat orchestrator /etc/ssl/certs/ca-certificates.crt > ./backend/config/certs/ca-certificates.crt

# Добавьте в конец файла корневой сертификат центра сертификации
# Замените путь на реальный путь к сертификату
echo >> ./backend/config/certs/ca-certificates.crt
cat /path/to/root-ca.crt >> ./backend/config/certs/ca-certificates.crt

# Установите права на чтение файла (могут понадобиться sudo права)
chmod 644 ./backend/config/certs/ca-certificates.crt

Важно: Если выполнен пункт «Настройка TLS для протокола LDAPS», команда выгрузки перезапишет файл ca-certificates.crt. В этом случае в файл необходимо добавить также корневой сертификат LDAPS-сервера.

Подключение файла к Оркестратору#

В файле docker-compose.yml в сервисе orchestrator необходимо раскомментировать строку:

- ./backend/config/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro

Если строка уже раскомментирована при настройке LDAPS, этот шаг не требуется. Строки с imap_certs изменять не нужно.

Если Оркестратор еще не запущен, необходимо перейти к следующему пункту установки. Если Оркестратор уже работает, необходимо пересоздать контейнер:

# Пересоздайте контейнер orchestrator, чтобы подключить файл доверенных сертификатов
docker compose up -d --no-deps --force-recreate orchestrator

Важно: Команда docker compose restart и перезагрузка сервера не применяют изменения файла docker-compose.yml.

Проверка подключения#

После запуска Sherpa Orchestrator проверяются сертификат и имя почтового сервера с учетом подключенного файла доверенных сертификатов. Для этого необходимо выбрать команду для режима подключения Триггера и заменить имя сервера и порт на значения из его настроек:

# IMAP с SSL, обычно порт 993
docker exec orchestrator openssl s_client -connect mail.company.ru:993 -servername mail.company.ru -verify_hostname mail.company.ru </dev/null

# IMAP с STARTTLS, обычно порт 143
docker exec orchestrator openssl s_client -connect mail.company.ru:143 -servername mail.company.ru -verify_hostname mail.company.ru -starttls imap </dev/null

В выводе ожидается строка Verify return code: 0 (ok). Она подтверждает проверку сертификата и имени сервера, но не проверку учетных данных почтового ящика. Если соединение не установлено, необходимо проверить сообщение об ошибке, адрес, порт и доступность сервера из контейнера. Утилита openssl s_client может завершиться с кодом 0 даже при ошибке сертификата, поэтому необходимо проверять именно строку Verify return code.

Затем в настройках Триггера на вкладке "Email" необходимо нажать на кнопку "Тест получения почты". При успешном подключении появится уведомление "Тест прошел успешно, получено N сообщений".

Важно: Значение поля "Почтовый сервер" должно соответствовать сертификату сервера, например mail.company.ru. Если сертификат выдан только для доменного имени, подключение по IP-адресу завершится ошибкой hostname mismatch.

Возможные ошибки#

Сообщения об ошибках подключения к почтовому серверу отображаются на экране "Аудит". Типовые ошибки сертификата:

• unable to get local issuer certificate, unable to verify the first certificate, self-signed certificate — в файле ca-certificates.crt нет нужного сертификата, или файл не подключен к контейнеру Оркестратора
• hostname mismatch — значение поля "Почтовый сервер" в настройках Триггера не совпадает с именем в сертификате

Выбор конфигурации базы данных#

Для встроенной БД необходимо выбрать MariaDB (DB_ENGINE=mysql, профиль mariadb) или PostgreSQL (DB_ENGINE=pgsql, профиль pg). Далее заполняются параметры только выбранной СУБД. Для внешней БД указывается адрес отдельного сервера, а локальные профили БД не включаются.

Настройка переменных окружения#

Необходимо заполнить адрес сервера, домен и параметры выбранной БД. Значения your_server_ip, your_domain_name и пароли ниже служат образцом: их требуется заменить данными установки. Настройки VNC нужны только при использовании соответствующего профиля.

# Откройте файл .env в текстовом редакторе
nano .env

Параметры сервера, выбранной БД и VNC:

# IP-адрес сервера (измените на ваш реальный IP-адрес или домен)
HOST_IP=your_server_ip

# Доменное имя, которое будет использовать NGINX
NGINX_DOMAIN_NAME=your_domain_name

# Настройки VNC
VNC_HOST=your_server_ip
VNC_PORT=5900
VNC_LOG_LEVEL=INFO
VNC_START_PORT=6080
VNC_MAX_PORTS=21
VNC_WEBSOCKIFY_WEB_ROOT=/opt/noVNC

# Тип базы данных: mysql или pgsql
DB_ENGINE=mysql

# Настройки MySQL (используется при DB_ENGINE=mysql)
MYSQL_HOST=orchestrator-db
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=mysql-password
MYSQL_DB=orchestrator

# Также задайте пароль для MariaDB-контейнера (должен совпадать с MYSQL_PASSWORD)
DB_PASSWORD=mysql-password

# Настройки PostgreSQL (используется при DB_ENGINE=pgsql)
POSTGRES_HOST=orchestrator-pg
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres-password
POSTGRES_DBNAME=postgres
POSTGRES_SCHEMA_NAME=orchestrator

Дополнительные параметры .env для SMTP, LDAP и хранения записей:

# Настройки почтового сервера (SMTP)
SMTP_SERVER=smtp.example.com
SMTP_PORT=25
SMTP_SECURE=tls
SMTP_LOGIN=
SMTP_PASSWORD=
SMTP_FROM=Orchestrator
SMTP_FROM_EMAIL=

# Настройки LDAP (опционально)
LDAP_SERVER=
LDAP_PORT=389
LDAP_ENCRYPTION=tls
LDAP_BASE_DN=dc=mydomain,dc=local
LDAP_GROUP=Group
LDAP_UID_KEY=uid
LDAP_USER=
LDAP_USERNAME=
LDAP_PASSWORD=
LDAP_FILTER=
LDAP_NETWORK_TIMEOUT=5
LDAP_OPERATION_TIMEOUT=10

# Прочие настройки
SESSION_LAST_ACTIVITY_TIMEOUT=30
STORE_LOGS_DAYS=180
STORE_AUDIT_DAYS=180

Параметры LDAP, режимы StartTLS и LDAPS, а также обязательный HTTPS callback OpenID описаны в инструкции по авторизации пользователей. Для OpenID применяется адрес /api/v1/system/oauth_hook; старый путь /api/gui/system/oAuthHook не подходит.

Запуск системы#

Необходимо выполнить одну команду для выбранной БД и нужных дополнительных сервисов. Для внешней БД используется docker compose up -d без профилей mariadb и pg.

# Запустите систему с нужным профилем БД
# Вариант 1: MariaDB
docker compose --profile mariadb up -d

# Вариант 2: PostgreSQL
docker compose --profile pg up -d

# Если нужен VNC (опционально), добавьте профиль vnc:
# Вариант 1: MariaDB + VNC
docker compose --profile mariadb --profile vnc up -d

# Вариант 2: PostgreSQL + VNC
docker compose --profile pg --profile vnc up -d

# Если нужен Vault (опционально), добавьте профиль vault:
# Вариант 1: MariaDB + Vault
docker compose --profile mariadb --profile vault up -d

# Вариант 2: PostgreSQL + Vault
docker compose --profile pg --profile vault up -d

# Комбинация профилей: MariaDB + VNC + Vault
docker compose --profile mariadb --profile vnc --profile vault up -d

Проверка статуса запуска#

Состояние сервисов и сообщения запуска проверяются следующими командами.

# Проверьте статус всех запущенных контейнеров
docker compose ps

# Посмотрите логи системы
docker compose logs orchestrator

# Мониторинг логов в реальном времени
docker compose logs -f orchestrator

При успешном запуске сервисы orchestrator, orchestrator-nginx и orchestrator-websocket находятся в состоянии Up. Для встроенной БД также запускается orchestrator-db или orchestrator-pg, для внешней — локальный контейнер БД не требуется. Дополнительные сервисы зависят от выбранных профилей. HTTPS-порт публикует orchestrator-nginx, а не backend-контейнер orchestrator.

Проверка доступности системы#

Проверка веб-интерфейса:

# Проверьте HTTPS доступность (замените на ваш домен/IP)
curl -I https://your-domain-or-ip

# Ожидаемый ответ: HTTP/2 200 или перенаправление

Управление системой#

Остановка системы:

# Остановите все сервисы
docker compose down

Команда docker compose down сохраняет именованные тома с данными. Параметр -v удаляет эти тома и их содержимое, поэтому для обычной остановки он не применяется.

Перезапуск сервисов:

# Перезапустите конкретный сервис
docker compose restart orchestrator

# Перезапустите все сервисы
docker compose restart

Просмотр ресурсов:

# Проверьте использование ресурсов контейнерами
docker stats

Возможные проблемы при запуске:#

Для поиска причины ошибки проверяются:

• Контейнеры не запускаются — сообщения команды docker compose logs.
• Проблемы с сетью — доступность портов 80 и 443, а при использовании VNC — 5000 и 6080–6100.
• Ошибки подключения к БД — параметры подключения в .env и доступность БД.
• Проблемы с доменом — значение HOST_IP и настройки DNS.

После успешного запуска и тестирования системы установка Sherpa Orchestrator завершена. Система будет доступна по HTTPS на настроенном домене или IP-адресе.