Using the IBM® Bluemix™ Manifest editor to change the Bluemix™ application manifest file

An editor is provided in Domino® Designer so that you can locally edit the advanced Bluemix™ properties found in the Bluemix™ application manifest file.

The IBM® Bluemix™ Manifest editor is part of the functionality and tooling available in Domino® Designer to provide the infrastructure needed to modify, configure, and deploy XPages applications to and from Bluemix™. An editor is provided in Domino® Designer so that you so that you can locally edit the advanced Bluemix™ application properties found in the Bluemix™ application manifest file (named manifest.yml by default).

Application manifests contain options that are applied when you push an application to Bluemix™. For example, you can use an application manifest to reduce the number of deployment details that you must specify every time that you push an application to Bluemix™. In application manifests, you can specify options such as the number of application instances to create, the amount of memory and disk quota to allocate to applications, and other environment variables for the application. You can also use application manifests to automate application deployments. As mentioned, the default name of a manifest file is manifest.yml.

Specifically, the types of properties and settings you can change in the file include

  • Staging settings. The settings include
    • Application name - Specifies the name of the current application.
    • Instances - Specifies the number of application instances you wish to have exist.
    • Memory - Specifies the memory for each application instance.
    • Disk Quota - Specifies the disk quota for each application instance.
    • Build pack - Specifies the version of the buildpack being used by the application.
    • Command - Lets you provide a custom application start command in your application manifest or on the command line. See the Bluemix™ documentation for more details.
    • Timeout - Specifies the amount of time you wish to give your application to start before the process is cancelled.
    • Path - Specifies the path to tell Bluemix™ where to find your application
  • URI Settings - Lets you set the application Uniform Resource Identifier (URI) information.
    • Host - Specifies the application's host address.
    • Domain - Specifies the domain address where the application resides,
    • There is no route for this application - If there is no route for the application, select this checkbox.
  • Bound Services - Lets you specify, add, or delete the Bluemix™ Services to bind to this application.
  • Hybrid Configuration Settings - Lets you specify the application Hybrid Configuration information so that you can set up and configure hybrid applications on Bluemix™. Hybrid applications can be defined as ones where your application is deployed on Bluemix™ but it accesses its data from outside of the boundaries of the Bluemix™ platform. In other words, the key characteristic of hybrid applications is that the application data resides outside of Bluemix™. This section lets you specify a frequently used collection of hybrid configuration settings that can be easily added to your Bluemix™ applications using the Bluemix™ manifest editor. The preferences that you can set in this section of the panel include the following:
    • Remote Data Connection - This section lets you specify information about the desired private cloud or on-premises server. In this portion of the panel you specify
      • Server address - specifies the IP address of the desired on-premises or cloud-hosting server (for example, 126.228.15.68).
      • Server name - specifies the name of the desired on-premises or cloud-hosting server (for example, onpremises/yourserver).
    • Runtime Application Container - This section lets you specify server credential information related to the desired Runtime Application Container. In this portion of the panel you specify
      • Server name - specifies the name of the runtime application container server (for example, xpagesruntime/runtimeserver).
      • Server ID file - lets you browse for the ID file location that contains the ID file that will be used during application staging (for example, C:\Domino\data\runtime-server.id).
      • Server ID password - specifies the optional password associated with the ID file that will be used during application staging.
    • Enable directory assistance for authentication - Checking this option lets you allow the runtime application server to use a Domino® user directory on the remote server as follows: 1) to authenticate Internet users against the credentials in the directory, 2) to resolve users during NAMELookup calls, and 3) to resolve members of groups when authorizing database access. In this portion of the panel you specify
      • Domain name - specifies the domain name of a Domino® directory on the remote server.
      • Domain directory - specifies the file name of a Domino® directory on the remote server.
  • XPages Runtime Environmental Variables - Lets you specify the special XPages Runtime environmental variables that will be set for this application. Refer to the appropriate section in this topic for more details on XPages Runtime environmental variables.
  • User Environmental Variables - Lets you specify your own custom environmental variables that will be set for this application.

The following example shows the contents of a manifest file for an XPages application that uses the built-in community XPages buildpack in Bluemix™:

---
applications:
- name: HelloWorld
  host: HelloWorld
  instances: 1
  memory: 512M
  timeout: 180
  buildpack: xpages_buildpack
  command: /app/launch_xpages_webcontainer
  env:
    APP_HOME_URL: /HelloWorld.nsf
    APP_PRELOAD_DB: HelloWorld.nsf
Note: Only advanced users should consider making changes to this file with the editor. This file is located in the deployment directory that you have created. For more detailed information on the properties supported and available for changing in the Bluemix™ application manifest, refer to the Bluemix™ documentation on the Bluemix™ site.

To access the IBM® Bluemix™ Manifest editor, open the Application Navigator for the Bluemix™ application in Domino® Designer and select Application Configuration > IBM Bluemix Manifest. Right-click the IBM Bluemix Manifest entry and select Open. The editor opens in the center editor pane.

Information about IBM® XPages for Bluemix™ runtime environment variables

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 runtime service 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 the XPages runtime environment variables section to let you set this group of environment variables to the desired value.

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

  • APP_HOME_URL
  • APP_PRELOAD_DB
  • APP_JVM_HEAPSIZE
  • APP_JAVA_POLICY_ALL_PERMISSION
  • APP_REDIRECT_TO_SSL

For more information on the XPages runtime environment variables, refer to the Using the IBM XPages for Bluemix runtime environment variables topic

Runtime environment variables for use with debugging applications

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

  • APP_INCLUDE_XPAGES_TOOLBOX
  • APP_VERBOSE_STAGING
  • APP_DEBUG_STAGING
  • APP_DEBUG_THREADS
  • APP_DEBUG_DIRECTORY_ASSISTANCE
  • APP_DEBUG_NAMELOOKUP

For more information on the XPages runtime environment variables, refer to the Using the IBM XPages for Bluemix runtime environment variables topic

Environment variables provided to support 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. These include the following:

  • APP_REMOTE_DATA_SERVER_ADDRESS
  • APP_REMOTE_DATA_SERVER_NAME
  • APP_RUNTIME_SERVER_NAME
  • APP_RUNTIME_SERVER_IDFILE
  • APP_DA_ENABLED
  • APP_DA_DOMAIN
  • APP_DA_ADDRESS_BOOK

For more information on the XPages runtime environment variables, refer to the Using the IBM XPages for Bluemix runtime environment variables topic

Additional editor information

In the Bluemix Manifest editor, there is also Hybrid Configuration editor page. This page lets you view and edit the hybrid configuration for the application. You can load any one of the hybrid profiles by clicking the Load hybrid profile button. This displays a dialog with the list of profiles and lets you choose the one you wish to load. The profile settings are then loaded to your manifest and the ID file is copied to your designated deployment directory. To remove all hybrid settings from the manifest, click the Delete this configuration button. Be aware that this delete option does not remove any previously copied ID file from the deployment directory. You must do that operation manually if it is required.

The editor also supports the Hosts and Domains options. These new options can be seen on the General page in the manifest editor. The Hosts option lets you specify multiple hostnames or subdomains. Each hostname generates a unique route for the application. The Domains option lets you specify specify multiple domains for the application.

Manifest Editor usage example

As mentioned, an editor is provided in Domino® Designer so that you can locally edit the advanced Bluemix™ properties found in the Bluemix™ manifest file (manifest.yml).

The steps presented next are provided as an example of how you would edit the manifest file to change the number of application instances. If your application was being used by a large number of users, you could increase the number of instances to spread and share the user load. This might be one reason why you might want to edit these properties.

  1. Open the Application Navigator for the Bluemix™ application in Domino® Designer and select Application Configuration > IBM Bluemix Manifest.
  2. Right-click the IBM Bluemix Manifest entry and select Open. The editor opens in the center editor pane.
  3. In the Staging Settings section of the Editor change the number in the Instances field to the number of application instances that you want to have staged.
  4. Save your application changes.

For more information on the advanced properties supported and available for changing in the Bluemix™ application manifest, refer to the Bluemix™ documentation on the Bluemix™ site.