Работа в изолированной сети

В данном разделе описана организация разработки приложений на фреймворке Jmix в изолированной от интернет сети, то есть без доступа к публичным репозиториям артефактов и другим сервисам.

В качестве примера приводится настройка одного изолированного компьютера под управлением Linux. Для работы команды из нескольких человек достаточно будет перенести созданный репозиторий на общедоступный в изолированной сети сервер.

Загрузка программного обеспечения

Загрузите и перенесите на изолированный компьютер следующее ПО:

  1. Sonatype Nexus OSS версии 3.x: https://help.sonatype.com/repomanager3/product-information/download/download-archives---repository-manager-3

  2. JDK 8 (необходим для запуска Nexus) и JDK 17 (необходим для разработки приложений): https://adoptium.net/temurin/releases

  3. Утилиту Jmix Dependencies Tool: https://github.com/jmix-framework/jmix-dependencies-tool/releases

    Jmix Dependencies Tool (deptool) - это утилита командной строки, позволяющая подготовить собственный репозиторий артефактов для разработки проектов на основе Jmix.

    Утилита deptool предоставляет следующие возможности:

    • Вычисляет и загружает артефакты зависимостей, необходимые для запуска Jmix, в кэш Gradle.

    • Вычисляет и загружает артефакты, используемые любой отдельной библиотекой.

    • Экспортирует загруженные артефакты в формате репозитория Maven.

    • Вычисляет npm-зависимости в виде package-lock.json.

    • Экспортирует npn-зависимости в виде tgz-архивов.

    • Импортирует артефакты в собственный Nexus.

    Полная документация по утилите находится в файле README.

  4. Gradle соответствующей версии: https://gradle.org/releases

    Версия Jmix Версия Gradle

    1.4.4

    7.5.1

    1.5.0

    7.6

    2.1

    8.2

    2.2

    8.6

  5. Node.js: https://nodejs.org/en/download

  6. IntelliJ IDEA Community Edition: https://www.jetbrains.com/idea/download

  7. Jmix Studio (плагин Jmix для IDE): https://plugins.jetbrains.com/plugin/14340-jmix/versions

    Выберите наиболее свежую версию, соответствующую версии IDE. Например, если IDE версии 2023.3, то версия плагина оканчивается на -233

Распакуйте все архивы, кроме плагина Jmix, в следующую файловую структуру:

~/work/
├── deptool-2.0.0
├── gradle-8.6
├── idea-IC-233
├── jdk-17.0.9
├── jdk8u362
├── nexus
└── node

Архив Java зависимостей

На изолированный компьютер необходимо перенести архив с артефактами Jmix и его зависимостей (используемых библиотек).

Если вы планируете использовать только фреймворк и бесплатные дополнения, то можете загрузить заранее подготовленный архив зависимостей со страницы https://www.jmix.ru/resources/jmix-dependencies.

Если же вам нужны коммерческие дополнения и у вас есть Enterprise подписка, то необходимо подготовить архив зависимостей самостоятельно с помощью утилиты Jmix Dependencies Tool (deptool). Выполните следующие шаги:

  1. Установите на компьютер с доступом в интернет утилиту deptool, скачав архив со страницы https://github.com/jmix-framework/jmix-dependencies-tool/releases.

  2. Откройте терминал, перейдите в подкаталог bin утилиты и запустите команду:

    ./deptool resolve-jmix \
  --jmix-version 2.1.1 \
  --jmix-plugin-version 2.1.1 \
  --resolve-commercial-addons \
  --jmix-license-key 123456123456-abcdefabcdef

    где:

    • --jmix-version - версия фреймворка

    • --jmix-plugin-version - версия плагина Gradle, если она отличается от версии фреймворка

    • --resolve-commercial-addons - флаг для загрузки всех коммерческих дополнений и их зависимостей

    • --jmix-license-key - ключ вашей Enterprise-подписки

    После завершения работы команды в подкаталоге gradle-home утилиты будет сформирован локальный кэш артефактов в формате Gradle.

  3. Запустите команду экспорта артефактов:

    ./deptool export

    В подкаталоге export утилиты будут собраны артефакты в переносимом формате репозитория Maven. Заархивируйте данный каталог для переноса в изолированную сеть.

Перенесите содержимое архива зависимостей (загруженного либо сформированного с помощью deptool) на изолированный компьютер и распакуйте в каталог ~/work/dependencies.

Архив npm зависимостей

Для Jmix версии 2.x+ на изолированный компьютер также нужно перенести архив с npm зависимостями, необходимыми для работы фронтенда.

Вы можете скачать заранее подготовленный архив со всеми зависимостями со страницы https://www.jmix.ru/resources/jmix-dependencies.

Либо вы можете собрать их самостоятельно, используя утилиту deptool:

  1. Откройте терминал, перейдите в подкаталог bin утилиты и запустите команду:

    ./deptool resolve-npm \
  --jmix-version 2.1.1 \
  --jmix-plugin-version 2.1.1 \
  --resolve-commercial-addons \
  --jmix-license-key 123456123456-abcdefabcdef

    где:

    • --jmix-version - версия фреймворка

    • --jmix-plugin-version - версия плагина Gradle, если она отличается от версии фреймворка

    • --resolve-commercial-addons - флаг для загрузки всех npm зависимостей для коммерческих дополнений

    • --jmix-license-key - ключ вашей Enterprise-подписки

    После завершения работы команды в подкаталоге npm-resolver утилиты будет сформирован файл package-lock.json с перечнем зависимостей.

  2. Запустите команду экспорта npm артефактов:

    ./deptool export-npm

    В подкаталоге export-npm утилиты будут собраны артефакты в виде tgz-архивов, разложенных по директориям, а также файл package-lock.json (он потребуется для запуска проекта). Заархивируйте данный каталог для переноса в изолированную сеть.

Перенесите содержимое архива npm зависимостей (загруженного либо сформированного с помощью deptool) на изолированный компьютер и распакуйте в каталог ~/work/dependencies-npm.

Настройка переменных окружения

Откройте в текстовом редакторе файл ~/.bashrc и внесите в конец файла следующие строки:

export INSTALL4J_JAVA_HOME=/home/$USER/work/jdk8u362
export JAVA_HOME=/home/$USER/work/jdk-17.0.9

PATH=$PATH:$JAVA_HOME/bin
PATH=$PATH:/home/$USER/work/gradle-8.6/bin
PATH=$PATH:/home/$USER/work/node/bin

Переменная INSTALL4J_JAVA_HOME, указывающая на каталог установки JDK 8, необходима для работы Nexus.

Переменная JAVA_HOME, а также переменная PATH, включающая каталоги запуска Java, Gradle и Node.js, необходимы для запуска deptool и разработки приложений.

Настройка локального Nexus

  • Откройте терминал и перейдите в подкаталог ~/work/nexus/nexus-<version>/bin и выполните:

    ./nexus run

  • Откройте в браузере страницу http://localhost:8081.

  • Нажмите Sign in в правом верхнем углу.

  • Войдите пользователем admin с паролем, находящимся в файле ~/work/nexus/sonatype-work/nexus3/admin.password.

  • Смените пароль на adminpass.

  • На шаге Configure Anonymous Access разрешите анонимный доступ к репозиторию - это упростит конфигурацию проектов.

Создание репозитория Jmix

Далее необходимо сконфигурировать репозиторий для хранения артефактов зависимостей Jmix.

  • Перейдите в раздел администрирования и откройте меню Repositories.

    nexus repository

  • Нажмите на кнопку Create repository.

  • Выберите тип maven2 hosted.

  • Введите jmix в поле Name, выберите Mixed в поле Version policy и нажмите на кнопку Create repository:

    nexus repository create

Будет создан новый пустой репозиторий артефактов, доступный по адресу http://localhost:8081/repository/jmix.

Для хранения npm зависимостей также нужно создать npm репозиторий. Создается он аналогичным образом.

  • Перейдите в раздел администрирования и откройте меню Repositories.

  • Нажмите на кнопку Create repository.

  • Выберите тип npm hosted.

  • Введите jmix-npm в поле Name и нажмите на кнопку Create repository:

Будет создан новый пустой npm репозиторий по адресу http://localhost:8081/repository/jmix-npm

Импорт зависимостей в Nexus

Импорт артефактов зависимостей в репозиторий Nexus осуществляется командой upload утилиты deptool:

Откройте терминал, перейдите в каталог ~/work/deptool-2.0.0/bin и запустите команду:

./deptool upload --nexus-url http://localhost:8081 \ (1)
--nexus-repository jmix \ (2)
--nexus-username admin \ (3)
--nexus-password adminpass \ (4)
--artifacts-dir ../../dependencies (5)
1 Адрес менеджера репозиториев Nexus.
2 Название репозитория.
3 Логин администратора Nexus.
4 Пароль администратора Nexus.
5 Каталог с артефактами, которые будут загружены в Nexus. Укажите каталог с распакованным архивом зависимостей.

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

Импорт npm зависимостей в Nexus

Импорт npm зависимостей осуществляется командой upload-npm утилиты deptool

Откройте терминал, перейдите в каталог ~/work/deptool-2.0.0/bin и запустите команду:

./deptool upload-npm --nexus-url http://localhost:8081 \ (1)
--nexus-repository jmix-npm \ (2)
--nexus-username admin \ (3)
--nexus-password adminpass \ (4)
--artifacts-dir ../../dependencies-npm (5)
1 Адрес менеджера репозиториев Nexus.
2 Название репозитория.
3 Логин администратора Nexus.
4 Пароль администратора Nexus.
5 Каталог с npm артефактами, которые будут загружены в Nexus. Укажите каталог с распакованным архивом npm зависимостей.

В результате выполнения данной операции репозиторий jmix-npm локального Nexus будет заполнен необходимыми артефактами.

Настройка IDE

Откройте терминал, перейдите в каталог ~/work/idea-IC-233/bin и запустите команду:

./idea.sh

В окне Welcome to IntelliJ IDEA перейдите на вкладку Plugins, нажмите на иконку шестеренки и выберите Install Plugin from Disk. Выберите ZIP-файл загруженного плагина Jmix. После установки плагина перезапустите IDE.

Для работы плагина Jmix требуется наличие файла sif.dat в конфигурационном каталоге IDE. При работе онлайн он создается автоматически при активации Jmix Studio. В изолированной сети его необходимо перенести вручную в каталог ~/.config/JetBrains/IdeaIC2023.3 (соответствует версии вашей IntelliJ IDEA, см. подробнее в документации IntelliJ). Данный файл можно либо скопировать с компьютера с уже активированной Jmix Studio, либо получить по email, направив запрос по адресу info@jmix.io.

Создание проекта Jmix

  • Запустите IntelliJ IDEA с установленным плагином Jmix.

  • Создайте новый Jmix проект с пользовательской конфигурацией репозиториев, в которой укажите адрес локального репозитория http://localhost:8081/repository/jmix:

    new project custom conf
    new project repo

    В поле Jmix version вы увидите список доступных версий Jmix, определяемый версиями имеющихся в репозитории артефактов io.jmix.templates.studio:jmix-studio-templates.

  • После создания проекта вы увидите сообщение об ошибке синхронизации Gradle: Unknown host 'services.gradle.org'. Нажмите на иконку гаечного ключа в панели Gradle в правой части IDE и выберите пункт Gradle Settings. В появившемся окне настроек Gradle выберите Local installation в поле Distribution и введите путь к установленному на компьютере Gradle:

    gradle location

  • После сохранения настроек Gradle начнется импорт проекта и завершится с ошибкой вида org.gradle.api.plugins.UnknownPluginException: Plugin [id: 'io.jmix', version: '2.1.1'] was not found …​

  • Откройте на редактирование файл settings.gradle и добавьте следующие строки в его начало:

    pluginManagement {
    resolutionStrategy {
        eachPlugin {
            if (requested.id.id == 'io.jmix') {
                useModule("io.jmix.gradle:jmix-gradle-plugin:${requested.version}")
            }
        }
    }
    repositories {
        maven {
            allowInsecureProtocol true (1)
            url 'http://localhost:8081/repository/jmix' (2)
        }
    }
}
    1 Инструкция allowInsecureProtocol true требуется, если ваш репозиторий Nexus использует протокол HTTP.
    2 URL локального репозитория Nexus.

  • Откройте также файл build.gradle и отредактируйте секцию repositories, добавив инструкцию allowInsecureProtocol true и удалив mavenCentral():

    repositories {
    maven {
        allowInsecureProtocol true
        url 'http://localhost:8081/repository/jmix'
    }
}

  • Для доступа к npm зависимостям:

    • Создайте в корне проекта файл .npmrc и добавьте в него следующую строку:

      registry=http://127.0.0.1:8081/repository/jmix-npm/

      Не используйте localhost для имени хоста - это может вызвать ошибку загрузки некоторых зависимостей.

    • Из архива с npm зависимостями скопируйте в корень проекта файл package-lock.json.

    • В application.properties проекта измените значение свойства vaadin.pnpm.enable на false.

  • В панели Gradle нажмите Reload All Gradle Projects, чтобы снова запустить импорт проекта.

  • После успешной загрузки артефактов и индексирования проекта вы увидите панель Jmix со структурой проекта в левой части IDE.

    Если панели Jmix нет или отображается окно Jmix Sign In, то проверьте что вы активировали Jmix Studio как описано в разделе Настройка IDE.