Приложения Citeck 

Приложения Citeck (ECOS Apps) — механизм упаковки, переноса и версионирования артефактов платформы ECOS между различными стендами. Приложение представляет собой zip-архив, содержащий метаданные и набор артефактов: типы данных, формы, журналы, шаблоны и другие элементы конфигурации системы.

На этой странице описано:

как создавать, скачивать и загружать приложения через интерфейс системы;
как переносить данные между стендами;
как создавать ECOS Apps проекты и деплоить их вручную или автоматически через Docker;
как настроить интеграцию с Git-репозиторием для версионирования артефактов.

Определения 

Приложение Citeck (ECOS App) - приложение, которое содержит в себе артефакты (единицы расширения системы). Примеры артефактов: Тип, Форма, Журнал.

Приложение Citeck представляет собой zip-архив с мета информацией (id, name, dependencies, version) и модулями (form, journal, menu, credentials, datasource, …).

Основная задача приложений Citeck - переносимость артефактов между стендами и возможность версионирования.

ECOS Application сам является артефактом, но его нельзя включить в другие приложения т.к. это системный тип.

Работа с приложениями 

Работа с приложениями осуществляется в журнале «Приложения ECOS» (Рабочее пространство «Раздел администратора» - Управление системой) :

Журнал доступен по адресу: v2/journals?journalId=ecos-apps&viewMode=table&ws=admin$workspace

На этой странице можно:

Создавать и редактировать приложения.

Скачивать приложения.

Перенос данных с одного стенда на другой 

Перенос данных со стенда на стенд осуществляется через Приложения ECOS. Для этого необходимо:

Создать приложение по кнопке +.

Ввести наименование, выбрать тип данных и автоматически или вручную добавить соответствующие артефакты.

Скачать приложение.

Загрузить приложение на необходимом стенде.

См. подробней пример

Структура архива приложения 

meta.json // метаданные приложения
artifacts: // папка с артефактами приложения
  type0:
    subType0:
      artifact0.json
      artifact1.json
      ...
    subType1:
      artifact0.json
      artifact1.json
      ...
  type1:
    subType0:
      artifact0.json
      ...
    subType1:
      artifact0.json
      ...
  ...

Создание ECOS Apps проекта 

Для создания ECOS Apps проекта нужно создать новый maven проект и настроить главный pom файл следующим образом:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <groupId>ru.citeck.ecos.eapps.assignments</groupId>
    <artifactId>ecos-assignments</artifactId>
    <version>1.0.0-snapshot</version>

    <parent>
        <groupId>ru.citeck.ecos.eapps.project</groupId>
        <artifactId>ecos-apps-simple-parent</artifactId>
        <version>1.0.3</version>
    </parent>

    <repositories>
        <repository>
            <id>citeck-public</id>
            <url>https://nexus.citeck.ru/repository/maven-public</url>
        </repository>
    </repositories>

</project>

Приложения можно расположить двумя способами:

src/main/resources/app - для варианта, когда приложение одно

src/main/resources/apps/[app0,app1,…] - для варианта, когда приложений несколько

В корне приложения нужно разместить файл meta.yml, в котором можно указать:

id: ecos-assignments

id: String - идентификатор приложения. По умолчанию равен artifactId проекта
name: MLText - имя приложения

Если файл meta.yml отсутствует, то он будет сгенерирован автоматически.

При сборке приложений получается набор zip-архивов, каждый из которых представляет из себя отдельное приложение.

Деплой 

Есть два основных способа деплоя - ручной и автоматический.

Ручной деплой

При ручном деплое мы можем собрать приложения командой:

mvn clean package

и загрузить нужный архив из папки target/classes/apps

через журнал приложений, который доступен по ссылке v2/journals?journalId=ecos-apps&viewMode=table&ws=admin$workspace

Автоматический деплой

Автоматический деплой осуществляется через механизм загрузки артефактов в микросервисе ecos-apps. Артефакты доставляются в виде docker образа.

Команда для сборки docker образа:

mvn clean package jib:dockerBuild -Djib.docker.image.tag=1.0.0-snapshot

где 1.0.0-snapshot - тег для итогового образа.

После сборки образа мы подключаем его там, где развернут микросервис ecos-apps:

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 скрипта. По завершении копирования приложений Citeck образ сразу же останавливается т.к. на этом его работа заканчивается.

Далее нам нужно подключить папку с артефактами (./volumes/ecos-apps) как volume в микросервис ecos-apps:

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, которая указывает на дополнительные папки, из которых нужно загрузить артефакты (приложение Citeck тоже является артефактами с типом app/ecosapp).

Нашу папку с архивами мы должны подключить как volume в директорию $ECOS_WEBAPP_EAPPS_ADDITIONAL_ARTIFACTS_LOCATIONS/app/ecosapp

При запуске микросервиса ecos-apps он начинает следить за директориями, которые указаны в ECOS_WEBAPP_EAPPS_ADDITIONAL_ARTIFACTS_LOCATIONS, и если приложения, которые там находятся изменяются, то микросервис автоматически их загружает к себе в БД и деплоит оттуда артефакты.

Интеграция с Git 

Примечание

Доступно только в enterprise версии.

Интеграция с Git позволяет связать приложение Citeck с Git репозиторием и по нажатию на действие «Зафиксировать изменения в Git» загрузить изменившиеся артефакты в указанный репозиторий.

Настройка 

Открыть журнал «Секреты» v2/journals?journalId=ecos-secrets&viewMode=table&ws=admin$workspace:

и создать пару логин/пароль (Тип - Basic) для доступа к Git репозиторию:

Примечание

Для получения пароля в Gitlab для своей учетной записи можно сгенерировать Personal Access Token с указанием scopes read_repository и write_repository для нужных репозиториев.

При этом на форме создания секрета выбрать тип= Basic, ввести свой логин и вместо своего пароля ввести сгенерированный токен.

Открыть журнал «Конечные точки» v2/journals?journalId=endpoints&viewMode=table&ws=admin$workspace

и добавить ссылку на Git репозиторий:

Примечание

Важно чтобы URL начинался на https (поддержка ssh на данный момент отсутствует).

URL можно получить, открыв страницу с репозиторием и нажав Code. В появившемся окне скопировать HTTPS URL.

Открыть журнал «Приложения ECOS» v2/journals?journalId=ecos-apps&viewMode=table&ws=admin$workspace

и открыть настройки нужного приложения Citeck. В настройках заполнить поле «репозиторий» конечной точкой, которая была создана в п.2.

После этого на карточке настроенного приложения Citeck и на карточках его артефактов появится действие «Зафиксировать изменения в Git» :

Проверка соединения 

По кнопке «Проверить соединение» можно проверить актуальный статус подключения к репозиторию:

Действие «Зафиксировать изменения в Git»

Действие для фиксации изменений доступно на карточке приложения Citeck и на карточках его артефактов если у приложения Citeck настроен Репозиторий.

При нажатии на действие появляется следующая форма:

На форме можно выбрать:

либо существующую ветку:

либо создать новую:

По умолчанию коммиты из Citeck можно делать в ветки, у которых имя начинается на ecos/. Это поведение можно изменить в журнале ECOS конфигураций → ecos-vcs-allowed-branches-to-commit.

При создании новой ветки в качестве базовой можно выбрать либо ветки, имя которых начинается на ecos/, либо стандартные ветки develop, master, main. Это поведение можно изменить в журнале ECOS конфигураций → ecos-vcs-allowed-base-branches.

Если установить галку «Создать ветку», то пользователю будет предложено указать имя новой ветки и ветку, которую нужно взять за основу. Новая ветка всегда имеет префикс ecos/, чтобы исключить случайную порчу артефактов в важных ветках репозитория.

Фиксация в репозитории будет с авторством пользователя, который выполнил действие. При этом фиксация будет выполнена системной учетной записью, которая была настроена для приложения Citeck.

Права на выполнение действия есть только у администраторов Citeck.

Фиксация изменений не удаляет артефакты из репозитория. Фиксируется только добавление новых артефактов и изменение старых.

Структура проекта 

Если в репозитории не обнаружено базовых файлов структуры проекта из maven архетипа ecos application , то они будут добавлены - настройка pom.xml, gitignore, gitattribute, editorconfig.

Настройки конфигурации 

Для настройки конфигурации необходимо открыть журнал «Конфигурация ECOS» v2/journals?journalId=ecos-configs&viewMode=table&ws=admin$workspace:

ecos-vcs-allowed-branches-to-commit — разрешённые ветки для коммита
ecos-vcs-allowed-base-branches — разрешённые базовые ветки