Данное руководство описывает процесс установки системы 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, и установить пакеты в следующей последовательности:
При установке последнего пакета производится автоматическая инициализация кластера СУБД, поэтому никаких действий по начальной инициализации 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`, создать символьную ссылку на конфигурацию в каталоге разрешённых конфигураций:
Установка Apache Artemis производится в каталог `/opt/artemis`
Для установки Apache Artemis необходимо выполнить следующие шаги:
. Создать пользователя `artemis`, под которым будет работать Artemis. При создании пользователя создаётся домашний каталог пользователя `/opt/artemis`, в котором будет установлен сам Artemis:
После выполнения команды создаётся новый брокер в каталоге `/opt/artemis/brokers/entaxy-broker` с именем `entaxy-broker`. Имя брокера задаётся в параметре `--name`.
Имя пользователя и пароль для входа в Web консоль брокера задаётся в параметрах `--user` и `--password` соответственно.
+
. Создать файл сервиса `/etc/systemd/system/entaxy@artemis.service`:
Установка Apache Karaf производится в каталог `/opt/karaf`
Для установки Apache Karaf необходимо выполнить следующие шаги:
. Создать пользователя `karaf`, под которым будет работать Karaf. При создании пользователя создаётся домашний каталог пользователя `/opt/karaf`, в котором будет установлен сам Karaf:
. Отредактировать переменную окружения `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`:
После копирования файлов конфигураций и локального репозитория можно запустить сервис `karaf`
<<<
== Подготовка ОС для установки Entaxy
Система в процессе работы использует файловые ресурсы, в которых хранятся передаваемые файлы, пакеты и т.д. Эти ресурсы перед установкой Системы необходимо создать:
Установка 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`:
Если статус компонента `Apache Karaf {two-colons} OSGi Services {two-colons} Event` установлен в состояние `Active`, это значит, что Apache Karaf установлен корректно, и можно переходить к установке Entaxy.
=== Установка Entaxy
Установка Entaxy выполняется из консоли управления Apache Karaf. Сначала к списку репозиториев Karaf добавляется репозиторий Entaxy:
Затем запускается команда установки всех компонентов 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. Отключение компонента выполняется следующим образом:
В Entaxy используется Basic аутентификация для всех запросов, приходящих на балансировщик, функции которого выполняет `nginx`. Аутентификация производится средствами самого `nginx`.
В качестве базы для хранения пользователей `nginx` использует файл в специальном формате htpasswd.
Для того, чтобы вновь созданные пользователи в Системе могли аутентифицироваться, необходимо передать информацию о них в файл htpasswd. Для этого используется специальный скрипт, который отрабатывает по расписанию. Сам скрипт нужно предварительно скопировать из каталога `/home/<username>/distrib/script/htpasswd-checker.sh` в любой каталог, например, в `/opt/htpasswd-checker`:
и сохранить файл. Теперь скрипт будет отрабатывать каждую минуту, подключаться к сервису аутентификации в Apache Karaf, проверять изменение пользовательской информации, и обновлять файл `/etc/nginx/htpasswd` если информация обновилась.
<<<
== Проверка работоспособности сервисов
Чтобы проверить, что сервисы Entaxy работают, можно провести быстрый тест.
Для этого открыть браузер на машине, где установлена Система, и перейти по адресу `http://localhost:8181/cxf`. Браузер запросит имя пользователя и пароль. Ввести `admin` в качестве имени пользователя, и `admin` в качестве пароля. Логин и пароль уже прописаны в файле `/etc/nginx/htpasswd`. При успешной аутентификации отобразится страница следующего вида:
image::img/services.png[]
На этом установку Системы можно считать законченной.
