= Руководство по установке Entaxy :nofooter: :toc: left :toc-title: Содержание :sectnums: :icons: font :title-page: :revnumber: 1.0 <<< == Цель руководства Данное руководство описывает процесс установки системы Entaxy (далее Система) на сервер или рабочую станцию в демонстрационных целях. <<< == Требования и замечания Для установки Системы требуется: - Установленная на сервер или рабочую станцию операционная система LTS: AstraLinux 2.12 (Orel), RHEL (CentOS), Ubuntu с настроенными репозиториями для установки программного обеспечения, входящего в состав поставки ОС - Созданный в системе пользователь с правами sudo. Под этим пользователем будет производиться установка Системы. Далее по инструкции имя пользователя обозначено как ``. Вместо `` нужно подставить имя пользователя, который будет производить установку. - Опыт работы с Debian/Ubuntu/AstraLinux системами <<< == Дистрибутивы программных продуктов Вместе с инструкцией поставляются все дистрибутивы, необходимые для установки Системы. Их распространение разрешено лицензиями. Дистрибутивы доступны в каталоге `distrib`. Перед установкой Системы нужно скопировать этот каталог на сервер или рабочую станцию, куда будет производиться установка в каталог `/home/`. Вся дальнейшая установка Системы будет производиться из файлов, скопированных в `/home//distrib` <<< == Установка PostgresPro 11 Standard Edition Система использует СУБД PostgresPro 11 Standard для хранения конфигураций, справочников и т.д. Указанная СУБД входит в Реестр программных продуктов. Для установки PostgresPro 11 Standard Edition необходимо перейти в каталог с дистрибутивом PostgresPro 11 Standard Edition, и установить пакеты в следующей последовательности: [source,bash] ---- cd /home//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//distrib/openjdk`, распаковать дистрибутив OpenJDK 11 в каталог установки и назначить на распакованные файлы права пользователя `root`: [source,bash] ---- cd /home//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//distrib/nginx/sites-available` в `/etc/nginx/sites-available`, создать символьную ссылку на конфигурацию в каталоге разрешённых конфигураций: [source,bash] ---- sudo rm -rf /etc/nginx/sites-enabled/default sudo cp /home//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//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//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//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 ---- + . Создать файл сервиса `/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//distrib/entaxy/etc` в каталог `/opt/karaf/etc`. Все файлы предварительно настроены для работы всех компонентов на одной машине: [source,bash] ---- sudo cp -a /home//distrib/entaxy/etc/. /opt/karaf/etc sudo chown -R karaf:karaf /opt/karaf/etc ---- Установочные файлы Системы хранятся в локальном репозитории артефактов. Перед установкой Системы необходимо скопировать локальный репозиторий из каталога `/home//distrib/entaxy/.m2` в `/opt/karaf`: [source,bash] ---- sudo cp /home//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 '' for a list of available commands and '[cmd] --help' for help on a specific command. Hit 'system:shutdown' to shutdown Karaf. Hit '' 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/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 ---- Например, если идентификатор компонента 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 ---- <<< == Настройка обновления файла аутентификации `htpasswd` В Entaxy используется Basic аутентификация для всех запросов, приходящих на балансировщик, функции которого выполняет `nginx`. Аутентификация производится средствами самого `nginx`. В качестве базы для хранения пользователей `nginx` использует файл в специальном формате htpasswd. Для того, чтобы вновь созданные пользователи в Системе могли аутентифицироваться, необходимо передать информацию о них в файл htpasswd. Для этого используется специальный скрипт, который отрабатывает по расписанию. Сам скрипт нужно предварительно скопировать из каталога `/home//distrib/script/htpasswd-checker.sh` в любой каталог, например, в `/opt/htpasswd-checker`: [source,bash] ---- sudo mkdir -p /opt/htpasswd-checker/log sudo cp /home//distrib/nginx/htpasswd /etc/nginx sudo cp /home//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[] На этом установку Системы можно считать законченной.