For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.
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. We 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 we 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. We 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 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 we 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, we 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. We 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, we 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, we 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, we 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. We 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, we 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 our database, try to enter the value for the user attribute in uppercase letters.
Instead of database, server, and port, we 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, we 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 our 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. We 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