Ant tasks for installation of MobileFirst Operations Console, MobileFirst Server artifacts, MobileFirst Server administration, and live update services

For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.

Ant tasks for installation of MobileFirst Operations Console, MobileFirst Server artifacts, MobileFirst Server administration, and live update services

The installmobilefirstadmin, updatemobilefirstadmin, and uninstallmobilefirstadmin Ant tasks are provided for the installation of MobileFirst Operations Console, the artifacts component, the administration service, and the live update service.

Task effects
installmobilefirstadmin
The installmobilefirstadmin Ant task configures an application server to run the WAR files of the administration and live update services as web applications, and optionally, to install the MobileFirst Operations Console. This task has the following effects:
It declares the administration service web application in the specified context root, by default /mfpadmin.
It declares the live update service web application in a context root derived from the specified context root of the administration service. By default, /mfpadminconfig.
For the relational databases, it declares data sources and on WebSphere® Application Server full profile, JDBC providers for the administration services.
It deploys the administration service and the live update service on the application server.
Optionally, it declaresMobileFirst Operations Console as a web application in the specified context root, by default /mfpconsole. If the MobileFirst Operations Console instance is specified, the Ant task declares the appropriate JNDI environment entry to communicate with the corresponding management service. For example,
<target name="adminstall">
  <installmobilefirstadmin servicewar="${mfp.service.war.file}">
    <console install="${mfp.admin.console.install}" warFile="${mfp.console.war.file}"/>
Optionally, it declares the MobileFirst Server artifacts web application in the specified context root /mfp-dev-artifacts when MobileFirst Operations Console is installed.
It configures the configuration properties for the administration service by using JNDI environment entries. These JNDI environment entries also give some additional information about the application server topology, for example whether the topology is a stand-alone configuration, a cluster, or a server farm.
Optionally, it configures users that it maps to roles used by MobileFirst Operations Console, and the administration and live update services web applications.
It configures the application server for use of JMX.
Optionally, it configures the communication with the MobileFirst Server push service.
Optionally, it sets the MobileFirst JNDI environment entries to configure the application server as a server farm member for the MobileFirst Server administration part.
updatemobilefirstadmin

The updatemobilefirstadmin Ant task updates an already-configured MobileFirst Server web application on an application server. This task has the following effects:
It updates the administration service WAR file. This file must have the same base name as the corresponding WAR file that was previously deployed.
It updates the live update service WAR file. This file must have the same base name as the corresponding WAR file that was previously deployed.
It updates the MobileFirst Operations Console WAR file. This file must have the same base name as the corresponding WAR file that was previously deployed.
The task does not change the application server configuration, that is, the web application configuration, data sources, JNDI environment entries, user-to-role mappings, and JMX configuration.

uninstallmobilefirstadmin

The uninstallmobilefirstadmin Ant task undoes the effects of an earlier run of installmobilefirstadmin. This task has the following effects:
It removes the configuration of the administration service web application with the specified context root. As a consequence, the task also removes the settings that were added manually to that application.
It removes the WAR files of the administration and live update services, and MobileFirst Operations Console from the application server as an option.
For the relational DBMS, it removes the data sources and on WebSphere Application Server Full Profile the JDBC providers for the administration and live update services.
For the relational DBMS, it removes the database drivers that were used by the administration and live update services from the application server.
It removes the associated JNDI environment entries.
On WebSphere Application Server Liberty and Apache Tomcat, it removes the users configured by the installmobilefirstadmin invocation.
It removes the JMX configuration.
Attributes and elements

The installmobilefirstadmin, updatemobilefirstadmin, and uninstallmobilefirstadmin Ant tasks have the following attributes:
Table 1. Attributes for the installmobilefirstadmin, updatemobilefirstadmin, and uninstallmobilefirstadmin Ant tasks
Attribute Description Required Default
contextroot The common prefix for URLs to the administration service to get information about MobileFirst runtime environments, applications, and adapters. No /mfpadmin
id To distinguish different deployments. No Empty
environmentId To distinguish different MobileFirst environments. No Empty
servicewar The WAR file for the administration service. No The mfp-admin-service.war file is in the same directory as the mfp-ant-deployer.jar file.
shortcutsDir The directory where to place shortcuts. No None
wasStartingWeight The start order for WebSphere Application Server. Lower values start first. No 1

contextroot and id

The contextroot and id attributes distinguish different deployments of MobileFirst Operations Console and the administration service.
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. Without this id attribute, two WAR files with the same context roots might conflict and these files would not be deployed.

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. For example, with this option we can host a test environment, a pre-production environment, and a production environment on the same server or in the same WebSphere Application Server Network Deployment cell. This environmentId attribute creates a suffix that is added to MBean names that the administration service and the MobileFirst runtime projects use when they communicate through Java™ Management Extensions (JMX).

servicewar

Use the servicewar attribute to specify a different directory for the administration service WAR file. We can specify the name of this WAR file with an absolute path or a relative path.

shortcutsDir

The shortcutsDir attribute specifies where to place shortcuts to the MobileFirst Operations Console. If you set this attribute, we can add the following files to that directory:
mobilefirst-console.url - this file is a Windows shortcut. It opens the MobileFirst Operations Console in a browser.
mobilefirst-console.sh- this file is a UNIX shell script and opens the MobileFirst Operations Console in a browser.
mobilefirst-admin-service.url - this file is a Windows shortcut. It opens in a browser and calls a REST service that returns a list of the MobileFirst projects that can be managed in JSON format. For each listed MobileFirst project, some details are also available about their artifacts, such as the number of applications, the number of adapters, the number of active devices, the number of decommissioned devices. The list also indicates whether the MobileFirst project runtime is running or idle.
mobilefirst-admin-service.sh - this file is a UNIX shell script that provides the same output as the mobilefirst-admin-service.url file.

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 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 the runtime cannot synchronize with the administration service database and cannot handle server requests.

The installmobilefirstadmin, updatemobilefirstadmin, and uninstallmobilefirstadmin Ant tasks support the following elements:
Table 2. Inner elements for the installmobilefirstadmin, updatemobilefirstadmin, and uninstallmobilefirstadmin Ant tasks
Element Description Count
<applicationserver> The application server. 1
<configuration> The live update service. 1
<console> The administration console. 0..1
<database> The databases. 1
<jmx> To enable Java Management Extensions. 1
<property> The properties. 0..
<push> The push service. 0..1
<user> The user to be mapped to a security role. 0..

To specify a MobileFirst Operations Console

The <console> element collects information to customize the installation of the MobileFirst Operations Console. This element has the following attributes:
Table 3. Attributes of the <console> element
Attribute Description Required Default
contextroot The URI of the MobileFirst Operations Console. No /mfpconsole
install To indicate whether the MobileFirst Operations Console must be installed. No Yes
warfile The console WAR file. No The mfp-admin-ui.war file is in the same directory as themfp-ant-deployer.jar file.

The <console> element supports the following element:
Table 4. Inner element for the <console> element
Element Description Count
<artifacts> The MobileFirst Server artifacts. 0..1
<property> The properties. 0..

The <artifacts> element has the following attributes:
Table 5. Attributes for the <artifacts> element
Attribute Description Required Default value
install To indicate whether the artifacts component must be installed. No true
warFile The artifacts WAR file. No The mfp-dev-artifacts.war file is in the same directory as the mfp-ant-deployer.jar file

By using this element, we can define your own JNDI properties or override the default value of the JNDI properties that are provided by the administration service and the MobileFirst Operations Console WAR files.
The <property> element specifies a deployment property to be defined in the application server. It has the following attributes:
Table 6. Attributes for the <property> element
Attribute Description Required Default value
name The name of the property. Yes None
value The value of the property. Yes None

By using this element, we can define your own JNDI properties or override the default value of the JNDI properties that are provided by the administration service and the MobileFirst Operations Console WAR files.
For more information about the JNDI properties, see List of JNDI properties for MobileFirst Server administration service.

To specify an application server

Use the <applicationserver> element to define the parameters that depend on the underlying application server. The <applicationserver> element supports the following elements.
Table 7. Inner elements of the <applicationserver> element
Element Description Count
<websphereapplicationserver> or <was> The parameters for WebSphere Application Server.
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.
0..1
<tomcat> The parameters for Apache Tomcat. 0..1

The attributes and inner elements of these elements are described in Table 5 through Table 14 of Ant tasks for installation of MobileFirst runtime environments.
However, for the inner element of the <was> element for Liberty collective, see the following table:
Table 8. Inner element of the <was> element for Liberty collective
Element Description Count
<collectiveController> A Liberty collective controller. 0..1

The <collectiveController> element has the following attributes:
Table 9. Attributes of the <collectiveController> element
Attribute Description Required Default value
serverName The name 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 controller. Possible values are true or false. No true

To specify the live update service configuration

Use the <configuration> element to define the parameters that depend on the live update service. The <configuration> element has the following attributes.
Table 10. Attributes of the <configuration> element
Attribute Description Required Default value
install To indicate whether the live update service must be installed. Yes true
configAdminUser The administrator for the live update service. No. However, it is required for a server farm topology. If not defined, a user is generated.
In a server farm topology, the user name must be the same for all the members of the farm.
configAdminPassword The administrator password for live update service user. If a user is specified for configAdminUser. None.
In a server farm topology, the password must be the same for all the members of the farm.
createConfigAdminUser To indicate whether to create an admin user in the basic registry of the application server, if it is missing. No true
warFile The live update service WAR file. No The mfp-live-update.war file is in the same directory as the mfp-ant-deployer.jar file.

The <configuration> element supports the following elements:
Table 11. Inner elements of the <configuration> element
Element Description Count
<user> The user for the live update service. 0..1
<property> The properties. 0..

The <user> element collects the parameters about a user to include in a certain security role for an application.
Table 12. Attributes of the <user> element
Attribute Description Required Default value
role A valid security role for the application. Possible value: configadmin. Yes None
name The user name. Yes None
password The password if the user needs to be created. No None

After you defined the users by using the <user> element, we can map them to any of the following roles for authentication in MobileFirst Operations Console:
configadmin
For more information about which authorizations are implied by the specific roles, see Configure user authentication for MobileFirst Server administration.
Tip: If the users exist in an external LDAP directory, set only the role and name attributes but do not define any passwords.
The <property> element specifies a deployment property to be defined in the application server. It has the following attributes:
Table 13. Attributes for the <property> element
Attribute Description Required Default value
name The name of the property. Yes None
value The value of the property. Yes None

By using this element, we can define your own JNDI properties or override the default value of the JNDI properties that are provided by the administration service and the MobileFirst Operations Console WAR files.
For more information about the JNDI properties, see List of JNDI properties for MobileFirst Server administration service.

To specify the push service configuration

Use the <push> element to define the parameters to configure the connection to the push service. The <push> element has the following attribute.
Table 14. Attribute of the <push> element
Attribute Description Required Default value
configure To indicate whether to configure the connection to the push service. No false

The <push> element supports the following element:
Table 15. Inner element of the <push> element
Element Description Count
<authorization> The configuration of the authorization server for the communication with the push service. Mandatory if the configure attribute is set to true. 1

The <authorization> element collects information to configure the authorization server for the authentication communication with other MobileFirst Server components. This element has the following attributes:
Table 16. Attributes of the <authorization> element
Attribute Description Required Default value
auto To indicate whether the authorization server URL is computed. The possible values are true or false. Required on a WebSphere Application Server Network Deployment cluster or node. true
authorizationURL The URL of the authorization server. If mode is not auto. The context root of the runtime on the local server.
runtimeContextRoot The context root of the runtime. No /mfp
adminClientID The administration service confidential ID in the authorization server. Yes None
adminClientSecret The administration service confidential client password in the authorization server. Yes None
pushURL The URL of the push service. If mode is not auto. /imfpush on the local server.
pushClientID The push service confidential client ID in the authorization server. Yes None
pushClientSecret The push service confidential password in the authorization server. Yes None

auto

If the value is set to true, the URL of the authorization server and the push service is computed automatically by using the context root of the runtime on the local application server. The auto mode is not supported if you deploy on WebSphere Application Server Network Deployment on a cluster.

authorizationURL

The URL of the authorization server. If the authorization server is the MobileFirst runtime, the URL is the URL of the runtime. For example, http://myHost:9080/mfp.

runtimeContextRoot

The context root of the runtime used to compute the URL of the authorization server in the automatic mode.

adminClientID

The ID of this administration service instance as a confidential client of the authorization server.

adminClientSecret

The secret key of this administration service instance as a confidential client of the authorization server.

pushClientID

The ID of this push service instance as a confidential client of the authorization server. If provided, the administration service registers it as a confidential client.

pushClientSecret

The secret key of this push service instance as a confidential client of the authorization server. If provided, the administration service registers it as a confidential client.

To specify JMX communication between the MobileFirst Server administration service and the MobileFirst projects

Use the <jmx> element to ensure that a JMX connection can be established between the MobileFirst Server administration service and the MobileFirst runtime projects. The <jmx> element has the following attributes, which depend on the underlying application server.
Table 17. Attributes of the <jmx> element
Attribute Description Required Default
libertyAdminUser The administrator (for Liberty only). No None
libertyAdminPassword The administrator password (for Liberty only). No None
createLibertyAdmin Whether the admin user must be created in the basic registry, if it does not exist (for Liberty only). No true
tomcatRMIPort The RMI port that Apache Tomcat uses to connect to MobileFirst projects (for Tomcat only). No 8686
tomcatSetEnvConfig To prevent automatic modification of setenv.bat and setenv.sh scripts. The valid values are manual and auto. No auto

Note: The libertyAdminUser and libertyAdminPassword attributes are not mandatory, but if you define one of these attributes, you must also define the other.
libertyAdminUser

libertyAdminCreate

libertyAdminPassword

We use these attributes to create an admin user in the server.xml file, which is the configuration file for Liberty, in the basic registry section.
tomcatRMIPort

If the default port 8686 is not available on the system, we use this attribute to specify a different port for JMX communication between the administration service and the managed MobileFirst projects. In this case, the port values range from 1 to 65535.

tomcatSetEnvConfig
We use this attribute to allow or prevent the installmobilefirstadmin and uninstallmobilefirstadmin Ant tasks from adding or removing contents to the setenv.sh or setenv.bat script, in the Tomcat_Root_Install_Dir/bin directory.
Important: Security warning. The default value auto does not secure the JMX communication. This setting is not suitable for production environments. In production environments, we must manually configure JMX with authentication, as described in the Enabling JMX Remote page of the Apache Tomcat user documentation. Use the following values for this attribute:
manual: The installmobilefirstadmin and uninstallmobilefirstadmin Ant tasks do not update the setenv.bat and setenv.sh script for JMX usage.
If you select the value manual, we must update the scripts manually to define the RMI port that is used for JMX communications internally between the administration service and the MobileFirst runtime environment, whether this connection must be secured or not with user or role authentication, or SSL. For more information, see the documentation of the JVM that you are using.
auto: The installmobilefirstadmin and uninstallmobilefirstadmin Ant tasks update the setenv.bat and setenv.sh script automatically, for JMX usage. If these scripts do not exist, they are created before they are updated.
If you select the auto value, the following modifications are made to extend the CATALINA_OPTS environment variable:
For setenv.bat:
REM Allow to inspect the MBeans through jconsole
set CATALINA_OPTS=%CATALINA_OPTS% -Dcom.sun.management.jmxremote

REM Configure JMX.
set CATALINA_OPTS=%CATALINA_OPTS% -Djava.rmi.server.hostname=localhost
set CATALINA_OPTS=%CATALINA_OPTS% -Dcom.sun.management.jmxremote.port=8686
set CATALINA_OPTS=%CATALINA_OPTS% -Dcom.sun.management.jmxremote.authenticate=false
set CATALINA_OPTS=%CATALINA_OPTS% -Dcom.sun.management.jmxremote.ssl=false
For setenv.sh:
# Allow to inspect the MBeans through jconsole
CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote"

# Configure JMX.
CATALINA_OPTS="$CATALINA_OPTS -Djava.rmi.server.hostname=localhost"
CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.port=8686"
CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.authenticate=false"
CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.ssl=false"
To specify a connection to the administration service database

The <database> element collects the parameters that specify a data source declaration in an application server to access the administration service database.
You must declare a single database: <database kind="MobileFirstAdmin">. You specify the <database> element similarly to the configuredatabase Ant task, except that the <database> element does not have the <dba> and <client> elements. It might have <property> elements.
The <database> element has the following attributes:
Table 18. Attributes of the <database> element
Attribute Description Required Default
kind The kind of database (MobileFirstAdmin). Yes None
validate To validate whether the database is accessible. No true

The <database> element supports the following elements. For more information about the configuration of these database elements for relational DBMS, see Table 18 through Table 28 in Ant tasks for installation of MobileFirst runtime environments.
Table 19. Inner elements for the <database> element
Element Description Count
<db2> The parameter for DB2® databases. 0..1
<derby> The parameter for Apache Derby databases. 0..1
<mysql> The parameter for MySQL databases. 0..1
<oracle> The parameter for Oracle databases. 0..1
<driverclasspath> The parameter for JDBC driver class path (relational DBMS only). 0..1

To specify a user and a security role

The <user> element collects the parameters about a user to include in a certain security role for an application.
Table 20. Attributes of the <user> element
Attribute Description Required Default
role A valid security role for the application. Yes None
name The user name. Yes None
password The password if the user needs to be created. No None

After you defined users by using the <user> element, we can map them to any of the following roles for authentication in the MobileFirst Operations Console.
mfpmonitor
mfpoperator
mfpdeployer
mfpadmin

For information about which authorizations are implied by the specific roles, see the chapter about the REST API for the MobileFirst Server administration service.
Tip: If users exist in an external LDAP directory, set only the role and name attributes but do not define any passwords.

Parent topic: Installation reference


Attribute	Description	Required	Default
contextroot	The common prefix for URLs to the administration service to get information about MobileFirst runtime environments, applications, and adapters.	No	/mfpadmin
id	To distinguish different deployments.	No	Empty
environmentId	To distinguish different MobileFirst environments.	No	Empty
servicewar	The WAR file for the administration service.	No	The mfp-admin-service.war file is in the same directory as the mfp-ant-deployer.jar file.
shortcutsDir	The directory where to place shortcuts.	No	None
wasStartingWeight	The start order for WebSphere Application Server. Lower values start first.	No	1


Element	Description	Count
<applicationserver>	The application server.	1
<configuration>	The live update service.	1
<console>	The administration console.	0..1
<database>	The databases.	1
<jmx>	To enable Java Management Extensions.	1
<property>	The properties.	0..
<push>	The push service.	0..1
<user>	The user to be mapped to a security role.	0..