entaxy-public/documentation/installation/install.adoc
2021-09-14 10:54:30 +03:00

626 lines
27 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

= Руководство по установке 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
----
+
. Создать файл сервиса `/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.0/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[]
На этом установку Системы можно считать законченной.