entaxy-public/documentation/installation/install.adoc

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

Содержание

• 1. Цель руководства
• 2. Требования и замечания
• 3. Дистрибутивы программных продуктов
• 4. Установка PostgresPro 11 Standard Edition
• 5. Подготовка СУБД для работы с Entaxy
• 6. Установка OpenJDK 11
• 7. Установка и настройка nginx
  • 7.1. Управление сервисом nginx
• 8. Установка Apache Artemis
  • 8.1. Управление сервисом Apache Artemis
• 9. Установка Apache Karaf
  • 9.1. Управление сервисом Apache Karaf
• 10. Настройка Apache Karaf
• 11. Подготовка ОС для установки Entaxy
• 12. Установка Entaxy
  • 12.1. Проверка работоспособности Apache Karaf
  • 12.2. Установка Entaxy
  • 12.3. Проверка работоспособности Entaxy
  • 12.4. Отключение компонента установки Nexus
• 13. Настройка обновления файла аутентификации htpasswd
• 14. Проверка работоспособности сервисов

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

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

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

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

• Установленная на сервер или рабочую станцию операционная система LTS: AstraLinux 2.12 (Orel), RHEL (CentOS), Ubuntu с настроенными репозиториями для установки программного обеспечения, входящего в состав поставки ОС

• Созданный в системе пользователь с правами sudo. Под этим пользователем будет производиться установка Системы. Далее по инструкции имя пользователя обозначено как <username>. Вместо <username> нужно подставить имя пользователя, который будет производить установку.

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

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

Вместе с инструкцией поставляются все дистрибутивы, необходимые для установки Системы. Их распространение разрешено лицензиями.

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

Вся дальнейшая установка Системы будет производиться из файлов, скопированных в /home/<username>/distrib

4. Установка PostgresPro 11 Standard Edition

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

Для установки PostgresPro 11 Standard Edition необходимо перейти в каталог с дистрибутивом PostgresPro 11 Standard Edition, и установить пакеты в следующей последовательности:

cd /home/<username>/distrib/postgrespro-std-11
sudo apt install ./postgrespro-std-11-libs_11.12.1-1.orel_amd64.deb
sudo apt install ./postgrespro-std-11-client_11.12.1-1.orel_amd64.deb
sudo apt install ./postgrespro-std-11-server_11.12.1-1.orel_amd64.deb
sudo apt install ./postgrespro-std-11-contrib_11.12.1-1.orel_amd64.deb
sudo apt install ./postgrespro-std-11_11.12.1-1.orel_amd64.deb

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

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

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

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

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

sudo su - postgres
psql

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

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

   CREATE USER entaxy WITH ENCRYPTED PASSWORD 'entaxy';

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

   CREATE DATABASE cache;
   CREATE DATABASE storage;

3. Назначение прав пользователю 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

Для установки OpenJDK 11 нужно перейти в каталог /home/<username>/distrib/openjdk, распаковать дистрибутив OpenJDK 11 в каталог установки и назначить на распакованные файлы права пользователя root:

cd /home/<username>/distrib/openjdk
sudo mkdir -p /opt/openjdk
sudo tar xvf bellsoft-jdk11.0.11+9-linux-amd64.tar.gz -C /opt/openjdk
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 по-умолчанию, скопировать предварительно настроенный файл конфигурации nginx из каталога /home/<username>/distrib/nginx/sites-available в /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 необходимо выполнить следующие шаги:

1. Создать пользователя artemis, под которым будет работать Artemis. При создании пользователя создаётся домашний каталог пользователя /opt/artemis, в котором будет установлен сам Artemis:

   sudo useradd -d /opt/artemis -m -r artemis -s /usr/sbin/nologin

2. Распаковать дистрибутив Artemis в домашний каталог Artemis и назначить распакованным файлам права пользователя artemis:

   cd /home/<username>/distrib/artemis
   sudo tar xvf apache-artemis-2.17.0-bin.tar.gz -C /opt/artemis
   sudo cp -a /opt/artemis/apache-artemis-2.17.0/. /opt/artemis/
   sudo rm -rf /opt/artemis/apache-artemis-2.17.0
   sudo chown -R artemis:artemis /opt/artemis

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

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

4. Создать брокер:

   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 соответственно.

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

   entaxy-broker@artemis.service

   [Unit]
   Description=Artemis ActiveMQ Message Broker
   After=syslog.target 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
   
   [Install]
   WantedBy=multi-user.target

6. Отредактировать переменную окружения 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

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

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

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

1. Создать пользователя karaf, под которым будет работать Karaf. При создании пользователя создаётся домашний каталог пользователя /opt/karaf, в котором будет установлен сам Karaf:

   sudo useradd -d /opt/karaf -m -r karaf -s /usr/sbin/nologin

2. Распаковать дистрибутив Karaf в домашний каталог, и назначить распакованным файлам права пользователя karaf:

   cd /home/<username>/distrib/karaf
   sudo tar xvf apache-karaf-4.2.9.tar.gz -C /opt/karaf
   sudo cp -a /opt/karaf/apache-karaf-4.2.9/. /opt/karaf
   sudo rm -rf /opt/karaf/apache-karaf-4.2.9
   sudo cp /home/<username>/distrib/karaf/jre.properties /opt/karaf/etc/jre.properties
   sudo chown -R karaf:karaf /opt/karaf

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

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

4. Отредактировать переменную окружения 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

5. Создать файл сервиса /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

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

   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. Настройка Apache Karaf

Скопируйте файлы конфигурации Entaxy из /home/<username>/distrib/entaxy/etc в каталог /opt/karaf/etc. Все файлы предварительно настроены для работы всех компонентов на одной машине:

sudo cp -a /home/<username>/distrib/entaxy/etc/. /opt/karaf/etc
sudo chown -R karaf:karaf /opt/karaf/etc

Установочные файлы Системы хранятся в локальном репозитории артефактов. Перед установкой Системы необходимо скопировать локальный репозиторий из каталога /home/<username>/distrib/entaxy/.m2 в /opt/karaf:

sudo cp /home/<username>/distrib/entaxy/.m2/. /opt/karaf/.m2
sudo chown -R karaf:karaf /opt/karaf/.m2

После копирования файлов конфигураций и локального репозитория можно запустить сервис karaf

11. Подготовка ОС для установки 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

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

12.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.

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

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

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

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

feature:install entaxy-all

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

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

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

ssh -p 8101 karaf@localhost

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

karaf@root()> list

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

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

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

• INTEGRATION :: ENTAXY :: DB EXAMPLE CONNECTOR будет находиться в состоянии Failure

Компонент INTEGRATION :: ENTAXY :: DB EXAMPLE CONNECTOR необходимо отключить командой:

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

Например, если идентификатор компонента 97, как показано ниже,

 97 │ Failure  │  80 │ 1.0.0.SNAPSHOT     │ INTEGRATION :: ENTAXY :: DB EXAMPLE CONNECTOR

то команда будет выглядеть так:

karaf@root()> bundle:stop 97

После остановки компонент перейдёт в состояние Resolved

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

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

• Sonatype Nexus

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

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

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

1. Войти в консоль управления Karaf

2. Найти идентфикатор компонента SYSTEM :: ENTAXY :: NEXUS :: DEPLOYER

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

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

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

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

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

Для того, чтобы вновь созданные пользователи в Системе могли аутентифицироваться, необходимо передать информацию о них в файл htpasswd. Для этого используется специальный скрипт, который отрабатывает по расписанию. Сам скрипт нужно предварительно скопировать из каталога /home/<username>/distrib/script/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 если информация обновилась.

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

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

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

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