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:
-
appName
- the name of the web application. By default, it corresponds to the Modules prefix, e.g.app
. -
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 tofalse
for building separate WAR files. -
includeJdbcDriver
- include JDBC driver which is currently used in the project.false
by default. -
includeContextXml
- include Tomcatcontext.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’scontext.xml
ifincludeContextXml
is set totrue
. -
hsqlInProcess
- if set totrue
, the database URL incontext.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 aweb.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:
logbackConfigurationFile = "/modules/global/src/logback.xml"
-
useDefaultLogbackConfiguration
- whiletrue
(default value), the task will copy its own standardlogback.xml
configuration file. -
polymerBuildDir
- the name of the directory where the Polymer UI is built. It ises6-unbundled
by default. Set this parameter if you have changed the build preset inpolymer.json
.
-
- 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 totrue
. -
webXmlPath
- the relative path to a file to be used as aweb.xml
of the single WAR. This file defines two servlet context listeners that load the application blocks:SingleAppCoreServletListener
andSingleAppWebServletListener
. 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>
All filters and servlets for single WAR deployment should be registered programmatically, see Registration of Servlets for single WAR deployment.
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.