Руководство по установке Entaxy

Содержание

1. Цель руководства
2. Требования и замечания
3. Дистрибутивы программных продуктов
4. Установка PostgreSQL
5. Подготовка СУБД для работы с Entaxy
6. Установка OpenJDK 11
7. Установка и настройка nginx
- 7.1. Управление сервисом nginx
8. Установка Apache Artemis
- 8.1. Управление сервисом Apache Artemis
- 8.2. Установка кластера master-slave Artemis
9. Установка Apache Karaf
- 9.1. Управление сервисом Apache Karaf
10. Подготовка ОС для установки Entaxy
11. Установка Entaxy
12. Настройка обновления файла аутентификации htpasswd
13. Проверка работоспособности сервисов

1. Цель руководства

Данное руководство описывает процесс установки системы Entaxy (далее Система) на сервер или рабочую станцию в демонстрационных целях.

2. Требования и замечания

Для установки Системы требуется:

Установленная на сервер или рабочую станцию операционная система LTS: AstraLinux 2.12 (Orel), RHEL (CentOS), Ubuntu с настроенными репозиториями для установки программного обеспечения, входящего в состав поставки ОС
Созданный в системе пользователь с правами sudo. Под этим пользователем будет производиться установка Системы. Далее по инструкции имя пользователя обозначено как <username>. Вместо <username> нужно подставить имя пользователя, который будет производить установку.

Опыт работы с Debian/Ubuntu/AstraLinux системами

Table 1. Минимальные системные требования для Entaxy
Service	CPU (cores)	Disk (GB)	Memory (GB)
Karaf	4	40	16
ArtemisMQ	4	40	16
Nginx	2	40	4
DB	8	128	8

3. Дистрибутивы программных продуктов

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

Предполагается, что все дистрибутивы будут располагаться в домашнем каталоге по следующему пути: /home/<username>/distrib/. В дальнейшем тексте этот путь будет использоваться для описания установки и работы с дистрибутивами.

Сборка Apache Karaf, подготовленная для установки Entaxy. Вы можете скачать инсталлятор с официального сайта используя эту ссылку: https://entaxy.ru/download
PostgreSQL: Вы можете скачать инсталлятор PostgreSQL с официального сайта используя эту ссылку: https://www.enterprisedb.com/downloads/postgres-postgresql-downloads
Для работы Системы требуется Java 11. Работа Системы протестирована на OpenJDK и AxiomJDK. Вы можете скачать дистрибутивы Java 11 с официальных сайтов:
AxiomJDK: https://axiomjdk.ru/pages/downloads/
OpenJDK: https://learn.microsoft.com/ru-ru/java/openjdk/download#openjdk-11 и https://jdk.java.net/archive/
Active ArtemisMQ: Вы можете скачать инсталлятор ArtemisMQ с официального сайта используя эту ссылку: https://activemq.apache.org/components/artemis/download/

4. Установка PostgreSQL

Система использует СУБД PostgreSQL для хранения конфигураций, справочников и т.д. Указанная СУБД входит в Реестр программных продуктов.

Ниже указан пример установки PostgreSQL без привязки к конкретной версии устанавливаемого дистрибутива.

Для установки PostgreSQL необходимо перейти в каталог где вы сохранили дистрибутив PostgreSQL. Например, /home/<username>/distrib/postgresql.

cd /home/<username>/distrib/postgresql

И установить пакеты с базовыми компонентами PostgreSQL в следующей последовательности, используя команду : sudo apt install. Обратите внимание, что названия пакетов могут отличаться в зависимости от устанавливаемой версии PostgreSQL. Для каждой конкретной версии PostgreSQL используйте соответствующие названия пакетов.

sudo apt install ./postgresql-libs_<номер вашей версии>.orel_amd64.deb
sudo apt install ./postgresql-client_<номер вашей версии>.orel_amd64.deb
sudo apt install ./postgresql-server_<номер вашей версии>.orel_amd64.deb
sudo apt install ./postgresql-contrib_<номер вашей версии>.orel_amd64.deb
sudo apt install ./postgresql.orel_amd64.deb

При установке последнего пакета производится автоматическая инициализация кластера СУБД, поэтому никаких действий по начальной инициализации PostgreSQL производить не требуется.

5. Подготовка СУБД для работы с Entaxy

Перед установкой Системы нужно подготовить СУБД для работы с ней.

Подготовка заключается в создании пользователя СУБД и создании баз данных.

Для работы с СУБД используется инструмент psql с правами администратора. Для запуска инструмента выполнить следующие команды:

sudo su - postgres
psql

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

Создание пользователя:

CREATE USER entaxy WITH ENCRYPTED PASSWORD 'entaxy';

Создание баз данных

CREATE DATABASE cache;
CREATE DATABASE storage;

Назначение прав пользователю entaxy на только что созданные базы cache и storage:
```
GRANT ALL ON DATABASE cache TO entaxy;
GRANT ALL ON DATABASE storage TO entaxy;
```

После создания пользователя и БД выйти из инструмента psql с помощью ввода команды \q

После выхода из инструмента для работы с PostgresPro 11 Standard Edition psql требуется выйти из консоли пользователя postgres. Для этого выполнить команду:

exit

6. Установка OpenJDK 11

Установка OpenJDK 11 производится в каталог /opt/openjdk В дальнейшей инструкции этот путь будет использоваться как путь к установленной Java. Обратите внимание, что в вашем случае он может иметь другое название.

Для установки OpenJDK 11 перейдите в каталог, где вы сохранили дистрибутив Java. Например, /home/<username>/distrib/openjdk, создайте каталог /opt/openjdk и распакуйте в него дистрибутив OpenJDK 11.

cd /home/<username>/distrib/openjdk
sudo mkdir -p /opt/openjdk
sudo tar xvf <название установочного файла Java>.tar.gz -C /opt/openjdk

На распакованные файлы необходимо назначить права пользователя root:

sudo chown -R root:root /opt/openjdk
sudo chmod 755 /opt/openjdk/jdk-11.0.11

7. Установка и настройка nginx

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

sudo apt install nginx

После установки удалить конфигурацию nginx по умолчанию. Далее в домашней директории - например, /home/<username>/distrib/nginx/sites-available/ создать файл конфигурации nginx entaxy.conf подставив свои параметры:

Директива "listen": Замените <port> на прослушиваемый порт.

upstream esb {
   server ip_addres:8181;
}
server {
    listen <port>;
    server_name _;

    location / {
    auth_basic "Secured area";
    auth_basic_user_file /etc/nginx/htpasswd;

    proxy_pass http://esb;
    proxy_redirect off;
    proxy_ssl_verify off;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-ForwardedUser $remote_user;
    proxy_pass_header ENTAXY_TrueSet;
    proxy_pass_header ENTAXY_EndpointName;
    proxy_pass_header ENTAXY_ConnectorType;
    proxy_pass_header ENTAXY_ConnectorName;
    proxy_pass_header ENTAXY_Source;
    proxy_pass_header ENTAXY_SourceType;
    proxy_pass_header ENTAXY_Destination;
    proxy_pass_header ENTAXY_DestinationType;
    proxy_pass_header ENTAXY_Priority;
    proxy_pass_header ENTAXY_ContentType;
    proxy_pass_header ENTAXY_EmptyContent;

    client_max_body_size 1G;
    proxy_buffering    off;
    proxy_request_buffering off;
    keepalive_timeout  5 5;
}
}

Скопируйте созданный entaxy.conf в директорию /etc/nginx/sites-available, затем требуется создать символьную ссылку на конфигурацию в каталоге разрешённых конфигураций:

sudo rm -rf /etc/nginx/sites-enabled/default
sudo cp /home/<username>/distrib/nginx/sites-available/entaxy.conf /etc/nginx/sites-available
sudo ln -s /etc/nginx/sites-available/entaxy.conf /etc/nginx/sites-enabled/entaxy.conf

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

sudo nginx -t (1)
sudo systemctl reload nginx (2)

1	- валидация конфигурации nginx (если команда вернёт строку `syntax is ok`, то конфигурация валидна)
2	- перезагрузка конфигурации nginx

Затем необходимо создать файл паролей Basic аутентификации htpasswd в каталоге /opt/nginx

7.1. Управление сервисом nginx

Запуск nginx выполняется командой:

sudo systemctl start nginx

Остановка nginx выполняется командой:

sudo systemctl stop nginx

Перезапуск nginx выполняется командой:

sudo systemctl restart nginx

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

sudo systemctl reload nginx

8. Установка Apache Artemis

Установка Apache Artemis производится в каталог /opt/artemis

Для установки Apache Artemis необходимо выполнить следующие шаги:

Создать пользователя artemis, под которым будет работать Artemis. При создании пользователя создаётся домашний каталог пользователя /opt/artemis, в котором будет установлен сам Artemis:
```
sudo useradd -d /opt/artemis -m -r artemis -s /usr/sbin/nologin
```
Перейти в каталог где вы сохранили дистрибутив Artemis. Например, /home/<username>/distrib/artemis. Распаковать дистрибутив Artemis в домашний каталог Artemis и назначить распакованным файлам права пользователя artemis:
```
cd /home/<username>/distrib/artemis
sudo tar xvf <название установочного файла Artemis>.tar.gz -C /opt/artemis
sudo cp -a /opt/artemis/apache-artemis-<номер вашей версии>/. /opt/artemis/
sudo rm -rf /opt/artemis/apache-artemis-<номер вашей версии>
sudo chown -R artemis:artemis /opt/artemis
```

Создать каталог для брокера:

sudo mkdir -p /opt/artemis/brokers
sudo chown artemis:artemis /opt/artemis/brokers

Создать брокер:
```
sudo su -s /bin/sh -c \
    "export JAVACMD=/opt/openjdk/jdk-11.0.11/bin/java; \
    export ARTEMIS_HOME=/opt/artemis; \
    /opt/artemis/bin/artemis create \
    --name entaxy-broker \
    --user artemis \
    --password artemis \
    --require-login \
    /opt/artemis/brokers/entaxy-broker" \
    artemis
```
После выполнения команды создаётся новый брокер в каталоге /opt/artemis/brokers/entaxy-broker с именем entaxy-broker. Имя брокера задаётся в параметре --name. Имя пользователя и пароль для входа в Web консоль брокера задаётся в параметрах --user и --password соответственно.

Создать файл сервиса /etc/systemd/system/entaxy@artemis.service:

entaxy-broker@artemis.service

[Unit]
Description=Artemis Message Broker - entaxy
After=network.target

[Service]
Type=forking
ExecStart=/opt/artemis/brokers/entaxy-broker/bin/artemis-service start
ExecStop=/opt/artemis/brokers/entaxy-broker/bin/artemis-service stop

User=artemis
Group=artemis
UMask=0007
RestartSec=10
Restart=always

[Install]
WantedBy=multi-user.target

Отредактировать переменную окружения JAVA_HOME для сервиса брокера:
```
sudo systemctl edit entaxy@artemis.service
```
При выполнении предыдущей команды откроется текстовый редактор, в который надо добавить следующее содержимое, после чего сохранить файл:
```
[Service]
Environment="JAVA_HOME=/opt/openjdk/jdk-11.0.11"
```

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

sudo systemctl daemon-reload

Выполнение команды перезагрузит конфигурацию systemd, и сервис для запуска Artemis станет доступен

Включить автозапуск сервиса Artemis при старте системы:

sudo systemctl enable entaxy@artemis.service

Запустить брокер Entaxy

sudo systemctl start entaxy@artemis.service

8.1. Управление сервисом Apache Artemis

Запуск сервиса брокера entaxy выполняется командой:

sudo systemctl start entaxy@artemis.service

Остановка сервиса брокера entaxy выполняется командой:

sudo systemctl stop entaxy@artemis.service

8.2. Установка кластера master-slave Artemis

Для установки брокера Apache Artemis в варианте кластера master - slave необходимо сделать следующие шаги:

Установить и настроить Apache Artemis на отдельной ноде.

Отредактировать файл

$ARTEMIS_HOME/brokers/entaxy-broker/etc/broker.xml

на обоих узлах Артемис, добавив секции

<connectors>…</connectors>

<connectors>
    <connector name="connector1">tcp://ip_addres:61616</connector>
    <connector name="connector2">tcp://ip_addres:61616</connector>
</connectors>

и <cluster-connections>…</cluster-connections>

<cluster-connections>
    <cluster-connection name="artemis-cluster">
        <address>cluster</address>
        <connector-ref>connector2</connector-ref>
        <retry-interval>500</retry-interval>
        <use-duplicate-detection>true</use-duplicate-detection>
        <message-load-balancing>ON_DEMAND</message-load-balancing>
        <max-hops>1</max-hops>
            <static-connectors>
                <connector-ref>connector1</connector-ref>
                <connector-ref>connector2</connector-ref>
            </static-connectors>
    </cluster-connection>
</cluster-connections>

На первой ноде (master) добавить в файл

$ARTEMIS_HOME/brokers/entaxy-broker/etc/broker.xml

секцию <ha-policy>..</ha-policy>:

<ha-policy>
    <replication>
        <master>
        <check-for-live-server>true</check-for-live-server>
        </master>
    </replication>
</ha-policy>

На второй ноде (slave) добавить в файл

$ARTEMIS_HOME/brokers/entaxy-broker/etc/broker.xml

секцию <ha-policy>..</ha-policy>:

<ha-policy>
    <replication>
        <slave>
            <allow-failback>true</allow-failback>
        </slave>
    </replication>
</ha-policy>

Убедиться, что на узлах master и slave открыты tcp порты 61616 и 8161.

9. Установка Apache Karaf

Установка Apache Karaf производится в каталог /opt/karaf

Для установки Apache Karaf необходимо выполнить следующие шаги:

Создать пользователя karaf, под которым будет работать Karaf. При создании пользователя создаётся домашний каталог пользователя /opt/karaf, в котором будет установлен сам Karaf:
```
sudo useradd -d /opt/karaf -m -r karaf -s /usr/sbin/nologin
```
Перейти в каталог где вы сохранили дистрибутив entaxy-ion-karaf-1.8.3.zip
Например, /home/<username>/distrib/karaf. Распаковать дистрибутив в домашний каталог и назначить распакованным файлам права пользователя karaf:
```
cd /home/<username>/distrib/karaf
unzip entaxy-ion-karaf-1.8.3.zip -d /opt/karaf
sudo cp -a /opt/karaf/entaxy-ion-karaf-1.8.3/entaxy-ion-karaf/. /opt/karaf
sudo rm -rf /opt/karaf/entaxy-ion-karaf-1.8.3
sudo chown -R karaf:karaf /opt/karaf
```

Отредактировать переменную окружения JAVA_HOME для Karaf:

sudo sed -i 's/# export JAVA_HOME/export JAVA_HOME=\/opt\/openjdk\/jdk-11.0.11/g' /opt/karaf/bin/setenv

Отредактировать переменную окружения EXTRA_JAVA_OPTS для Karaf, чтобы устранить возможность эксплуатацию критической уязвимости Log4j CVE-2021-44228:
```
sudo sed -i 's/# export EXTRA_JAVA_OPTS/export EXTRA_JAVA_OPTS=-Dlog4j2.formatMsgNoLookups=true/g' /opt/karaf/bin/setenv
```

Создать файл сервиса /etc/systemd/system/karaf.service со следующим содержимым:

karaf.service

[Unit]
Description=Entaxy Karaf
After=syslog.target network.target

[Service]
ExecStart=/opt/karaf/bin/karaf start
ExecStop=/opt/karaf/bin/karaf stop

User=karaf
Group=karaf

SuccessExitStatus=0 143
RestartSec=15
Restart=on-failure

LimitNOFILE=102642

[Install]
WantedBy=multi-user.target

После создания файла сервиса и определения переменных окружения, выполнить команду:
```
sudo systemctl daemon-reload
```

Выполнение команды перезагрузит конфигурацию systemd, и сервис для запуска Karaf станет доступен

Включить автозапуск сервиса Karaf при старте системы:
```
sudo systemctl enable karaf.service
```

9.1. Управление сервисом Apache Karaf

Запуск сервиса karaf выполняется командой:
```
sudo systemctl start karaf.service
```
Остановка сервиса karaf выполняется командой:
```
sudo systemctl stop karaf.service
```

10. Подготовка ОС для установки Entaxy

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

sudo mkdir -p /opt/karaf/bundle-repository
sudo mkdir -p /mnt/entaxy/file-connector/message-store
sudo mkdir -p /mnt/entaxy/ignite
sudo mkdir -p /mnt/entaxy/filestore
sudo chown -R karaf:karaf /opt/karaf/bundle-repository
sudo chown -R karaf:karaf /mnt/entaxy

11. Установка Entaxy

11.1. Проверка работоспособности Apache Karaf

Установка Entaxy осуществляется из консоли управления Apache Karaf. Чтобы войти в консоль управления Apache Karaf, нужно выполнить в терминале команду:

ssh -p 8101 karaf@localhost

При первом входе в консоль управления необходимо на запрос предоставления доступа ввести слово yes и нажать Enter После этого Apache Karaf запросит пароль - в качестве пароля ввести karaf

Warning: Permanently added '[localhost]:8101' (RSA) to the list of known hosts.
Password authentication
Password:
        __ __                  ____
       / //_/____ __________ _/ __/
      / ,<  / __ `/ ___/ __ `/ /_
     / /| |/ /_/ / /  / /_/ / __/
    /_/ |_|\__,_/_/   \__,_/_/

  Apache Karaf (4.2.9)

Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit 'system:shutdown' to shutdown Karaf.
Hit '<ctrl-d>' or type 'logout' to disconnect shell from current session.

Для контроля корректности установки ввести команду list:

karaf@root()> list
START LEVEL 100 , List Threshold: 50
ID │ State  │ Lvl │ Version │ Name
───┼────────┼─────┼─────────┼────────────────────────────────────────────────
22 │ Active │  80 │ 4.2.9   │ Apache Karaf :: OSGi Services :: Event
karaf@root()>

Если статус компонента Apache Karaf :: OSGi Services :: Event установлен в состояние Active, это значит, что Apache Karaf установлен корректно, и можно переходить к установке Entaxy.

11.2. Установка Entaxy

Установка Entaxy выполняется из консоли управления Apache Karaf. Сначала к списку репозиториев Karaf добавляется репозиторий Entaxy:

feature:repo-add mvn:ru.entaxy.esb/karaf-features/1.9.0-SNAPSHOT/xml/features

Затем запускается команда установки всех компонентов Entaxy

feature:install entaxy-all

После завершения установки Entaxy произойдёт выход из консоли управления Apache Karaf. Это связано с перезапуском встроенного в Karaf SSH сервера. Это нормальная ситуация, в процессе установки происходит настройка устанавливаемых компонентов.

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

Чтобы проверить корректность установки необходимо вновь зайти в консоль управления Karaf:

ssh -p 8101 karaf@localhost

В консоли управления ввести команду:

karaf@root()> list

Отобразится список установленных компонентов Entaxy, и вспомогательных библиотек. Состояние почти всех компонентов должно быть Active

Среди компонентов, которые могут не находиться в состоянии Active можно выделить два:

camel-caffeine-lrucache может находиться в состоянии Resolved

11.4. Отключение компонента установки Nexus

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

Sonatype Nexus
Файловая система

По умолчанию все генерируемые компоненты помещаются в систему управления репозиториями Sonatype Nexus. Это отдельное ПО, целесообразность установки которого оправдана только в кластерных конфигурациях. В нашем случае установка всей системы выполняется на одну машину.

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

Войти в консоль управления Karaf
Найти идентификатор компонента SYSTEM :: ENTAXY :: NEXUS :: DEPLOYER

Остановить его командой:

karaf@root()> bundle:stop <id_компонента>

12. Настройка обновления файла аутентификации `htpasswd`

В Entaxy используется Basic аутентификация для всех запросов, приходящих на балансировщик, функции которого выполняет nginx. Аутентификация производится средствами самого nginx.

В качестве базы для хранения пользователей nginx использует файл в специальном формате htpasswd.

Для того, чтобы вновь созданные пользователи в Системе могли аутентифицироваться, необходимо передать информацию о них в файл htpasswd. Для этого используется специальный скрипт, который отрабатывает по расписанию. Сам скрипт нужно предварительно скачать (htpasswd-checker.sh) и затем вставить в любой каталог, например, в /opt/htpasswd-checker:

sudo mkdir -p /opt/htpasswd-checker/log
sudo cp /home/<username>/distrib/nginx/htpasswd /etc/nginx
sudo cp /home/<username>/distrib/script/htpasswd-checker.sh /opt/htpasswd-checker
sudo chown -R root:root /opt/htpasswd-checker

Так же требуется проверить адреса серверов кластера, публикующих сервис для работы с файлом htpasswd(сервера с karaf) для ключа KARAF_HOST_NAMES:

KARAF_HOST_NAMES=("http://192.168.122.93:9091" "http://192.168.122.94:9091")

Затем создать расписание запуска для cron:

sudo crontab -e

В открывшемся редакторе добавить запись:

* * * * * /opt/htpasswd-checker/htpasswd-checker.sh

и сохранить файл. Теперь скрипт будет отрабатывать каждую минуту, подключаться к сервису аутентификации в Apache Karaf, проверять изменение пользовательской информации, и обновлять файл /etc/nginx/htpasswd если информация обновилась.

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

Чтобы проверить, что сервисы Entaxy работают, можно провести быстрый тест.

Для этого открыть браузер на машине, где установлена Система, и перейти по адресу http://localhost:8181/cxf. Браузер запросит имя пользователя и пароль. Ввести admin в качестве имени пользователя, и admin в качестве пароля. Логин и пароль уже прописаны в файле /etc/nginx/htpasswd. При успешной аутентификации отобразится страница следующего вида:

На этом установку Системы можно считать законченной.