= Руководство по установке Entaxy
:nofooter:
:toc: left
:toc-title: Содержание
:sectnums:
:icons: font
:title-page:
:revnumber: 1.0

<<<

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

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

<<<

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

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

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

<<<

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

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

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

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

<<<

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

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

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

[source,bash]
----
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 производить не требуется.

<<<

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

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

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

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

[source,bash]
----
sudo su - postgres
psql
----

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

. Создание пользователя:
+
[source,sql]
----
CREATE USER entaxy WITH ENCRYPTED PASSWORD 'entaxy'; 
----
+
. Создание баз данных
+
[source,sql]
----
CREATE DATABASE cache;
CREATE DATABASE storage;
----
+
. Назначение прав пользователю `entaxy` на только что созданные базы `cache` и `storage`:
+
[source,sql]
----
GRANT ALL ON DATABASE cache TO entaxy;
GRANT ALL ON DATABASE storage TO entaxy;
----

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

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

[source,bash]
----
exit
----

<<<

== Установка OpenJDK 11

Установка OpenJDK 11 производится в каталог `/opt/openjdk`

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

[source,bash]
----
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
----

<<<

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

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

[source,bash]
----
sudo apt install nginx
----

Затем удалить конфигурацию nginx по-умолчанию, скопировать предварительно настроенный файл конфигурации `nginx` из каталога `/home/<username>/distrib/nginx/sites-available` в `/etc/nginx/sites-available`, создать символьную ссылку на конфигурацию в каталоге разрешённых конфигураций: 

[source,bash]
----
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` командой:

[source,bash]
----
sudo nginx -t <1>
sudo systemctl reload nginx <2>
----
<1> - валидация конфигурации nginx (если команда вернёт строку `syntax is ok`, то конфигурация валидна)
<2> - перезагрузка конфигурации nginx

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

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

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

[source,bash]
----
sudo systemctl start nginx
----

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

[source,bash]
----
sudo systemctl stop nginx
----

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

[source,bash]
----
sudo systemctl restart nginx
----

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

[source,bash]
----
sudo systemctl reload nginx
----

<<<

== Установка Apache Artemis

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

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

. Создать пользователя `artemis`, под которым будет работать Artemis. При создании пользователя создаётся домашний каталог пользователя `/opt/artemis`, в котором будет установлен сам Artemis:
+
[source,bash]
----
sudo useradd -d /opt/artemis -m -r artemis -s /usr/sbin/nologin
----
+
. Распаковать дистрибутив Artemis в домашний каталог Artemis и назначить распакованным файлам права пользователя `artemis`:
+
[source,bash]
----
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
----
+
. Создать каталог для брокера:
+
[source,bash]
----
sudo mkdir -p /opt/artemis/brokers
sudo chown artemis:artemis /opt/artemis/brokers
----
+
. Создать брокер:
+
[source,bash]
----
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
[source,bash]
----
[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
----
+
. Отредактировать переменную окружения `JAVA_HOME` для сервиса брокера:
+
[source,bash]
----
sudo systemctl edit entaxy@artemis.service
----
+
При выполнении предыдущей команды откроется текстовый редактор, в который надо добавить следующее содержимое, после чего сохранить файл:
+
[source,bash]
----
[Service]
Environment="JAVA_HOME=/opt/openjdk/jdk-11.0.11"
----

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

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

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

[source,bash]
----
sudo systemctl enable entaxy@artemis.service
----

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

[source,bash]
----
sudo systemctl start entaxy@artemis.service
----

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

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

[source,bash]
----
sudo systemctl start entaxy@artemis.service
----

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

[source,bash]
----
sudo systemctl stop entaxy@artemis.service
----

<<<

== Установка Apache Karaf

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

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

. Создать пользователя `karaf`, под которым будет работать Karaf. При создании пользователя создаётся домашний каталог пользователя `/opt/karaf`, в котором будет установлен сам Karaf:
+
[source,bash]
----
sudo useradd -d /opt/karaf -m -r karaf -s /usr/sbin/nologin
----
+
. Распаковать дистрибутив Karaf в домашний каталог, и назначить распакованным файлам права пользователя `karaf`:
+
[source,bash]
----
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
----
+
. Отредактировать переменную окружения `JAVA_HOME` для Karaf:
+
[source,bash]
----
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:
+
[source,bash]
----
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
[source,bash]
----
[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
----
+
. После создания файла сервиса и определения переменных окружения, выполнить команду:
+
[source,bash]
----
sudo systemctl daemon-reload
----

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

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

[source,bash]
----
sudo systemctl enable karaf.service
----

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

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

[source,bash]
----
sudo systemctl start karaf.service
----

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

[source,bash]
----
sudo systemctl stop karaf.service
----

<<<

== Настройка Apache Karaf

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

[source,bash]
----
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`:

[source,bash]
----
sudo cp /home/<username>/distrib/entaxy/.m2/. /opt/karaf/.m2
sudo chown -R karaf:karaf /opt/karaf/.m2
----

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

<<<

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

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

[source,bash]
----
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
----

<<<

== Установка Entaxy

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

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

[source,bash]
----
ssh -p 8101 karaf@localhost
----

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

[source,bash]
----
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`: 

[source,bash]
----
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 {two-colons} OSGi Services {two-colons} Event` установлен в состояние `Active`, это значит, что Apache Karaf установлен корректно, и можно переходить к установке Entaxy.

=== Установка Entaxy

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

[source,bash]
----
feature:repo-add mvn:ru.entaxy.esb/karaf-features/1.8.1/xml/features
----

Затем запускается команда установки всех компонентов Entaxy
[source,bash]
----
feature:install entaxy-all
----

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

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

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

[source,bash]
----
ssh -p 8101 karaf@localhost
----

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

[source,bash]
----
karaf@root()> list
----

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

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

- `camel-caffeine-lrucache` может находиться в состоянии `Resolved`
- `INTEGRATION {two-colons} ENTAXY {two-colons} DB EXAMPLE CONNECTOR` будет находиться в состоянии `Failure`

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

[source,bash]
----
karaf@root()> bundle:stop <id_компонента>
----

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

[source,bash]
----
 97 │ Failure  │  80 │ 1.0.0.SNAPSHOT     │ INTEGRATION :: ENTAXY :: DB EXAMPLE CONNECTOR
----

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

[source,bash]
----
karaf@root()> bundle:stop 97
----

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

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

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

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

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

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

. Войти в консоль управления Karaf
. Найти идентфикатор компонента `SYSTEM {two-colons} ENTAXY {two-colons} NEXUS {two-colons} DEPLOYER`
. Остановить его командой:
+
[source,bash]
----
karaf@root()> bundle:stop <id_компонента>
----

<<<

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

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

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

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

[source,bash]
----
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:
[source,bash]
----
KARAF_HOST_NAMES=("http://192.168.122.93:9091" "http://192.168.122.94:9091")
----

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

[source,bash]
----
sudo crontab -e
----

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

[source,bash]
----
* * * * * /opt/htpasswd-checker/htpasswd-checker.sh
----

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

<<<

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

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

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

image::img/services.png[]

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