Ant tasks for installation of operations console and administration services

Ant tasks for installation of operations console and administration services

The <installworklightadmin>, <updateworklightadmin>, and <uninstallworklightadmin> Ant tasks are provided for the installation of the operations console and administration services.

Task effects

<installworklightadmin>

Configure an application server to run an administration services WAR file as a web application and, optionally, install the operations console.
This task...

Declares the administration services web application in the specified context root, by default...
/worklightadmin

Declares data sources and - on WebSphere Application Server Full Profile - JDBC providers for administration services.

Deploys the administration services on the application server.

Optionally declares the operations console as a web application in the specified context root, by default...
/worklightconsole

If the 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, deploys the operations console WAR file on the application server.

Configure configuration properties for the administration services using JNDI environment entries, providing additional information about the application server topology, for example whether the topology is a stand-alone configuration, a cluster, or a server farm.

Optionally, map users to roles.

Configures the application server for use of JMX.

Configures the web container custom properties.

<updateworklightadmin>

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

Update the administration services WAR file. This file must have the same base name as the corresponding WAR file that was previously deployed.
Update the 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.

<uninstallworklightadmin>

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

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.

Removes the administration services WAR file and the operations console WAR file from the application server as an option.

Removes the data sources and – on WebSphere Application Server Full Profile – the JDBC providers for administration services.

Removes the database drivers that were used by administration services from the application server.

Removes the associated JNDI environment entries.

Removes the users configured by the installworklightadmin invocation.

Removes the JMX configuration.

Attributes and elements

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

Attribute Description Required Default
contextroot Common prefix for URLs to admin services, to get information about MobileFirst runtime environments, applications, and adapters No /worklightadmin
id Distinguishes different deployments No Empty
environmentId Distinguishes different MobileFirst environments No Empty
servicewar The WAR file for the administration services No The worklightadmin.war file is in the same directory as the worklight-ant-deployer.jar file.
shortcutsDir Directory where to place shortcuts No None
wasStartingWeight Start order for WAS. Lower values start first. No 1

contextroot and id

The contextroot and id attributes distinguish different deployments of operations console and administration services.
In WAS 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

Distinguish several environments, consisting each of MobileFirst Server administration 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 WAS ND 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 JMX.

servicewar

Specify a different directory for the administration services WAR file. We can specify the name of this WAR file with an absolute path or a relative path.

shortcutsDir

Where to place shortcuts to the operations console. If we set this attribute, we can add the following files to that directory:

mobilefirst-console.url: This file is a Windows shortcut. It opens the operations console in a browser.

mobilefirst-console.sh: This file is a UNIX shell script and opens the 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 project. 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 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

Value 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.

The <installworklightadmin>, <updateworklightadmin>, and <uninstallworklightadmin> tasks support the following elements:

Element Description Count
applicationserver Application server 1
console Administration console 0..1
database Databases 1
jmx Enable Java Management Extensions 1
property Properties 0..*
user User to be mapped to a security role 0..*

To specify a operations console

The <console> element collects information to customize the installation of the operations console. This element has the following attributes:

Attribute Description Required Default
contextroot URI of the operations console No /worklightconsole
install Indicates whether the operations console must be installed No Yes
warfile Console WAR file No The worklightconsole.war file is in the same directory as the worklight-ant-deployer.jar file.

The <property> element supports the following element:

Element Description Count
property Properties 0..∞

By using this element, we can define our own JDNI properties or override the default value of the JNDI properties provided by the administration services and the operations console WAR files.
For more information about the JNDI properties, see Configure a MobileFirst project in production using JNDI environment entries.

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. The attributes and inner elements of these elements are described in tables 6 through 13 of Ant tasks for installation of MobileFirst runtime environments.

Attribute Description Count
websphereapplicationserver or was The parameters for WAS. 0..1
tomcat The parameters for Apache Tomcat. 0..1

To specify JMX communication between the MobileFirst Server administration and the project.

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.

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 Prevents automatic modification of setenv.bat and setenv.sh scripts. The valid values are manual and auto. No auto

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

libertyAdminUser

libertyAdminCreate

libertyAdminPassword

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 default port 8686 is not available, 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

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, we must manually configure JMX with authentication, as described in the Enable 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 we select the value manual, update the scripts manually to define the RMI port 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. See 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 we 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:

Attribute Description Required Default
kind The kind of database (WorklightAdmin) 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, see 18 through 28 in Ant tasks for installation of MobileFirst runtime environments.

Element Description Count
db2 Parameter for DB2 databases 0..1
derby Parameter for Apache Derby databases 0..1
mysql Parameter for MySQL databases 0..1
oracle Parameter for Oracle databases 0..1
driverclasspath Parameter for JDBC driver class path 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.

Attribute Description Required Default
role A valid security role for the application Yes None
name User name Yes None
password Password if the user needs to be created No None

After you defined users using the <user> element, we can map them to any of the following roles for authentication in the operations console.

worklightmonitor

worklightoperator

worklightdeployer

worklightadmin

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

Parent topic: Reference

Attribute	Description	Required	Default
contextroot	Common prefix for URLs to admin services, to get information about MobileFirst runtime environments, applications, and adapters	No	/worklightadmin
id	Distinguishes different deployments	No	Empty
environmentId	Distinguishes different MobileFirst environments	No	Empty
servicewar	The WAR file for the administration services	No	The worklightadmin.war file is in the same directory as the worklight-ant-deployer.jar file.
shortcutsDir	Directory where to place shortcuts	No	None
wasStartingWeight	Start order for WAS. Lower values start first.	No	1

Element	Description	Count
applicationserver	Application server	1
console	Administration console	0..1
database	Databases	1
jmx	Enable Java Management Extensions	1
property	Properties	0..*
user	User to be mapped to a security role	0..*

Attribute	Description	Required	Default
contextroot	URI of the operations console	No	/worklightconsole
install	Indicates whether the operations console must be installed	No	Yes
warfile	Console WAR file	No	The worklightconsole.war file is in the same directory as the worklight-ant-deployer.jar file.

Attribute	Description	Count
websphereapplicationserver or was	The parameters for WAS.	0..1
tomcat	The parameters for Apache Tomcat.	0..1

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	Prevents automatic modification of setenv.bat and setenv.sh scripts. The valid values are manual and auto.	No	auto

Attribute	Description	Required	Default
kind	The kind of database (WorklightAdmin)	Yes	None
validate	To validate whether the database is accessible	No	True

Element	Description	Count
db2	Parameter for DB2 databases	0..1
derby	Parameter for Apache Derby databases	0..1
mysql	Parameter for MySQL databases	0..1
oracle	Parameter for Oracle databases	0..1
driverclasspath	Parameter for JDBC driver class path	0..1

Attribute	Description	Required	Default
role	A valid security role for the application	Yes	None
name	User name	Yes	None
password	Password if the user needs to be created	No	None