4.3.4.3. buildWar

buildWar – the task of the CubaWarBuilding type, which builds a WAR file from the application code and its dependencies. It should be declared in the root of build.gradle. The resulting WAR file(s) are located in the build/distributions project subdirectory.

The task can be configured using the Deployment > WAR Settings page in Studio.

Any CUBA application consists of at least two blocks: Middleware and Web Client. So the most natural way to deploy an application is to create two separate WAR files: one for Middleware and one for Web Client. This also allows you to scale your application when the number of users grows. However, separate WAR files contain some duplicated dependencies that increase overall size. Besides, extended deployment options are often not needed and rather complicate the process. The CubaWarBuilding task can create both types of WAR files: one per block or single WAR containing both blocks. In the latter case, the application blocks are loaded into separate class loaders inside one web application.

Creating separate WAR files for Middleware and Web Client

To create separate WAR files for Middleware and Web Client, use the following task configuration:

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

Task parameters:

  • appName - the name of the web application. By default, it corresponds to the Modules prefix, e.g. app.

  • appProperties - an optional map defining application properties. These properties will be added to the /WEB-INF/local.app.properties files inside generated WAR.

    appProperties = ['cuba.automaticDatabaseUpdate': 'true'] will create the database at the first launch, if there wasn’t any.

  • singleWar - should be set to false for building separate WAR files.

  • includeJdbcDriver - include JDBC driver which is currently used in the project. false by default.

  • includeContextXml - include Tomcat context.xml file which is currently used in the project. false by default.

  • coreContextXmlPath - the relative path to a file which should be used instead of project’s context.xml if includeContextXml is set to true.

  • hsqlInProcess - if set to true, the database URL in context.xml will be modified for HSQL in-process mode.

  • coreProject - the Gradle project representing the core module (Middleware). If not defined, the standard core module is used.

  • webProject - the Gradle project representing the web module (Web Client). If not defined, the standard web module is used.

  • portalProject - the Gradle project representing the portal module (Web Portal). Set this property if the application project contains the portal module. For example, portalProject = project(':app-portal').

  • coreWebXmlPath, webWebXmlPath, portalWebXmlPath - a relative path to a file to be used as a web.xml of the corresponding application block.

    Example of using custom web.xml files:

    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 - defines a relative path to a file to be used for logging configuration.

    For example:

    task buildWar(type: CubaWarBuilding) {
    // ...
    logbackConfigurationFile = 'etc/war-logback.xml'
}

  • useDefaultLogbackConfiguration - while true (default value), the task will copy its own standard logback.xml configuration file.

  • frontBuildDir - the name of the directory where the Front UI is built. It is build by default. Set this parameter if you have custom build directory.

Creating a single WAR file

To create a single WAR file that comprises both Middleware and Web Client blocks, use the following task configuration:

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

The following parameters should be specified in addition to the ones described above:

  • singleWar - should be omitted or set to true.

  • webXmlPath - the relative path to a file to be used as a web.xml of the single WAR. This file defines two servlet context listeners that load the application blocks: SingleAppCoreServletListener and SingleAppWebServletListener. All initialization parameters are passed to them through context parameters.

    Example of 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>

All filters and servlets for single WAR deployment should be registered programmatically, see Registration of Servlets and Filters.

Single WAR contains only core and web modules (Middleware and Web Client). To deploy the portal module, use separate WAR files.

If the application project contains the front module, it becomes accessible at /<appName>/front path. In order for the frontend interface to work correctly in the single WAR, you should change the environment variable PUBLIC_URL= /app/front/ during build (for example, in the .env.production.local (see README)).

See also WAR deployment to Jetty section for step-by-step instructions on some variants of WAR deployment.