Configure a MobileFirst project in production using JNDI environment entries

Configure a MobileFirst project in production using JNDI environment entries

We can configure a project's WAR file with JNDI environment entries for setting MobileFirst server properties.
JNDI environment entries cover all the properties we can set in a production environment. You set the JNDI environment entries in one of two ways:

Editing the configuration XML file for the deployer Ant tasks
Configuring the server's environment entries

On WAS full profile, we use the administration console. On WAS Liberty profile or Apache Tomcat, you edit the server.xml file.

Many of the MobileFirst configuration properties must have different values when the project is deployed to different environments. For example, the configuration properties used to specify the MobileFirst Server public URL (that is, publicWorkLightHostname, publicWorkLightPort, and publicWorkLightProtocol) might be different when the project.is deployed to a staging server or to a production server. We can configure the project WAR file through JNDI environment entries.
Some of the properties are relevant only in a development environment and are not available as JNDI entries.
There are two ways to encrypt the JNDI properties listed in the following table, as described in Storing properties in encrypted format:

We can define the property with the .enc suffix in worklight.properties that is packaged in the WAR file of the project. Then override the encrypted value using a JNDI property. With Apache Tomcat, this option is the only one available.

On WAS full profile and Liberty profile, we can use the password encoding tools: PropFilePasswordEncoder for WAS and SecurityUtility for Liberty profile.

The following table lists the MobileFirst properties that are always available as JNDI entries:

Property name Description
publicWorkLightHostname IP address or host name of the computer running MPF. If the MobileFirst Server is behind a reverse proxy, the value is the IP address or host name of the reverse proxy. This property must be identical for nodes within the same cluster.
Default: IP address of current server.
publicWorkLightPort The port for accessing the MobileFirst Server. If the MobileFirst Server is behind a reverse proxy, the value is the port for accessing the reverse proxy. This property must be identical for nodes within the same cluster.
Default: 10080.
The configureApplicationServer Ant task sets a default value that depends on the application server.
publicWorkLightProtocol The protocol for accessing the MobileFirst Server. Value values are HTTP and HTTPS. If the MobileFirst Server is behind a reverse proxy, the value is the protocol for accessing the reverse proxy. This property must be identical for nodes within the same cluster.
Default: HTTP.
The configureApplicationServer Ant task sets a default value that depends on the application server.
serverSessionTimeout
Idle session timeout in minutes. Default: 10.
reports.exportRawData
Whether reporting is activated (true or false). Default: false.
push.gcm.proxy.host
GCM proxy host. A negative value means default port.
push.gcm.proxy.port
GCM proxy port. Use -1 for the default port. Default: -1.
push.gcm.proxy.protocol
Either http or https.
push.gcm.proxy.enabled
Shows whether GCM must be accessed through a proxy. Default: false.
push.gcm.proxy.user
Proxy user name, if the proxy requires authentication. Empty user name means no authentication.
push.gcm.proxy.password
Proxy password, if the proxy requires authentication.
push.apns.proxy.enabled
Indicates whether APNS must be accessed through a proxy. Default: false.
push.sms.proxy.enabled
Indicates whether push SMS proxy is enabled. Default: false.
push.apns.proxy.host
APNS proxy host.
push.apns.proxy.port
APNS proxy port.
push.sms.proxy.protocol
Push SMS proxy protocol.
push.sms.proxy.host
Push SMS proxy host.
push.sms.proxy.port
Push SMS proxy port.
push.sms.proxy.user
Push SMS proxy user.
push.sms.proxy.password
Push SMS proxy password.
wl.ca.keystore.path
Path to the keystore relative to the server folder in the project. for example: conf/my-cert.jks.
wl.ca.keystore.type
Type of keystore file. Valid values are jks or pkcs12.
wl.ca.keystore.password
Password to the keystore file.
wl.ca.key.alias
Alias of the entry where the private key and certificate are stored in the keystore.
wl.ca.key.alias.password
Password to the alias in the keystore.
ssl.keystore.path
SSL certificate keystore location. Default: conf/default.keystore.
ssl.keystore.type
SSL certificate keystore type. Valid keystore types: jks or PKCS12. Default: jks.
ssl.keystore.password
SSL certificate keystore password. Default: worklight.
cluster.data.synchronization.taskFrequencyInSeconds
Applications and adapters cluster data synchronization interval. Default: 2.
deployables.cleanup.taskFrequencyInSeconds
Deployable folder cleanup task interval (in seconds). Default: 86400.
sso.cleanup.taskFrequencyInSeconds
Interval (seconds) for a cleanup task that cleans the database of orphaned and expired single-sign-on login contexts. Default: 5
wl.analytics.logs.forward
Boolean value (true or false) that indicates whether to send all com.worklight.* logs to the operational analytics server. If this value is true, all logs specified in com.worklight settings are forwarded to the operational analytics server. Default is true. This setting is only supported on MobileFirst production servers. It is not supported on the MobileFirst Studio development environment.
wl.analytics.url
URL that is exposed by the MPF Operational Analytics that receives incoming analytics data. Example: http://host:<port>/<context-root>/data.
wl.analytics.username
User name used if the data entry point for the MPF Operational Analytics is protected with basic authentication.
wl.analytics.password
Password used if the data entry point for the MPF Operational Analytics is protected with basic authentication.
wl.analytics.queues
Sets the maximum number of queues that MobileFirst Server can create to hold analytics data before it sends the data to the server. When all the queues are full, MobileFirst Server quietly discards any new analytics data until the current data finishes processing. Default: 20.
wl.analytics.queue.size
The number of individual analytics events that each queue can hold. The total number of analytics events that the server can hold at one time before it begins to drop data is (wl.analytics.queues * wl.analytics.queue.size). In a production environment, the default value is 10. In the MobileFirst Studio development environment, when we use the MobileFirst Development Server, the default value is 1. This value can be changed by setting a different value through JNDI. (Optional.)
wl.clientlogs.adapter.name
The name of the HTTP adapter to use to receive client-side logs. If we do not specify this property, the default WLClientLogReceiver name is used.
wl.device.archiveDecommissioned.when
A value, in days, that defines when client devices that were decommissioned will be placed in an archive file when the decommissioning task is run. The archived client devices are written to a file in the MobileFirst Server home\devices_archive directory. The name of the file contains the time stamp when the archive file is created. Default: 90 days.
wl.device.decommission.when
The number of days of inactivity after which a client device is decommissioned by the device decommissioning task. Default: 90 days.
wl.device.enableAccessManagement
A Boolean value (true or false) that enables the Access Management features on the MobileFirst Server. If the Access Management features are enabled, each time a device attempts to connect to the server, it is checked against the backend for its access rights.
wl.device.tracking.enabled
A value used to enable or disable device tracking in IBM MobileFirst Platform Foundation. For performance reasons, we can disable this flag when MPF is running only Business-to-Consumer (B2C) apps. When device tracking is disabled, the license reports are also disabled and no license metrics are generated.
ibm.worklight.admin.rmi.registryPort
Optional. RMI registry port for the JMX connection through a firewall. Tomcat only.
ibm.worklight.admin.rmi.serverPort
Optional. RMI server port for the JMX connection through a firewall. Tomcat only.
ibm.worklight.admin.jmx.connector
Mandatory. JMX connector type, by default RMI/SOAP. WebSphere Application Server profile only.
ibm.worklight.admin.jmx.dmgr.host
Mandatory. dmgr host name. WAS ND only.
ibm.worklight.admin.jmx.dmgr.port
Mandatory. dmgr RMI or SOAP port. WAS ND only.
ibm.worklight.admin.environmentid
Optional. Environment identifier for the registration of the MBeans. Use this identifier when different instances of the MobileFirst Server are installed on the same application server. The identifier determines which administration services, which console, and which runtimes belong to the same installation. The administration services manage only the runtimes that have the same environment identifier.
ibm.worklight.admin.serverid
Optional. Server identifier. Must be different for each server in the farm. Server farms only.
ibm.worklight.jndi.configuration
Optional. If the JNDI configuration is injected into the WAR files or provided as a shared library, the value of this property is the name of the JNDI configuration. This value can also be specified as a system property. See JNDI properties file for transfer.
ibm.worklight.jndi.file
Optional. If the JNDI configuration is stored as an external file, the value of this property is the path of a file that describes the JNDI configuration. This value can also be specified as a system property. See JNDI properties file for transfer.
ibm.worklight.topology.platform
Server type. The values can be:

Liberty

WAS

Tomcat

If the default value is not set, the application tries to guess the server type.
ibm.worklight.topology.clustermode
In addition to the server type, we must specify the server topology. The values allowed:

Standalone

Cluster

Farm

Default is Standalone.

Custom user properties that are defined in worklight.properties are exposed, too.
The wl.db.* and wl.reports.db.* properties are not available as JNDI environment entries because they are intended for use only during the development phase.
Configuring with the Ant task
When we deploy and configure the project with the Ant task (as described in Deploy a project WAR file and configure the application server with Ant tasks), it is possible to set values for MobileFirst configuration properties inside the <configureapplicationserver> tag. For example:
<configureapplicationserver shortcutsDir="${shortcuts.dir}">
  <property name="serverSessionTimeout" value="30"/>
  <property name="publicWorkLightHostname" value="www.example.com"/>
  <property name="publicWorkLightPort" value="80"/>
  <property name="publicWorkLightProtocol" value="http"/>
Manually configuring on the server
In some cases, when you do not want to or cannot redeploy the application, it is also possible to set values for MobileFirst configuration properties manually on the server configuration files (or console). This procedure is what the Ant task does behind the scenes. The manual configuration method is less recommended because in some cases (for example, when upgrading or redeploying), the application server might forget the configuration and the administrator must reconfigure it.

Complete the following tasks, depending on which application server is used:
WebSphere Liberty profile:
Insert the following declarations in the server.xml file:
<application id="worklight" name="worklight" location="worklight.war" 
  type="war" context-root="/app_context_path">
</application>
<jndiEntry value="9080" jndiName="app_context_path/publicWorkLightPort"/>
<jndiEntry value="www.example.com" jndiName="app_context_path/publicWorkLightHostname"/>
The context path (in the previous example: app_context_path) connects between the JNDI entry and a specific MobileFirst application. If multiple MobileFirst applications exist on the same server, we can define specific JNDI entries for each application using the context path prefix. Typically, app_context_path is "worklight".
Apache Tomcat:
Insert the following declarations in the server.xml file:
<Context docBase="app_context_path" path="/app_context_path">
  <Environment name="publicWorkLightPort" override="false" 
    type="java.lang.String" value="9080"/>
  <Environment name="publicWorkLightHostname" override="false" 
    type="java.lang.String" value="www.example.com"/>
</Context>
On Apache Tomcat, override="false" is mandatory.
With Apache Tomcat, the context path prefix is not needed because the JNDI entries are defined inside the <Context> element of an application.
WebSphere Application Server:

In the administration console, go to Applications > Application Types > WebSphere enterprise applications > Worklight > Environment entries for Web modules

In the Value fields, enter values that are appropriate to the circumstances. See Figure 1
Figure 1. Setting JNDI environment entries on WebSphere Application Server
Preconfiguring JNDI properties
As an alternative to setting JNDI environment entries by editing the deployer Ant task configuration XML file or by configuring the server environment entries through the WebSphere Application Server administration console or the server.xml file on WAS Liberty profile or Apache Tomcat, we can configure all JNDI properties in advance using a property file. Holding JNDI properties in a property file makes it easier to transfer the entire configuration from one web application server to another. For example, we can configure a test web server; when the configuration is stable, we can are transfer the configuration to the production web server by copying the property file to the production server.
For details of this mechanism, see JNDI properties file for transfer.

Parent topic: Application server-side configuration parameters
Related reference:

Application server-side configuration parameters

Property name	Description
publicWorkLightHostname	IP address or host name of the computer running MPF. If the MobileFirst Server is behind a reverse proxy, the value is the IP address or host name of the reverse proxy. This property must be identical for nodes within the same cluster. Default: IP address of current server.
publicWorkLightPort	The port for accessing the MobileFirst Server. If the MobileFirst Server is behind a reverse proxy, the value is the port for accessing the reverse proxy. This property must be identical for nodes within the same cluster. Default: 10080. The configureApplicationServer Ant task sets a default value that depends on the application server.
publicWorkLightProtocol	The protocol for accessing the MobileFirst Server. Value values are HTTP and HTTPS. If the MobileFirst Server is behind a reverse proxy, the value is the protocol for accessing the reverse proxy. This property must be identical for nodes within the same cluster. Default: HTTP. The configureApplicationServer Ant task sets a default value that depends on the application server.
serverSessionTimeout	Idle session timeout in minutes. Default: 10.
reports.exportRawData	Whether reporting is activated (true or false). Default: false.
push.gcm.proxy.host	GCM proxy host. A negative value means default port.
push.gcm.proxy.port	GCM proxy port. Use -1 for the default port. Default: -1.
push.gcm.proxy.protocol	Either http or https.
push.gcm.proxy.enabled	Shows whether GCM must be accessed through a proxy. Default: false.
push.gcm.proxy.user	Proxy user name, if the proxy requires authentication. Empty user name means no authentication.
push.gcm.proxy.password	Proxy password, if the proxy requires authentication.
push.apns.proxy.enabled	Indicates whether APNS must be accessed through a proxy. Default: false.
push.sms.proxy.enabled	Indicates whether push SMS proxy is enabled. Default: false.
push.apns.proxy.host	APNS proxy host.
push.apns.proxy.port	APNS proxy port.
push.sms.proxy.protocol	Push SMS proxy protocol.
push.sms.proxy.host	Push SMS proxy host.
push.sms.proxy.port	Push SMS proxy port.
push.sms.proxy.user	Push SMS proxy user.
push.sms.proxy.password	Push SMS proxy password.
wl.ca.keystore.path	Path to the keystore relative to the server folder in the project. for example: conf/my-cert.jks.
wl.ca.keystore.type	Type of keystore file. Valid values are jks or pkcs12.
wl.ca.keystore.password	Password to the keystore file.
wl.ca.key.alias	Alias of the entry where the private key and certificate are stored in the keystore.
wl.ca.key.alias.password	Password to the alias in the keystore.
ssl.keystore.path	SSL certificate keystore location. Default: conf/default.keystore.
ssl.keystore.type	SSL certificate keystore type. Valid keystore types: jks or PKCS12. Default: jks.
ssl.keystore.password	SSL certificate keystore password. Default: worklight.
cluster.data.synchronization.taskFrequencyInSeconds	Applications and adapters cluster data synchronization interval. Default: 2.
deployables.cleanup.taskFrequencyInSeconds	Deployable folder cleanup task interval (in seconds). Default: 86400.
sso.cleanup.taskFrequencyInSeconds	Interval (seconds) for a cleanup task that cleans the database of orphaned and expired single-sign-on login contexts. Default: 5
wl.analytics.logs.forward	Boolean value (true or false) that indicates whether to send all com.worklight.* logs to the operational analytics server. If this value is true, all logs specified in com.worklight settings are forwarded to the operational analytics server. Default is true. This setting is only supported on MobileFirst production servers. It is not supported on the MobileFirst Studio development environment.
wl.analytics.url	URL that is exposed by the MPF Operational Analytics that receives incoming analytics data. Example: http://host:<port>/<context-root>/data.
wl.analytics.username	User name used if the data entry point for the MPF Operational Analytics is protected with basic authentication.
wl.analytics.password	Password used if the data entry point for the MPF Operational Analytics is protected with basic authentication.
wl.analytics.queues	Sets the maximum number of queues that MobileFirst Server can create to hold analytics data before it sends the data to the server. When all the queues are full, MobileFirst Server quietly discards any new analytics data until the current data finishes processing. Default: 20.
wl.analytics.queue.size	The number of individual analytics events that each queue can hold. The total number of analytics events that the server can hold at one time before it begins to drop data is (wl.analytics.queues * wl.analytics.queue.size). In a production environment, the default value is 10. In the MobileFirst Studio development environment, when we use the MobileFirst Development Server, the default value is 1. This value can be changed by setting a different value through JNDI. (Optional.)
wl.clientlogs.adapter.name	The name of the HTTP adapter to use to receive client-side logs. If we do not specify this property, the default WLClientLogReceiver name is used.
wl.device.archiveDecommissioned.when	A value, in days, that defines when client devices that were decommissioned will be placed in an archive file when the decommissioning task is run. The archived client devices are written to a file in the MobileFirst Server home\devices_archive directory. The name of the file contains the time stamp when the archive file is created. Default: 90 days.
wl.device.decommission.when	The number of days of inactivity after which a client device is decommissioned by the device decommissioning task. Default: 90 days.
wl.device.enableAccessManagement	A Boolean value (true or false) that enables the Access Management features on the MobileFirst Server. If the Access Management features are enabled, each time a device attempts to connect to the server, it is checked against the backend for its access rights.
wl.device.tracking.enabled	A value used to enable or disable device tracking in IBM MobileFirst Platform Foundation. For performance reasons, we can disable this flag when MPF is running only Business-to-Consumer (B2C) apps. When device tracking is disabled, the license reports are also disabled and no license metrics are generated.
ibm.worklight.admin.rmi.registryPort	Optional. RMI registry port for the JMX connection through a firewall. Tomcat only.
ibm.worklight.admin.rmi.serverPort	Optional. RMI server port for the JMX connection through a firewall. Tomcat only.
ibm.worklight.admin.jmx.connector	Mandatory. JMX connector type, by default RMI/SOAP. WebSphere Application Server profile only.
ibm.worklight.admin.jmx.dmgr.host	Mandatory. dmgr host name. WAS ND only.
ibm.worklight.admin.jmx.dmgr.port	Mandatory. dmgr RMI or SOAP port. WAS ND only.
ibm.worklight.admin.environmentid	Optional. Environment identifier for the registration of the MBeans. Use this identifier when different instances of the MobileFirst Server are installed on the same application server. The identifier determines which administration services, which console, and which runtimes belong to the same installation. The administration services manage only the runtimes that have the same environment identifier.
ibm.worklight.admin.serverid	Optional. Server identifier. Must be different for each server in the farm. Server farms only.
ibm.worklight.jndi.configuration	Optional. If the JNDI configuration is injected into the WAR files or provided as a shared library, the value of this property is the name of the JNDI configuration. This value can also be specified as a system property. See JNDI properties file for transfer.
ibm.worklight.jndi.file	Optional. If the JNDI configuration is stored as an external file, the value of this property is the path of a file that describes the JNDI configuration. This value can also be specified as a system property. See JNDI properties file for transfer.
ibm.worklight.topology.platform	Server type. The values can be: Liberty WAS Tomcat If the default value is not set, the application tries to guess the server type.
ibm.worklight.topology.clustermode	In addition to the server type, we must specify the server topology. The values allowed: Standalone Cluster Farm Default is Standalone.