Ant tasks for installation of MobileFirst runtime environments

Reference information for the installmobilefirstruntime, updatemobilefirstruntime, and uninstallmobilefirstruntime Ant tasks.

Task effects

installmobilefirstruntime
The installmobilefirstruntime Ant task configures an application server to run a MobileFirst runtime WAR file as a web application. This task has the following effects.
  • It declares the MobileFirst web application in the specified context root, by default /mfp.
  • It deploys the runtime WAR file on the application server.
  • It declares data sources and on WebSphere® Application Server full profile JDBC providers for the runtime.
  • It deploys the database drivers in the application server.
  • It sets MobileFirst configuration properties through JNDI environment entries.
  • Optionally, it sets the MobileFirst JNDI environment entries to configure the application server as a server farm member for the runtime.
updatemobilefirstruntime

The updatemobilefirstruntime Ant task updates a MobileFirst runtime that is already configured on an application server. This task updates the runtime WAR file. The file must have the same base name as the runtime WAR file that was previously deployed. Other than that, the task does not change the application server configuration, that is, the web application configuration, data sources, and JNDI environment entries.

uninstallmobilefirstruntime
The uninstallmobilefirstruntime Ant task undoes the effects of an earlier installmobilefirstruntime run. This task has the following effects.
  • It removes the configuration of the MobileFirst web application with the specified context root. The task also removes the settings that are added manually to that application.
  • It removes the runtime WAR file from the application server.
  • It removes the data sources and on WebSphere Application Server full profile the JDBC providers for the runtime.
  • It removes the associated JNDI environment entries.

Attributes and elements

The installmobilefirstruntime, updatemobilefirstruntime, and uninstallmobilefirstruntime Ant tasks have the following attributes:

Table 1. Attributes for the installmobilefirstruntime, updatemobilefirstruntime, and uninstallmobilefirstruntime Ant tasks
Attribute Description Required Default
contextroot The common prefix in URLs to the application (context root). No /mfp
id To distinguish different deployments. No Empty
environmentId To distinguish different MobileFirst environments. No Empty
warFile The WAR file for MobileFirst runtime. No The mfp-server.war file is in the same directory as the mfp-ant-deployer.jar file.
wasStartingWeight The start order for WebSphere Application Server. Lower values start first. No 2
contextroot and id

The contextroot and id attributes distinguish different MobileFirst projects.

In WebSphere Application Server Liberty profiles and in Tomcat environments, the contextroot parameter is sufficient for this purpose. In WebSphere Application Server full profile environments, the id attribute is used instead.

environmentId
Use the environmentId attribute to distinguish several environments, consisting each of MobileFirst Server administration service and MobileFirst runtime web applications, that must operate independently. You must set this attribute to the same value for the runtime application as the one that was set in the <installmobilefirstadmin> invocation, for the administration service application.
warFile

Use the warFile attribute to specify a different directory for the MobileFirst runtime WAR file. You can specify the name of this WAR file with an absolute path or a relative path.

wasStartingWeight
Use the wasStartingWeight attribute to specify a value that is used in WebSphere Application Server as a weight to ensure that a start order is respected. As a result of the start order value, the MobileFirst Server administration service web application is deployed and started before any other MobileFirst runtime projects. If MobileFirst projects are deployed or started before the web application, the JMX communication is not established and you cannot manage your MobileFirst projects.

The installmobilefirstruntime, updatemobilefirstruntime, and uninstallmobilefirstruntime tasks support the following elements:

Table 2. Inner elements for the installmobilefirstruntime, updatemobilefirstruntime, and uninstallmobilefirstruntime Ant tasks
Element Description Count
<property> The properties. 0..
<applicationserver> The application server. 1
<database> The databases. 1
<analytics> The Analytics. 0..1
The <property> element specifies a deployment property to be defined in the application server. It has the following attributes:
Table 3. Attributes for the <property> element
Attribute Description Required Default value
name The name of the property. Yes None
value The value for the property. Yes None

The <applicationserver> element describes the application server to which the MobileFirst application is deployed. It is a container for one of the following elements:

Table 4. Inner elements for the <applicationserver> element
Element Description Count
<websphereapplicationserver> or <was> The parameters for WebSphere Application Server. 0..1
<tomcat> The parameters for Apache Tomcat. 0..1

The <websphereapplicationserver> element (or <was> in its short form) denotes a WebSphere Application Server instance. WebSphere Application Server full profile (Base, and Network Deployment) are supported, so is WebSphere Application Server Liberty Core and WebSphere Application Server Liberty Network Deployment. The <websphereapplicationserver> element has the following attributes:

Table 5. Attributes for the <websphereapplicationserver> or <was> element
Attribute Description Required Default
installdir WebSphere Application Server installation directory. Yes None
profile WebSphere Application Server profile, or Liberty. Yes None
user WebSphere Application Server administrator name. Yes, except for Liberty None
password WebSphere Application Server administrator password. No Queried interactively
libertyEncoding The algorithm to encode data source passwords for WebSphere Application Server Liberty. The possible values are none, xor, and aes.

Whether the xor or aes encoding is used, the clear password is passed as argument to the securityUtility program, which is called through an external process. You can see the password with a ps command, or in the /proc file system on UNIX operating systems.

 No xor
jeeVersion For Liberty profile. To specify whether to install the features of the JEE6 web profile or the JEE7 web profile. Possible values are 6, 7, or auto. No auto
configureFarm For WebSphere Application Server Liberty, and WebSphere Application Server full profile (not for WebSphere Application Server Network Deployment edition and Liberty collective). To specify whether the server is a server farm member. Possible values are true or false. No false
farmServerId A string that uniquely identify a server in a server farm.

The MobileFirst Server administration services and all the MobileFirst runtimes that communicate with it must share the same value.

 Yes None

It supports the following element for single-server deployment:

Table 6. Inner element for the <was> element (single-server deployment)
Element Description Count
<server> A single server. 0..1

The <server> element, which is used in this context, has the following attribute:

Table 7. The attribute of <server> element (single-server deployment)
Attribute Description Required Default
name The server name. Yes None
It supports the following elements for Liberty collective:
Table 8. Inner element of the <was> element for Liberty collective
Element Description Count
<collectiveMember> A Liberty collective member. 0..1
The <collectiveMember> element has the following attributes:
Table 9. Attributes of the <collectiveMember> element
Attribute Description Required Default value
serverName The name of the collective member. Yes None
clusterName The cluster name that the collective member belongs to. Yes None
serverId A string that uniquely identifies the collective member. Yes None
controllerHost The name of the collective controller. Yes None
controllerHttpsPort The HTTPS port of the collective controller. Yes None
controllerAdminName The administrative user name that is defined in the collective controller. This is the same user that is used to join new members to the collective. Yes None
controllerAdminPassword The administrative user password. Yes None
createControllerAdmin To indicate whether the administrative user must be created in the basic registry of the collective member. Possible values are true or false. No true
It supports the following elements for Network Deployment:
Table 10. Inner elements for the <was> element (network deployment)
Element Description Count
<cell> The entire cell. 0..1
<cluster> All the servers of a cluster. 0..1
<node> All the servers in a node, clusters excluded. 0..1
<server> A single server. 0..1

The <cell> element has no attributes.

The <cluster> element has the following attribute:

Table 11. Attribute for the <cluster> element (network deployment)
Attribute Description Required Default
name The cluster name. Yes None

The <node> element has the following attribute:

Table 12. Attribute for the <node> element (network deployment)
Attribute Description Required Default
name The node name. Yes None

The <server> element, which is used in a Network Deployment context, has the following attributes:

Table 13. Attributes for the <server> element (network deployment)
Attribute Description Required Default
nodeName The node name. Yes None
serverName The server name. Yes None

The <tomcat> element denotes an Apache Tomcat server. It has the following attribute:

Table 14. Attribute of the <tomcat> element
Attribute Description Required Default
installdir The installation directory of Apache Tomcat. For a Tomcat installation that is split between a CATALINA_HOME directory and a CATALINA_BASE directory, specify the value of the CATALINA_BASE environment variable. Yes None
configureFarm To specify whether the server is a server farm member. Possible values are true or false. No false
farmServerId A string that uniquely identify a server in a server farm.

The MobileFirst Server administration services and all the MobileFirst runtimes that communicate with it must share the same value.

 Yes None

The <database> element specifies what information is necessary to access a particular database. The <database> element is specified like the configuredatabase Ant task, except that it does not have the <dba> and <client> elements. However, it might have <property> elements. The <database> element has the following attributes:

Table 15. Attributes of the <database> element
Attribute Description Required Default
kind The kind of database (MobileFirstRuntime). Yes None
validate To validate whether the database is accessible or not. The possible values are true or false. No true

The <database> element supports the following elements:

Table 16. Inner elements for the <database> element
Element Description Count
<derby> The parameters for Derby. 0..1
<db2> The parameters for DB2®. 0..1
<mysql> The parameters for MySQL. 0..1
<oracle> The parameters for Oracle. 0..1
<driverclasspath> The JDBC driver class path. 0..1
The <analytics> element indicates that you want to connect the MobileFirst runtime to an already installed MobileFirst Analytics console and services. It has the following attributes:
Table 17. Attributes of the <analytics> element
Attribute Description Required Default
install To indicate whether to connect the MobileFirst runtime to MobileFirst Analytics. No false
analyticsURL The URL of MobileFirst Analytics services. Yes None
consoleURL The URL ofMobileFirst Analytics Console. Yes None
username The user name. Yes None
password The password. Yes None
validate To validate whether MobileFirst Analytics Console is accessible or not. No true
tenant The tenant for indexing data that is collected from a MobileFirst runtime. No Internal identifier
install

Use the install attribute to indicate that this MobileFirst runtime must be connected and send events to MobileFirst Analytics. Valid values are true or false.

analyticsURL

Use the analyticsURL attribute to specify the URL that is exposed by MobileFirst Analytics, which receives incoming analytics data.

For example: http://<hostname>:<port>/analytics-service/rest

consoleURL

Use the consoleURL attribute to the URL that is exposed by MobileFirst Analytics, which links to the MobileFirst Analytics console.

For example: http://<hostname>:<port>/analytics/console

username

Use the username attribute to specify the user name that is used if the data entry point for the MobileFirst Analytics is protected with basic authentication.

password

Use the password attribute to specify the password that is used if the data entry point for the MobileFirst Analytics is protected with basic authentication.

validate

Use the validate attribute to validate whether the MobileFirst Analytics Console is accessible or not, and to check the user name authentication with a password. The possible values are true, or false.

tenant

For more information about this attribute, see Configuration properties.

To specify an Apache Derby database

The <derby> element has the following attributes:

Table 18. Attributes of the <derby> element
Attribute Description Required Default
database The database name. No MFPDATA, MFPADM, MFPCFG, MFPPUSH, or APPCNTR, depending on kind.
datadir The directory that contains the databases. Yes None
schema The schema name. No MFPDATA, MFPCFG, MFPADMINISTRATOR, MFPPUSH, or APPCENTER, depending on kind.

The <derby> element supports the following element:

Table 19. Inner element for the <derby> element
Element Description Count
<property> The data source property or JDBC connection property. 0..

For more information about the available properties, see the documentation for Class EmbeddedDataSource40. See also the documentation for Class EmbeddedConnectionPoolDataSource40.

For more information about the available properties for a Liberty server, see the documentation for properties.derby.embedded at Liberty profile: Configuration elements in the server.xml file.

When the mfp-ant-deployer.jar file is used within the installation directory of IBM MobileFirst™ Platform Foundation, a <driverclasspath> element is not necessary.

To specify a DB2 database

The <db2> element has the following attributes:

Table 20. Attributes of the <db2> element
Attribute Description Required Default
database The database name. No MFPDATA, MFPADM, MFPCFG, MFPPUSH, or APPCNTR, depending on kind.
server The host name of the database server. Yes None
port The port on the database server. No 50000
user The user name for accessing databases. This user does not need extended privileges on the databases. If you implement restrictions on the database, you can set a user with the restricted privileges that are listed in Database users and privileges. Yes None
password The password for accessing databases. No Queried interactively
schema The schema name. No Depends on the user

For more information about DB2 user accounts, see DB2 security model overview.

The <db2> element supports the following element:

Table 21. Inner element for the <db2> element
Element Description Count
<property> The data source property or JDBC connection property. 0..

For more information about the available properties, see Properties for the IBM® Data Server Driver for JDBC and SQLJ.

For more information about the available properties for a Liberty server, see the properties.db2.jcc section at Liberty profile: Configuration elements in the server.xml file.

The <driverclasspath> element must contain JAR files for the DB2 JDBC driver and the associated license. You can download DB2 JDBC drivers from DB2 JDBC Driver Versions.

To specify a MySQL database

The <mysql> element has the following attributes:

Table 22. Attributes of the <mysql> element
Attribute Description Required Default
database The database name. No MFPDATA, MFPADM, MFPCFG, MFPPUSH, or APPCNTR, depending on kind.
server The host name of the database server. Yes None
port The port on the database server. No 3306
user The user name for accessing databases. This user does not need extended privileges on the databases. If you implement restrictions on the database, you can set a user with the restricted privileges that are listed in Database users and privileges. Yes None
password The password for accessing databases. No Queried interactively

Instead of database, server, and port, you can also specify a URL. In this case, use the following attributes:

Table 23. Alternative attributes for the <mysql> element
Attribute Description Required Default
url The URL for connection to the database. Yes None
user The user name for accessing databases. This user does not need extended privileges on the databases. If you implement restrictions on the database, you can set a user with the restricted privileges that are listed in Database users and privileges. Yes None
password The password for accessing databases. No Queried interactively

For more information about MySQL user accounts, see MySQL User Account Management.

The <mysql> element supports the following element:

Table 24. Inner element for the <mysql> element
Element Description Count
<property> The data source property or JDBC connection property. 0..

For more information about the available properties, see the documentation at Driver/Datasource Class Names, URL Syntax and Configuration Properties for Connector/J.

For more information about the available properties for a Liberty server, see the properties section at Liberty profile: Configuration elements in the server.xml file.

The <driverclasspath> element must contain a MySQL Connector/J JAR file. You can download it from Download Connector/J.

To specify an Oracle database

The <oracle> element has the following attributes:

Table 25. Attributes of the <oracle> element
Attribute Description Required Default
database The database name, or Oracle service name.
Note: You must always use a service name to connect to a PDB database.
 No ORCL
server The host name of the database server. Yes None
port The port on the database server. No 1521
user The user name for accessing databases. This user does not need extended privileges on the databases. If you implement restrictions on the database, you can set a user with the restricted privileges that are listed in Database users and privileges.

See the note under this table.

 Yes None
password The password for accessing databases. No Queried interactively
Note: For the user attribute, use preferably a user name in uppercase letters. Oracle user names are generally in uppercase letters. Unlike other database tools, the installmobilefirstruntime Ant task does not convert lowercase letters to uppercase letters in the user name. If the installmobilefirstruntime Ant task fails to connect to your database, try to enter the value for the user attribute in uppercase letters.

Instead of database, server, and port, you can also specify a URL. In this case, use the following attributes:

Table 26. Alternative attributes of the <oracle> element
Attribute Description Required Default
url The URL for connection to the database. Yes None
user The user name for accessing databases. This user does not need extended privileges on the databases. If you implement restrictions on the database, you can set a user with the restricted privileges that are listed in Database users and privileges.

See the note under this table.

 Yes None
password The password for accessing databases. No Queried interactively
Note: For the user attribute, use preferably a user name in uppercase letters. Oracle user names are generally in uppercase letters. Unlike other database tools, the installmobilefirstruntime Ant task does not convert lowercase letters to uppercase letters in the user name. If the installmobilefirstruntime Ant task fails to connect to your database, try to enter the value for the user attribute in uppercase letters.

For more information about Oracle user accounts, see Overview of Authentication Methods.

For more information about Oracle database connection URLs, see the Database URLs and Database Specifiers section at Data Sources and URLs.

It supports the following element:

Table 27. Inner element for the <oracle> element
Element Description Count
<property> The data source property or JDBC connection property. 0..

For more information about the available properties, see the Data Sources and URLs section at Data Sources and URLs.

For more information about the available properties for a Liberty server, see the properties.oracle section at Liberty profile: Configuration elements in the server.xml file.

The <driverclasspath> element must contain an Oracle JDBC driver JAR file. You can download Oracle JDBC drivers from JDBC, SQLJ, Oracle JPublisher and Universal Connection Pool (UCP).

The <property> element, which can be used inside <derby>, <db2>, <mysql>, or <oracle> elements, has the following attributes:

Table 28. Attributes for the <property> element in a database-specific element
Attribute Description Required Default
name The name of the property. Yes None
type Java™ type of the property values, usually java.lang.String/Integer/Boolean. No java.lang.String
value The value for the property. Yes None
Parent topic: Installation reference