6.3.3.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.

Tip

The task can be configured using the Deployment settings > WAR page in Studio. See its context help for details.

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) {
    appHome = '${app.home}'
    appProperties = ['cuba.automaticDatabaseUpdate': 'true']
    singleWar = false
}

Task parameters:

  • appHome – the path to the application home directory. You can specify an absolute or relative path to the home directory, or a placeholder for Java system variable which should be set at server start.

  • 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'
}
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) {
    appHome = '${app.home}'
    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
        </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
        </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>

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

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