.. _applications: ECOS Приложения =============== .. contents:: :depth: 3 Определения -------------- **Приложение ECOS** (ECOS App) - приложение, которое содержит в себе :ref:`артефакты` (единицы расширения системы). Примеры артефактов: :guilabel:`Тип`, :guilabel:`Форма`, :guilabel:`Журнал`. Приложение ECOS представляет собой zip-архив с мета информацией (id, name, dependencies, version) и модулями (form, journal, menu, credentials, datasource, …). Основная задача приложений ECOS - переносимость артефактов между стендами и возможность версионирования. **ECOS Application** сам является артефактом, но его нельзя включить в другие приложения т.к. это системный тип. Работа с приложениями ----------------------- Работа с приложениями осуществляется на странице администратора системы. ``http://host/v2/admin?journalId=ecos-apps&type=JOURNAL`` .. image:: _static/apps/apps_page.png :width: 600 :align: center :alt: ECOS apps На этой странице можно: 1. Cоздавать и редактировать приложения. 2. Скачивать приложения. Перенос данных с одного стенда на другой ------------------------------------------ Перенос данных со стенда на стенд осуществляется через **Приложения ECOS**. Для этого необходимо: 1. Создать приложение по кнопке **+**. .. image:: _static/apps/new_app.png :width: 600 :align: center :alt: Создать приложение Ввести наименование, выбрать тип данных и автоматически иди вручную добавить соответствующие артефакты. 2. Скачать приложение. .. image:: _static/apps/apps_page_1.png :width: 600 :align: center :alt: Скачать приложение 3. Загрузить приложение на необходимом стенде. .. image:: _static/apps/apps_page_2.png :width: 600 :align: center :alt: Скачать приложение Структура архива приложения ---------------------------- :: meta.json // метаданные приложения artifacts: // папка с артефактами приложения type0: subType0: artifact0.json artifact1.json ... subType1: artifact0.json artifact1.json ... typ1: subType0: artifact0.json ... subType1: artifact0.json ... ... Артефакты ---------- Для управления :ref:`артефактами` предусмотрен журнал **Артефакты ECOS**. В данный журнал попадают все артефакты, которые достигли микросервиса ``ecos-apps``. .. image:: _static/apps/artifacts.png :width: 600 :align: center :alt: Артефакты В данном журнале есть возможность выполнить следующие действия: .. image:: _static/apps/artifacts_2.png :width: 200 :align: center **1. Скачать историю артефакта** * При нажатии на действие можно выбрать дату, с которой необходимо выгрузить историю артефакта. * При сабмите формы скачивается **zip** архив со всеми версиями артефакта с указанной даты. * Если последний артефакт был загружен ранее чем выбраная дата, то будет выгружен только он (т.е. всегда будет как минимум 1 артефакт). * Формат имени папки с версией артефакта: **дата_созданияTвремя_созданияZ-[USER | APPLICATION | ECOS_APP]**. Дата создания указывается в часовом поясе UTC. .. image:: _static/apps/artifact-history.png :width: 600 :align: center :alt: Версия артефакта **2. Скачать артефакт** Всегда скачивается *zip* архив с выбранным артефактом. **3. Передеплоить артефакт вручную** Отправить артефакт из ``ecos-apps`` в микросервис. Может быть полезно при разработке или после сбоя в базе целевого микросервиса т.е. ``ecos-apps`` не пропускает артефакт если он ранее был успешно задеплоен. **4. Сбросить пользовательскую версию артефакта** Сброс происходит до той версии, которая была установлена из приложения (``APPLICATION`` или ``ECOS_APP``). Сбрасывать можно только артефакты, которые в колонке :guilabel:`Тип источника` имеют **USER**. Источники артефактов ~~~~~~~~~~~~~~~~~~~~ Есть 3 возможных источника артефактов: 1. **USER** - артефакт добавляет или модифицирует пользователь; 2. **APPLICATION** - артефакт загружается из приложений, которые подключены к интерфейсу команд; 3. **ECOS_APP** - артефакт загружается из приложения ECOS; Обновление артефактов ~~~~~~~~~~~~~~~~~~~~~ Все 3 источника имеют свою политику по обновлению артефактов: * **USER** - Артефакт обновляется безусловно. Любое изменение артефакта приводит к его изменению в базе микросервиса ``ecos-apps``. * **APPLICATION** - Артефакт обновляется если он не принадлежит никакому приложению ECOS и была загружена версия артефакта, которая отличается от предыдущей загруженной из ``APPLICATION``. Пример: Если у нас есть следующие ревизии артефакта: - **rev2** USER - **rev1** USER - **rev0** APPLICATION То **rev0** - самая первая версия артефакта, а **rec2** - самая последняя версия артефакта. Мы видим, что первая версия артефакта поступила из приложения, а другие две от пользователя. Если в такой ситуации в микросервис приходит версия **rev0** от APPLICATION, то ничего не поменяется не смотря на то что **rev2** != **rev0**. Если из приложения придет **rev3**, то новая ревизия загрузится и станет актуальной: - **rev3** APPLICATION - **rev2** USER - **rev1** USER - **rev0** APPLICATION **ECOS_APP** - обновляется аналогично APPLICATION, но при загрузке артефакту проставляется признак принадлежности приложению. Если артефакт принадлежит приложению, то он не обновляется из APPLICATION. Создание ECOS Apps проекта --------------------------- .. _app_project: Для создания ECOS Apps проекта нужно создать новый **maven проект** и настроить главный **pom файл** следующим образом: .. code-block:: 4.0.0 ru.citeck.ecos.eapps.assignments ecos-assignments 1.0.0-snapshot ru.citeck.ecos.eapps.project ecos-apps-simple-parent 1.0.3 citeck-public https://nexus.citeck.ru/repository/maven-public Приложения можно расположить двумя способами: ``src/main/resources/app`` - для варианта, когда приложение одно ``src/main/resources/apps/[app0,app1,…]`` - для варианта, когда приложений несколько В корне приложения нужно разместить файл **meta.yml**, в котором можно указать: .. code-block:: id: ecos-assignments * **id: String** - идентификатор приложения. По умолчанию равен artifactId проекта * **name: MLText** - имя приложения Если файл **meta.yml** отсутствует, то он будет сгенерирован автоматически. .. image:: _static/apps/app_folder.png :width: 400 :align: center При сборке приложений получается набор **zip-архивов**, каждый из которых представляет из себя отдельное приложение. Деплой ~~~~~~~ Есть два основных способа деплоя - ручной и автоматический. Ручной деплой """""""""""""" .. _manual_deploy: При ручном деплое мы можем собрать приложения командой: .. code-block:: mvn clean package и загрузить нужный архив из папки ``target/classes/apps`` .. image:: _static/apps/zip_arch.png :width: 400 :align: center через журнал приложений, который доступен по ссылке ``/v2/admin?journalId=ecos-apps&type=JOURNAL`` .. image:: _static/apps/zip_arch_upload.png :width: 600 :align: center Автоматический деплой """""""""""""""""""""" .. _auto_deploy: Автоматический деплой осуществляется через механизм загрузки артефактов в микросервисе **ecos-apps**. Артефакты доставляются в виде docker образа. Команда для сборки docker образа: .. code-block:: mvn clean package jib:dockerBuild -Djib.docker.image.tag=1.0.0-snapshot где **1.0.0-snapshot** - это тег для итогового образа. После сборки образа мы подключаем его там, где развернут микросервис **ecos-apps**: .. code-block:: ecos-assignments-ecos-apps: container_name: ecos-assignments-ecos-apps image: nexus.citeck.ru/ecos-assignments:1.0.0-snapshot environment: - ECOS_APPS_TARGET_DIR=/run/ecos-apps volumes: - ./volumes/ecos-apps:/run/ecos-apps Параметр **ECOS_APPS_TARGET_DIR** - папка, в которую будут скопированы все приложения, которые лежат внутри образа. Копирование происходит с помощью shell скрипта. По завершении копирования приложений ECOS образ сразу же останавливается т.к. на этом его работа заканчивается. Далее нам нужно подключить папку с артефактами (``./volumes/ecos-apps``) как volume в микросервис ecos-apps: .. code-block:: eapps-app-dev: container_name: eapps-app-dev image: nexus.citeck.ru/ecos-apps:2.6.0-snapshot ports: - 8089:8089 environment: ...остальные_env_переменные... - ECOS_WEBAPP_EAPPS_ADDITIONAL_ARTIFACTS_LOCATIONS=/run/ecos-artifacts volumes: - ./volumes/ecos-apps:/run/ecos-artifacts/app/ecosapp В **env** переменной мы передаем конфигурацию **ECOS_WEBAPP_EAPPS_ADDITIONAL_ARTIFACTS_LOCATIONS**, которая указывает на дополнительные папки, из которых нужно загрузить артефакты (приложение ECOS тоже является артефактами с типом **app/ecosapp**). Нашу папку с архивами мы должны подключить как **volume** в директорию ``$ECOS_WEBAPP_EAPPS_ADDITIONAL_ARTIFACTS_LOCATIONS/app/ecosapp`` При запуске микросервиса **ecos-apps** он начинает следить за директориями, которые указаны в **ECOS_WEBAPP_EAPPS_ADDITIONAL_ARTIFACTS_LOCATIONS**, и если приложения, которые там находятся изменяются, то микросервис автоматически их загружает к себе в БД и деплоит оттуда артефакты.