Ant tasks for installation of MobileFirst Operations Console and Administration Services

Task effects

<installworklightadmin>

The <installworklightadmin> task configures an application server to run an Administration Services WAR file as a web application and, optionally, to install the MobileFirst Operations Console. This task has the following effects:

• It declares the Administration Services web application in the specified context root, by default /worklightadmin.
• For the relational databases, it declares data sources and, on WebSphere® Application Server Full Profile, JDBC providers for Administration Services.
• It deploys the Administration Services on the application server.
• Optionally, it declares the MobileFirst Operations Console as a web application in the specified context root, by default /worklightconsole. 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">
    <installworklightadmin servicewar="${worklight.service.war.file}">
      <console install="${wladmin.console.install}" warFile="${worklight.console.war.file}"/>

• Optionally, it deploys the MobileFirst Operations Console WAR file on the application server.
• It configures configuration properties for the Administration Services 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 the MobileFirst Operations Console and Administration Services web applications.
• It configures the application server for use of JMX.
• On WebSphere Application Server, it configures the necessary custom property for the web container.

<updateworklightadmin>

The <updateworklightadmin> task updates an already-configured MobileFirst web application on an application server. This task has the following effects:

• It updates the Administration Services 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.

Note: On WebSphere Application Server Liberty profile, the task does not change the features, which leaves a potential non-minimal list of features in the server.xml file for the installed application.

<uninstallworklightadmin>

The <uninstallworklightadmin> Ant task undoes the effects of an earlier run of <installworklightadmin>. This task has the following effects:

• It removes the configuration of the Administration Services 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 Administration Services WAR file and the MobileFirst Operations Console WAR file 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 Administration Services.
• For the relational DBMS, it removes the database drivers that were used by Administration Services from the application server.
• It removes the associated JNDI environment entries.
• It removes the users configured by the installworklightadmin invocation.
• It removes the JMX configuration.

Attributes and elements

The <installworklightadmin>, <updateworklightadmin>, and <uninstallworklightadmin> tasks have the following attributes:

contextroot and id

The contextroot and id attributes distinguish different deployments of MobileFirst Operations Console and Administration Services.

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 and MobileFirst runtime web applications, that must operate independently. For example, with this option you 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 Services 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 Services WAR file. You 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, you 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.
• worklight-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.
• worklight-admin-service.sh: This file is a UNIX shell script that provides the same output as the worklight-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 Services 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 database and cannot handle server requests.

To specify a MobileFirst Operations Console

The <console> element supports the following element:

The <property> element specifies a deployment property to be defined in the application server. It has the following attributes:

By using this element, you can define your own JNDI properties or override the default value of the JNDI properties that are provided by the Administration Services and the MobileFirst Operations Console WAR files.

For more information about the JNDI properties, see List of JNDI properties for MobileFirst Server administration.

To specify an application server

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

Use the <jmx> element to ensure that a JMX connection can be established between the MobileFirst Server administration and the MobileFirst runtime projects. The <jmx> element has the following attributes, which depend on the underlying application server.

libertyAdminUser

libertyAdminCreate

libertyAdminPassword

You 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, you use this attribute to specify a different port for JMX communication between the MobileFirst Server administration and the managed MobileFirst projects. In this case, the port values range from 1 to 65535.

tomcatSetEnvConfig

You use this attribute to allow or prevent the <installworklightadmin> and <uninstallworklightadmin> Ant tasks from adding or removing contents to the setenv.sh or setenv.bat script, in the <TomcatRootInstallDir>/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, you 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 <installworklightadmin> and <uninstallworklightadmin> Ant tasks do not update the setenv.bat and setenv.sh script for JMX usage.

  If you select the value manual, you must update the scripts manually to define the RMI port that is used for JMX communications internally between the Administration Services 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 <installworklightadmin> and <uninstallworklightadmin> 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 database

The <database> element collects the parameters that specify a data source declaration in an application server to access the administration database.

You must declare a single database: <database kind="WorklightAdmin">. 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:

To specify a user and a security role

For information about which authorizations are implied by the specific roles, see the chapter about the REST API Administration Services.