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