¶ 1. Назначение документа
Настоящее руководство содержит описание процесса установки, настройки, обновления и администрирования ПО Cubisio в серверном варианте развёртывания.
В документе описаны команды для администрирования приложения в двух режимах: ручном standalone режиме и обычнном сервером варианте с использованием утилиты администрирования. Все команды приведены на примере ОС Ubuntu 20.04, для других ОС данные действия осуществляются аналогичным образом.
¶ 2. Режим standalone, Linux
¶ 2.1. Установка
Для серверного варианта развертывания ПО Cubisio поставляется в виде zip архива со всеми исполняемыми модулями и ресурсами программы.
¶ 2.1.1. Предварительные условия
Для выполнения настройки ПО Сubisio требуется наличие прав администратора посредством команды sudo, а также наличие интерпретатора bash для запуска команд и исполняемого файла программы.
¶ 2.1.1.1. Установка виртуальной машины Java
Для работы Cubisio требуется установить виртуальную машину Java, например, OpenJDK 1.8 или OpenJDK 11, а также настроить видимость исполняемого файла java в PATH, а также переменные среды окружения, в частности JAVA_HOME.
Данный шаг можно пропустить, если в ОС установлена одна из требуемых версий Java.
1) Вариант 1 - OpenJDK 1.8
Ниже представлен пример установки OpenJDK 1.8 с использованием стандартного менеджера пакетов и установщика.
- Выполните установку пакета OpenJDK 1.8 из стандартного репозитория:
$ sudo apt-get install -y openjdk-8-jdk
- Выполните настройку переменных окружения ОС, действующих в том числе после перезапуска ОС.
Для упрощения процесса ниже производится создание файла, осуществляющего одновременную настройку нескольких переменных окружения. Данный файл выполняется при каждом запуске ОС. Выполните следующие команды:
-
$ sudo touch /etc/profile.d/javajdk.sh -
$ echo export PATH=$PATH:/usr/lib/jvm/java-8-openjdk-amd64/bin > /etc/profile.d/javajdk.sh -
$ echo export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64/ > /etc/profile.d/javajdk.sh -
$ echo export JRE_HOME=/usr/lib/jvm/java-8-openjdk-amd64/jre/ > /etc/profile.d/javajdk.sh -
$ sudo chmod 744 /etc/profile.d/javajdk.sh
- Для проверки установки Java выполните:
$ java -version
В результате выполнения команды в консоли должна быть выведена установленная версия Java - 1.8.
2) Вариант 2 - Oracle Java 1.8
Ниже представлен пример установки альтернативной версии Oracle Java 1.8 с использованием стандартного установщика, для этого выполните следующие команды:
sudo add-apt-repository -y ppa:webupd8team/javasudo apt-get update -ysudo apt-get install -y oracle-java8-installersudo apt-get install -y oracle-java8-set-default
Для проверки установки Java выполните:
$ java -version
В результате выполнения команды в консоли должна быть выведена установленная версия Java - 1.8.
¶ 2.1.1.2. Установка дополнительных компонент
Для установки архиватора zip, который требуется для распаковки архива с дистрибутивом программы, выполните:
$ sudo apt install -y zip
¶ 2.1.2. Установка Cubisio
- Выполните распаковку дистрибутива Cubisio в целевую директорию (например,
/home/user/cubisio):
$ unzip "cubisio.zip" -d "/home/user/cubisio"
- Установите права на запуск исполняемых файлов программы:
$ chmod +x "/home/user/cubisio/jsb-application/"*.sh
¶ 2.2. Настройка и конфигурирование
В общем случае дистрибутив Cubisio включает конфигурацию по умолчанию, которой достаточно для запуска и использования приложения в режиме standalone без предварительной настройки. Как правило, изменение конфигурации по умолчанию требуется для настройки дополнительного расширенного функционала, изменения режима работы, тонкой настройки под инфраструктурное окружение, а также для интеграции со смежными подсистемами.
¶ 2.2.1. Основные настройки
Конфигурационные файлы *.conf сервера приложений Cubisio располагаются в папке ./jsb-application/config.
Для удобства обновления серверно зависимой конфигурации рекомендуется сохранять в файле
SERVER.conf. Данный файл не должен обновляться и изменяться при регулярном обновлении версии. Все остальные конфигурационные файлы рекомендуется включать в дистрибутив в актуальном виде.
1) Настройка порта web-сервера
Для задания порта web-сервера задайте опцию конфигурации web.http.port, например добавьте в файл SERVER.conf строку:
web.http.port = 8888
Для работы некоторых функций Cubisio, требующих возможность обратного вызова API со стороны сторонних сервисов, требуется указать актуальный URL в опцию конфигурации web.http.url, например добавьте в файл SERVER.conf строку:
web.http.url = "http://127.0.0.1:8888"
2) Настройка расположения пользовательских рабочих областей
Для задания директории расположения рабочих областей задайте конфигурацию workspace.folder, например добавьте в файл SERVER.conf строки:
workspace.workspaceTypes.system.entryStore.baseDirectory = ${user.home}/.cubisio/system workspace.workspaceTypes.user.entryStore.baseDirectory = ${user.home}/.cubisio/user workspace.workspaceTypes.shared.entryStore.baseDirectory = ${user.home}/.cubisio/shared
¶ 2.3. Обновление версии
Для обновления Cubisio достаточно удалить старые файлы приложения и распаковать архив с новой версией в директорию приложения.
- Остановите Cubisio, в режиме standalone достаточно нажать
Ctrl-Cдождаться завершения. Для сервиса используйте команду:
sudo systemctl stop cubisio
-
Сделайте бекап файлов приложения (
~/cubisioили /opt/cubisio/cubisio) и файлов рабочей области (~/.cubisioили /opt/cubisio/.cubisio) -
Удалите старые файлы приложения, для этого выполните команду:
$ rm -fR /home/user/cubisio
или
$ rm -fR /opt/cubisio/cubisio
-
Распакуйте архив с новой версией и задайте права для запуска исполняемых файлов, как указано в разделе "Установка Cubisio".
-
Скопируйте серверно или проектно зависимые файлы конфигурации (все файлы, которые менялись при установке и настройке) из бекапа в папку с программой, как правило это
./config/SERVER.confи./web/WEB-INF/keycloak.json. -
Запустите сервис Cubisio, используя команду:
sudo systemctl stop cubisio
Для контроля запуска можно отслеживать лог, например, используя команды:
tail -f -n 1000 /opt/cubisio/cubisio/logs/jsbeans.log
или
less /opt/cubisio/cubisio/logs/jsbeans.log
¶ 2.4. Запуск
1) Запуск приложения в режиме standalone
Для запуска Cubisio в режиме standalone необходимо выполнить исполняемый файл start.sh, например выполнить команду:
$ cd /home/user/cubisio/jsb-application && ./start_release.sh
В результате успешного запуска в консоли будет выведено сообщение, содержащее (см. Рисунок 1):
Workspace controller initialization done.
Рисунок 1 - вывод консоли после успешного запуска Cubisio
2) Открытие пользовательского портала
Для открытия портала пользователя-аналитика необходимо открыть в браузере URL главной страницы, например:
http://localhost:8888/cubisio.jsb.
При завершении загрузки указанной страницы будет отображён центральный графический интерфейс системы, включающий панель навигации и окно приветствия, см. Рисунок 2. При первом запуске будет открыта рабочая область "Системные настройки", при повторном запуске будет открыт текущий активный или последний открытый проект.
Рисунок 2 - окно приветствия Cubisio
¶ 3. Cubisio Admin Tools, Linux
Для удобства развёртывания и администрирования Cubisio на серверах может быть использована утилита администрирования - admin/admin.sh.
Улитита администрирования состоит из двух частей:
./base/**- базовая неизменная часть, включающая базовые команды и общие настройки;./resource/**,*.properties- переопределение для конкретного проекта, может включать настройки для конкретных серверов.
¶ 3.1. Установка
¶ 3.1.1. Подготовка сервера
Настройка локали и установка утилит
sudo dpkg-reconfigure locales sudo apt install -y fail2ban mc curl net-tools
Закачать утилиту администрирования на удалённый сервер
Выполнять команду на сервере, с которого необходимо закачать утилиту на удалённый сервер.
cd ./admin ./admin.sh --upload_scripts_create_dir 'yes' --upload_scripts_ssh 'cb@123.123.123.123' upload_scripts
Установка и настройка почтовых уведомлений (SMTP)
~/admin-cubisio/admin.sh install_ssmtp
Настройка iptables и отключение IPv6
~/admin-cubisio/admin.sh install_iptables
¶ 3.1.2. Установка JVM
Установка Open JDK 8
~/admin-cubisio/admin.sh install_openjdk8
¶ 3.1.3. Установка СУБД
¶ 3.1.3.1. Установка Postgresql
Установка Postgresql с настройками по умолчанию
$ ~/admin-cubisio/admin.sh install_postgresql
¶ 3.1.3.2. Установка ClickHouse
Установка ClickHouse и пароля, зашифрованного SHA256
$ ~/admin-cubisio/admin.sh install_clickhouse
¶ 3.1.4. Установка Cubisio
Установить почтовую SMTP утилиту для рассылки уведомлений
~/admin-cubisio/admin.sh install_ssmtp
Установить билдсервер Cubisio
~/admin-cubisio/admin.sh install_build_server
Выполнить и настроить сборку
~/admin-cubisio/admin.sh repo_updated_build
Установить сервер приложений Cubisio
~/admin-cubisio/admin.sh jsb_app_install
Разрешение перезапуска сервиса cubisio без ввода пароля sudo
Выполнить sudo visudo и добавить:
cb ALL= NOPASSWD: /bin/systemctl * cubisio-online.service
Установить Web-фасад nginx для Cubisio
~/admin-cubisio/admin.sh jsb_app_nginx_install
Установка оснастки краулеров
Установка: Chrome, сhromedriver, xvfb; x11vnc; noVNC. В nginx добавляется конфигурация /etc/nginx/conf.d/crawler-rdp.conf – настроен сквозной проброс интерфейса удалённого доступа для N экранов, а также экраны спрятаны за авторизацией через subrequest.
$ ~/admin.sh --crawler_displays 2 install_crawler
Конфигурация установщика ~/admin-cubisio/.crawler.properties или ~/admin-cubisio/base/tools/.crawler.properties.
¶ 3.2. Настройка и конфигурирование
¶ 3.2.1. Настройка авторизации на базе Keykloak
Установка Keycloak
~/admin-cubisio/admin.sh keycloak_install
Настройка пароля администратора для Keykloak
Необходимо пробросить порь сервера 8080 на локальную машину, например так:
ssh -o ServerAliveInterval=60 cb@server.local -L 8080:127.0.0.1:8080
Далее в локальном браузере открыть url http://localhost:8080/auth/ и задать пароль администратора.
Установка nginx прокси для keycloak (keycloak.conf)
~/admin-cubisio/admin.sh keycloak_nginx_install
Keycloak под HTTPS может не открываться из-за ошибки подмены протокола, поэтому требуется:
В конфиге keycloak standalone.xml или standalone-ha.xml добавить proxy-address-forwarding="true" в /, чтобы не было ошибки подмены протокола.
В данном случае достаточно выполнить:
sudo sed -i -e 's/<http-listener /<http-listener proxy-address-forwarding="true" /' /opt/keycloak/keycloak-15.0.1/standalone/configuration/standalone.xml
sudo systemctl restart keycloak
Настройка интеграции Cubisio с Keykloak
- добавить в SERVER.conf:
keycloak.cubisioClient.user = "admin"
keycloak.cubisioClient.password = "KEYKLOAK_PASSWORD"
-
Вставить актуальные ключ и адрес сервера авторизации в
WEB-INF/keycloak.json -
Перезапустить Cubisio
¶ 3.3. Обновление версии
Необходимо выполнить вход по ssh под пользователем cb (cb - основной пользователь, под которым работает приложение, он же управляющий с правом перезапуска сервиса без ввода пароля sudo).
Сборка из исходников текущей версии
$ ~/admin-cubisio/admin.sh repo_build
Загрузка обновлений и сборка
Команда выполняет загрузку обновлений из репозитория и сборку, в случае если изменения были получены (если изменений не было - выход с ошибкой). По результатам отправляет отчёт.
$ ~/admin-cubisio/admin.sh repo_updated_build
Обновление портала
- Команда сохраняет текущую копию в папке ~/cubisio-backups для последующей возможности откатить обновление;
- Останавливает сервис портала;
- Выполняет обновление из файла ~/cubisio-build/cubisio/target/*.tar.gz, сохраняя неизменяемые конфигурационные файлы;
- Запускает сервис портала;
- По результатам отправляет отчёт.
$ ~/admin-cubisio/admin.sh update
Сборка и обновление
Двойная команда, которая сначала выполняет загрузку обновлений из репозитория, после чего выполняет сборку и обновление в случае наличия обновлений. По результатам отправляет отчёты.
$ ~/admin-cubisio/admin.sh repo_updated_build jsb_app_update
Для автосборки и обновления в cron зарегистрирована команда, которая выполняется каждые 5 минут:
*/5 * * * * /home/cb/admin-cubisio/admin.sh repo_updated_build jsb_app_update >> /home/cb/.cubisio-autoupdate.log 2>&1
¶ 3.4. Запуск и управление
Запуск сервиса
$ ~/admin-cubisio/admin.sh jsb_app_start
или
$ sudo systemctl start cubisio.service
Остановка сервиса
$ ~/admin-cubisio/admin.sh jsb_app_stop
или
$ sudo systemctl stop cubisio.service
Состояние сервиса
$ ~/admin/admin.sh jsb_app_status
или
$ sudo systemctl status cubisio.service
¶ 4. Советы по исправлению неисправностей
При попытке открыть страницу ошибка, до авторизации Keycloak не доходит, в сервере лога ошибка обработки запроса
- Проверьте доступность сервера авторизации, указанного в web/WEB-INF/keycloak.json
- Проверьте, чтобы "resource" и "secret" соответствовали названию и ключу клиента на сервере авторизации
Авторизация выполняется, но при открытии страницы приложения выводится ошибка в браузере "MIME type"
Лечится добавлением в конфиг Nginx, в секции location, где выполняется проброс запросов:
add_header Permissions-Policy interest-cohort=();