Using the IBM® XPages for Bluemix™ runtime environment variables

Overview

Environment variables are used in Bluemix™ to provide information about applications, services, and the Bluemix™ environment itself. These system-provided environment variables allow applications and services that run in Bluemix™ to retrieve the information they need about the Bluemix™ environment.

With the XPages boilerplate (a starter application that uses both the IBM® XPages NoSQL Database for Bluemix™ service and the IBM® XPages for Bluemix™ runtime), environment variables are used as the means by which the Cloud Foundry runtime can communicate with the deployed starter application about its environment.

For Bluemix™ specifically, you use the VCAP_SERVICES environment variable to retrieve the information and credentials you need to access the IBM® XPages NoSQL Database for Bluemix™ service with various Bluemix™ runtimes. In Domino® Designer, the bluemixContext object provides various methods that let you retrieve information from the XPages runtime as well as connection information from any bound XPages NoSQL Database service. This is done by parsing the VCAP_SERVICES environment variable provided by the bound service. Refer to the Bluemix™ documentation for more information on the VCAP_SERVICES environment variable.

In addition to the information automatically provided by the VCAP_SERVICES environment variable, the XPages runtime provides its own collection of environment variables to help optimize integration with the Bluemix™ platform. In Domino® Designer, the Bluemix™ Manifest editor includes an XPages runtime environment variables section to let you set this group of environment variables to the desired value. To open the Manifest editor in Domino® Designer, select IBM Bluemix Manifest under the Application Configuration category in the Applications Navigator.

XPages for Bluemix™ runtime environment variables

The main group of XPages runtime environment variables provided for you includes:

APP_HOME_URL

Specifies the filename of the NSF that will be used as the default root for the route of an application. It must include a leading slash. Domino® Designer automatically sets this variable if it is not already defined in the Bluemix™ manifest.yml file.

Examples:

APP_HOME_URL: /crm.nsf
APP_HOME_URL: /crm.nsf/index.xsp

APP_PRELOAD_DB

Specifies the filename (for example, file_name.nsf) of the NSF to be preloaded during the staging and startup process of the XPages runtime container. This is typically the same value as the APP_HOME_URL variable except it does not require a leading slash. It can also be a comma-delimited list of filenames to accommodate the preloading of several NSF applications. Domino® Designer automatically sets this variable if it is not already defined in the Bluemix™ manifest.yml file.

Examples:

APP_PRELOAD_DB: crm.nsf
APP_PRELOAD_DB: crm.nsf,plm.nsf,mrp.nsf

APP_JVM_HEAPSIZE

Specifies a JVM HeapSize that is different than the minimum default of 256 MB. Some applications may have higher memory demands and therefore it is important to be able to adjust the amount of memory allocated to an application at runtime accordingly. You can use this variable to change the JVM HeapSize but make sure that is kept below the MEMORY_LIMIT set for the application.

Setting this variable to a value lower than 256 MB will have no effect as XPages enforces 256 MB as the minimum at runtime when an application instance is staged and started.

Examples:

APP_JVM_HEAPSIZE: 256MB
APP_JVM_HEAPSIZE: 512MB

APP_JAVA_POLICY_ALL_PERMISSION

Used to apply permission java.security.AllPermission; against the JVM security policy of the XPages runtime container. When enabled, this feature allows privileged execution to custom Java™ code within NSF applications. This feature is disabled by default.

A value of 1 enables this feature.

A value of 0, blank, or undefined disables this feature.

Examples:

APP_JAVA_POLICY_ALL_PERMISSION: 1
APP_JAVA_POLICY_ALL_PERMISSION: 0 

This variable allows enabling/disabling at a global level of JVM privileged code execution. This is disabled by default so that custom Java™ code within an NSF is sandboxed.

In addition to this new security related feature, there is also support for letting you push a java.policy-fragment file with an application. The purpose of this file is to allow fine-grained JVM security policy configuration. If this file exists and APP_JAVA_POLICY_ALL_PERMISSION is disabled, then the JVM grant statements within the java.policy-fragment are merged into the global JVM security policy file.

APP_REDIRECT_TO_SSL

When enabled, application requests are always processed using the HTTPS protocol. When disabled, the regular HTTP protocol is normally used but programmatic switching to the HTTPS protocol is still possible for specific requests. This is enabled by default.

A value of 1 enables this feature.

A value of 0, blank, or undefined disables this feature.

Examples:

APP_REDIRECT_TO_SSL: 1
APP_REDIRECT_TO_SSL: 0 

The following example shows how these XPages environment variables are stored in a Bluemix™ manifest.yml file.

applications:
- services:
  - stagetest1-XPagesData
  disk_quota: 1024M
  buildpack: xpages_buildpack
  host: stagetest1
  name: stagetest1
  path: .
  domain: mybluemix.net
  env:
    APP_HOME_URL: /ToDo_design.nsf
    APP_PRELOAD_DB: ToDo_design.nsf
    APP_INCLUDE_XPAGES_TOOLBOX: 1
    APP_JVM_HEAPSIZE: 512M
    APP_VERBOSE_STAGING: 1
    APP_JAVA_POLICY_ALL_PERMISSION: 0
  instances: 1
  memory: 512M

The next sections in this topic provide information on runtime environment variables for use with application debugging and hybrid applications.

Runtime environment variables for use with debugging applications

These runtime environment variables are provided to help you with debugging tasks:

APP_INCLUDE_XPAGES_TOOLBOX

Specifies whether to provision the XPages Buildpack Toolbox application into the XPages runtime application instance and also enable RAM and CPU profiling analysis. This is disabled by default and is a specialist developer tool to assist with performance and scalability optimization during application development phase. It can also be used for troubleshooting purposes of a production application.

Ideally, it should be unprovisioned before an application is put into production mode and only enabled against a production application when necessary.

When enabled, the toolbox can be accessed on the same route as the deployed application using /XPagesBuildpackToolbox.nsf on the path.

A value of 1 enables this feature.

A value of 0, blank, or undefined disables this feature (the default setting).

Examples:

APP_INCLUDE_XPAGES_TOOLBOX: 1
APP_INCLUDE_XPAGES_TOOLBOX: 0

APP_VERBOSE_STAGING

Specifies whether verbose logging information is output to the command line interface (CLI) console and console.log on Bluemix™ during application staging. This feature is disabled by default.

A value of 1 enables this feature.

A value of 0, blank, or undefined disables this feature.

Examples:

APP_VERBOSE_STAGING: 1
APP_VERBOSE_STAGING: 0

APP_DEBUG_STAGING

When enabled, lets detailed debug information be generated during application staging. Information is collected into the console log file in the IBM_TECHNICAL_SUPPORT directory. Disabled by default.

Note: It is very important to note that when this property is enabled, detailed information will be collected into the console.log file and should be treated with high sensitivity

A value of 1 enables this feature.

A value of 0, blank, or undefined disables this feature.

Examples:

APP_DEBUG_STAGING: 1
APP_DEBUG_STAGING: 0 

APP_DEBUG_THREADS

When enabled, detailed thread request and response information is collected into separate thread log files in the IBM_TECHNICAL_SUPPORT directory. Each active thread is assigned a log file in this location (Naming format: htthr*.log). Disabled by default.

A value of 1 enables this feature.

A value of 0, blank, or undefined disables this feature.

Examples:

APP_DEBUG_THREADS: 1
APP_DEBUG_THREADS: 0 

APP_DEBUG_DIRECTORY_ASSISTANCE

When enabled, detailed directory assistance debug information is collected into the console log file in the IBM_TECHNICAL_SUPPORT directory. Disabled by default.

A value of 1 enables this feature.

A value of 0, blank, or undefined disables this feature.

Examples:

APP_DEBUG_DIRECTORY_ASSISTANCE: 1
APP_DEBUG_DIRECTORY_ASSISTANCE: 0 

APP_DEBUG_NAMELOOKUP

When enabled, detailed name lookup information is collected into the console log file in the IBM_TECHNICAL_SUPPORT directory. Disabled by default.

A value of 1 enables this feature.

A value of 0, blank, or undefined disables this feature.

Examples:

APP_DEBUG_NAMELOOKUP: 1
APP_DEBUG_NAMELOOKUP: 0 

XPages for Bluemix™ runtime environment variables for hybrid applications

With the support of hybrid applications, a group of XPages Runtime Environment Variables are provided to help you work with hybrid application configuration information. The Bluemix Manifest editor includes a Hybrid Configuration section to let you set this group of environment variables to the desired value.

To open the Manifest editor in Designer, select IBM Bluemix Manifest under the Application Configuration category in the Applications Navigator. By clicking on the Edit... button in the Hybrid Configuration section, you can open the "Configure a hybrid Domino connection model" panel to make changes to the current hybrid configuration variable settings.

The environment variables related to hybrid applications include the following:

APP_REMOTE_DATA_SERVER_ADDRESS

Specifies the IP address of the desired remote on-premises or cloud-hosting server (for example, 126.228.15.68)

APP_REMOTE_DATA_SERVER_NAME

Specifies the name of the desired remote on-premises or cloud-hosting server (for example, onpremises/yourserver).

APP_RUNTIME_SERVER_NAME

Specifies the name of the runtime application container server (for example, xpagesruntime/runtimeserver)

APP_RUNTIME_SERVER_IDFILE

Specifies the name of the ID file that will be used during application staging (for example, C:\Program Files\IBM\Notes\Data\ids\servers\runtime_server.id))

APP_DA_ENABLED

Specifies whether ID directory assistance has been enabled for your hybrid configuration.

APP_DA_DOMAIN

Specifies the domain name of the on-premises server.

APP_DA_ADDRESS_BOOK

Specifies the domain directory NSF filename needed for authentication in your hybrid application configuration.