4.3.4.3. buildWar

buildWar - задача типа CubaWarBuilding, выполняющая сборку приложения и его зависимостей в WAR-файл. Должна быть объявлена в корне скрипта build.gradle. Собранные WAR-файлы находятся в подкаталоге build/distributions проекта.

Эту задачу можно настроить на странице Deployment > WAR Settings в Studio.

Любое CUBA-приложение состоит как минимум из двух блоков: Middleware и Web Client. Поэтому наиболее естественный способ развертывания приложения это создание двух файлов WAR: один для Middleware, второй для Web Client. Это также позволяет масштабировать приложение при увеличении нагрузки. Однако раздельные WAR-файлы содержат дублированные зависимости, что увеличивает их общий размер. Кроме того, часто расширенные возможности развертывания не нужны и только усложняют процесс. Задача CubaWarBuilding может создавать WAR-файлы обоих типов: один файл на блок или единственный WAR, содержащий оба блока. В последнем случае блоки приложения загружаются в раздельные class loaders внутри одного веб-приложения.

Создание раздельных WAR-файлов для Middleware и Web Client

Для создания двух отдельных WAR-файлов для Middleware и Web Client используйте следующую конфигурацию:

task buildWar(type: CubaWarBuilding) {
    appProperties = ['cuba.automaticDatabaseUpdate': 'true']
    singleWar = false
}

Параметры задачи:

  • appName - имя приложения. По умолчанию совпадает с Modules prefix, например, app.

  • appProperties - опциональный мэп свойств приложения. Эти свойства будут добавлены в файлы /WEB-INF/local.app.properties внутри создаваемых WAR.

  • singleWar - должен быть установлен в false для создания раздельных WAR-файлов.

  • includeJdbcDriver - включить JDBC драйвер, который используется в проекте. По умолчанию false.

  • includeContextXml - включить файл context.xml, который используется в проекте. По умолчанию false.

  • coreContextXmlPath - относительный путь к файлу, который должен быть использован вместо проектного context.xml если параметр includeContextXml установлен в true.

  • hsqlInProcess - если установлен в true, то URL подключения к БД в context.xml будет изменен на подключение к HSQL в режиме in-process.

  • coreProject - проект Gradle, представляющий модуль core (Middleware). Если не установлено, используется стандартный модуль core проекта.

  • webProject - проект Gradle, представляющий модуль web (Web Client). Если не установлено, используется стандартный модуль web проекта.

  • portalProject - проект Gradle, представляющий модуль portal (Web Portal). Установите данное свойство, если в проекте используется модуль portal. Например, portalProject = project(':app-portal').

  • coreWebXmlPath, webWebXmlPath, portalWebXmlPath - относительный путь к файлу, который будет использован в качестве web.xml соответствующего блока приложения.

    Пример использования собственных web.xml:

    task buildWar(type: CubaWarBuilding) {
        singleWar = false
        // ...
        coreWebXmlPath = 'modules/core/web/WEB-INF/production-web.xml'
        webWebXmlPath = 'modules/web/web/WEB-INF/production-web.xml'
    }
  • logbackConfigurationFile - задает относительный путь к файлу, в котором содержится конфигурация логирования.

    Например:

    task buildWar(type: CubaWarBuilding) {
        // ...
        logbackConfigurationFile = 'etc/war-logback.xml'
    }
  • useDefaultLogbackConfiguration - пока установлено значение true (по умолчанию), задача будет копировать конфигурацию из её собственного стандартного файла logback.xml.

  • frontBuildDir - имя каталога, в который собирается собирается фронтенд интерфейс. По умолчанию build. Установите данный параметр, если сборка происходит в другой каталог.

Создание единого WAR-файла

Для создания единого файла WAR, включающего в себя блоки Middleware и Web Client, используйте следующую конфигурацию:

task buildWar(type: CubaWarBuilding) {
    webXmlPath = 'modules/web/web/WEB-INF/single-war-web.xml'
}

Следующие параметры должны быть указаны в дополнение к описанным выше:

  • singleWar - должен быть опущен или установлен в true.

  • webXmlPath - относительный путь к файлу, который будет использован в качестве web.xml единого WAR. Этот файл задает два servlet context listeners, которые загружают блоки приложения: SingleAppCoreServletListener и SingleAppWebServletListener. Все параметры инициализации передаются через параметры контекста.

    Пример файла single-war-web.xml:

    <?xml version="1.0" encoding="UTF-8"?>
    <web-app xmlns="http://java.sun.com/xml/ns/javaee"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
             version="3.0">
    
        <!--Application components-->
        <context-param>
            <param-name>appComponents</param-name>
            <param-value>com.haulmont.cuba</param-value>
        </context-param>
    
        <!-- Web Client parameters -->
    
        <context-param>
            <description>List of app properties files for Web Client</description>
            <param-name>appPropertiesConfigWeb</param-name>
            <param-value>
                classpath:com/company/sample/web-app.properties
                /WEB-INF/local.app.properties
                file:${app.home}/local.app.properties
            </param-value>
        </context-param>
    
        <context-param>
            <description>Web resources version for correct caching in browser</description>
            <param-name>webResourcesTs</param-name>
            <param-value>${webResourcesTs}</param-value>
        </context-param>
    
        <!-- Middleware parameters -->
    
        <context-param>
            <description>List of app properties files for Middleware</description>
            <param-name>appPropertiesConfigCore</param-name>
            <param-value>
                classpath:com/company/sample/app.properties
                /WEB-INF/local.app.properties
                file:${app.home}/local.app.properties
            </param-value>
        </context-param>
    
        <!-- Servlet context listeners that load the application blocks -->
    
        <listener>
            <listener-class>
                com.vaadin.server.communication.JSR356WebsocketInitializer
            </listener-class>
        </listener>
        <listener>
            <listener-class>
                com.haulmont.cuba.core.sys.singleapp.SingleAppCoreServletListener
            </listener-class>
        </listener>
        <listener>
            <listener-class>
                com.haulmont.cuba.web.sys.singleapp.SingleAppWebServletListener
            </listener-class>
        </listener>
    </web-app>

Все фильтры и сервлеты при развёртывании в единый WAR-файл необходимо программно зарегистрировать, см. Регистрация сервлетов и фильтров.

Единый WAR файл содержит только модули core и web (Middleware и Web Client). Для развертывания модуля portal используйте раздельные WAR-файлы.

При использовании в проекте модуля front при развёртывании он должен быть доступен по пути /<appName>/front. Для того чтобы фронтенд-интерфейс корректно работал в singleWar, необходимо поменять переменную среды PUBLIC_URL=/app/front/ при сборке (например, в .env.production.local (см. README)).

В разделе Развертывание WAR в Jetty содержатся пошаговые инструкции по некоторым вариантам развертывания WAR-файлов.