Setting up MobileFirst Server on IBM Cloud using scripts for Liberty for Java

improve this page | report issue

Overview

Follow the instructions below to configure a MobileFirst Server instance on a Liberty for Java runtime on IBM Cloud. To achieve this you will go through the following steps:

  • Setup your host computer with the required tools (Cloud Foundry CLI)
  • Setup your IBM Cloud account
  • Build a MobileFirst Server and push it to the IBM Cloud as a Cloud Foundry application.

Finally, you will register your mobile apps as well as deploy your adapters.

Notes:

  • Windows OS is currently not supported for running these scripts.
  • The MobileFirst Server Configuration tools cannot be used for deployments to IBM Cloud.

Jump to:

Register an account at IBM Cloud

If you do not have an account yet, visit the IBM Cloud website and click Get Started Free or Sign Up. You need to fill up a registration form before you can move on to the next step.

The IBM Cloud Dashboard

After signing in to IBM Cloud, you are presented with the IBM Cloud Dashboard, which provides an overview of the active IBM Cloud space. By default, this work area receives the name “dev”. You can create multiple work areas/spaces if needed.

Set up your host machine

To manage the IBM Cloud Cloud Foundry app, you need to install the Cloud Foundry CLI.
You can run the scripts using the macOS Terminal.app or a Linux bash shell.

Install the Cloud Foundry CLI.

Download the ibm-mfpf-container-8.0.0.0 archive

To set up Mobile Foundation on Liberty on Java, you must first create a file layout that will later be pushed to IBM Cloud.
Follow the instructions in this page to download the MobileFirst Server 8.0 for IBM Containers archive (.zip file, search for: CNBL0EN).

The archive file contains the files for building an file layout (dependencies and mfpf-libs), the files for building and deploying a MobileFirst Analytics Container (mfpf-analytics) and files for configuring a MobileFirst Server Cloud Foundry app (mfpf-server-libertyapp).

Image showing the file system structure of the archive file

dependencies folder

Contains the Mobile Foundation runtime and IBM Java JRE 8.

mfpf-libs folder

Contains MobileFirst product component libraries and CLI.

mfpf-server-libertyapp folder

  • scripts folder: This folder contains the args folder, which contains a set of configuration files. It also contains scripts to run for logging into IBM Cloud, building a Mobile Foundation app for pushing to IBM Cloud and running the server on IBM Cloud. You can choose to run the scripts interactively or by preconfiguring the configuration files as is further explained later. Other than the customizable args/*.properties files, do not modify any elements in this folder. For script usage help, use the -h or --help command-line arguments (for example, scriptname.sh --help).
  • usr folder:
    • config folder: Contains the server configuration fragments (keystore, server properties, user registry) used by MobileFirst Server.
    • keystore.xml - the configuration of the repository of security certificates used for SSL encryption. The files listed must be referenced in the ./usr/security folder.
    • mfpfproperties.xml - configuration properties for MobileFirst Server. See the supported properties listed in these documentation topics:
    • registry.xml - user registry configuration. The basicRegistry (a basic XML-based user-registry configuration is provided as the default. User names and passwords can be configured for basicRegistry or you can configure ldapRegistry.
  • env folder: Contains the environment properties used for server initialization (server.env) and custom JVM options (jvm.options).
  • security folder: used to store the key store, trust store, and the LTPA keys files (ltpa.keys).

Setting Up the MobileFirst Server and MobileFirst Application Center

You can choose to run the scripts interactively or by using the configuration files: A good place to start is to run the scripts interactively once, which will also record the arguments (recorded-args). You can later use the args files to run the scripts in a non interactive mode.

Note: Passwords are not recorded and you will have to manually add the passwords to the argument files.

  • Using the configuration files - run the scripts and pass the respective configuration file as an argument.
  • Interactively - run the scripts without any arguments.

If you choose to run the scripts interactively, you can skip the configuration but it is strongly suggested to at least read and understand the arguments that you will need to provide.

MobileFirst Application Center

Note: You can download installers and DB tools from the on-premise MobileFirst Application Center installation folders (installer and tools folders).

The args folder contains a set of configuration files which contain the arguments that are required to run the scripts. You can find the empty template files and the explanation of the arguments in the args folder, or after running the scripts interactively in the recorded-args folder. Following are the files:

initenv.properties

This file contains properties used to run the environment initialization.

prepareappcenterdbs.properties

The MobileFirst Application Center requires an external dashDB Enterprise Transactional database instance (Any plan that is marked OLTP or Transactional).
Note: The deployment of the dashDB Enterprise Transactional plans is immediate for the plans marked "pay as you go". Make sure you pick one of the suitable plans like Enterprise for Transactions High Availability 2.8.500 (Pay per use)

After you have set up your dashDB instance, provide the required arguments.

prepareappcenter.properties

This file is used for the prepareappcenter.sh script. This prepares the Application Center file layout and pushes it to IBM Cloud as a Cloud Foundry app.

startappcenter.properties

This file configures tha runtime attributes of the server and starts is. It is strongly recomended that you use a minimum of 1024 MB (SERVER_MEM=1024) and 3 nodes for high availablilty (INSTANCES=3)

The following instructions demonstrate how to run the scripts by using the configuration files. A list of command-line arguments is also available should you choose to run without in interactive mode:

  1. initenv.sh – Logging in to IBM Cloud
    Run the initenv.sh script to login to IBM Cloud. Run this for the Org and space where your dashDB service is bound: 
    ./initenv.sh args/initenv.properties
    You an also pass the parameters on the commandline 
    initenv.sh --user IBM_Cloud_user_ID --password IBM_Cloud_password --org IBM_Cloud_organization_name --space IBM_Cloud_space_name
    To learn all the parameters supported and their documentation run the help option 
    ./initenv.sh --help
  2. prepareappcenterdbs.sh - Prepare the MobileFirst Application Center database
    The prepareappcenterdbs.sh script is used to configure your MobileFirst Application Center with the dashDB database service or a accessible DB2 database server. The DB2 option is usable particularly when you are running IBM Cloud local in the same datacentre where you have the DB2 server installed. If using the dashDB service, the service instance of the dashDB service should be available in the Organization and Space that you logged in to in step 1. Run the following: 
    ./prepareappcenterdbs.sh args/prepareappcenterdbs.properties
    You an also pass the parameters on the commandline 
    prepareappcenterdbs.sh --acdb MFPAppCenterDashDBService
    To learn all the parameters supported and their documentation run the help option 
    ./prepareappcenterdbs.sh --help
  3. initenv.sh(Optional) – Logging in to IBM Cloud
    This step is required only if you need to create your server in a different Organization and Space than where the dashDB service instance is available. If yes, then update the initenv.properties with the new Organization and Space where the containers have to be created (and started), and rerun the initenv.sh script: 
    ./initenv.sh args/initenv.properties
  4. prepareappcenter.sh - Prepare the MobileFirst Application Center
    Run the prepareappcenter.sh script in order to build a MobileFirst Application Center and push it to IBM Cloud as a Cloud Foundry application. To view all the Cloud Foundry applications and their URLs in the logged in Org and space, run: cf apps
    ./prepareappcenter.sh args/prepareappcenter.properties
    You an also pass the parameters on the commandline 
    prepareappcenter.sh --name APP_NAME
    To learn all the parameters supported and their documentation run the help option 
    ./prepareappcenter.sh --help
  5. startappcenter.sh - Starting the MobileFirst Application Center
    The startappcenter.sh script is used to start the MobileFirst Application Center on Liberty for Java Cloud Foundry application. Run:

    ./startappcenter.sh args/startappcenter.properties
    You an also pass the parameters on the commandline 
    ./startappcenter.sh --name APP_NAME
    To learn all the parameters supported and their documentation run the help option 
    ./startappcenter.sh --help

Launch the MobileFirst Application Center console by loading the following URL: http://APP_HOST.mybluemix.net/appcenterconsole (it may take a few moments).

With MobileFirst Application Center running on IBM Cloud, you can now upload your mobile apps to the application center.

MobileFirst Server

The args folder contains a set of configuration files which contain the arguments that are required to run the scripts. You can find the empty template files and the explanation of the arguments in the args folder, or after running the scripts interactively in the recorded-args folder. Following are the files:

initenv.properties

This file contains properties used to run the environment initialization.

prepareserverdbs.properties

The Mobile Foundation service requires an external dashDB Enterprise Transactional database instance (Any plan that is marked OLTP or Transactional).
Note: The deployment of the dashDB Enterprise Transactional plans is immediate for the plans marked "pay as you go". Make sure you pick one of the suitable plans like Enterprise for Transactions High Availability 2.8.500 (Pay per use)

After you have set up your dashDB instance, provide the required arguments.

prepareserver.properties

This file is used for the prepareserver.sh script. This prepares the server file layout and pushes it to IBM Cloud as a Cloud Foundry app.

startserver.properties

This file configures tha runtime attributes of the server and starts is. It is strongly recomended that you use a minimum of 1024 MB (SERVER_MEM=1024) and 3 nodes for high availablilty (INSTANCES=3)

The following instructions demonstrate how to run the scripts by using the configuration files. A list of command-line arguments is also available should you choose to run without in interactive mode:

  1. initenv.sh – Logging in to IBM Cloud
    Run the initenv.sh script to login to IBM Cloud. Run this for the Org and space where your dashDB service is bound: 
    ./initenv.sh args/initenv.properties
    You an also pass the parameters on the commandline 
    initenv.sh --user IBM_Cloud_user_ID --password IBM_Cloud_password --org IBM_Cloud_organization_name --space IBM_Cloud_space_name
    To learn all the parameters supported and their documentation run the help option 
    ./initenv.sh --help
  2. prepareserverdbs.sh - Prepare the MobileFirst Server database
    The prepareserverdbs.sh script is used to configure your MobileFirst Server with the dashDB database service or a accessible DB2 database server. The DB2 option is usable particularly when you are running IBM Cloud local in the same datacentre where you have the DB2 server installed. If using the dashDB service, the service instance of the dashDB service should be available in the Organization and Space that you logged in to in step 1. Run the following: 
    ./prepareserverdbs.sh args/prepareserverdbs.properties
    You an also pass the parameters on the commandline 
    prepareserverdbs.sh --admindb MFPDashDBService
    To learn all the parameters supported and their documentation run the help option 
    ./prepareserverdbs.sh --help
  3. initenv.sh(Optional) – Logging in to IBM Cloud
    This step is required only if you need to create your server in a different Organization and Space than where the dashDB service instance is available. If yes, then update the initenv.properties with the new Organization and Space where the containers have to be created (and started), and rerun the initenv.sh script: 
    ./initenv.sh args/initenv.properties
  4. prepareserver.sh - Prepare a MobileFirst Server
    Run the prepareserver.sh script in order to build a MobileFirst Server and push it to IBM Cloud as a Cloud Foundry application. To view all the Cloud Foundry applications and theur URLs in the logged in Org and space, run: cf apps
    ./prepareserver.sh args/prepareserver.properties
    You an also pass the parameters on the commandline 
    prepareserver.sh --name APP_NAME
    To learn all the parameters supported and their documentation run the help option 
    ./prepareserver.sh --help
  5. startserver.sh - Starting the server
    The startserver.sh script is used to start the MobileFirst Server on Liberty for Java Cloud Foundry application. Run:

    ./startserver.sh args/startserver.properties
    You an also pass the parameters on the commandline 
    ./startserver.sh --name APP_NAME
    To learn all the parameters supported and their documentation run the help option 
    ./startserver.sh --help

Launch the MobileFirst Operations Console by loading the following URL: http://APP_HOST.mybluemix.net/mfpconsole (it may take a few moments).
Add the remote server by following the instructions in the Using MobileFirst CLI to Manage MobileFirst Artifacts tutorial.

With MobileFirst Server running on IBM Cloud, you can now start your application development.

Applying changes

You may need to apply changes to the server layout after you have deployed the server once, e.g: you want to update the analytics URL in /usr/config/mfpfproperties.xml. Make the changes and then re-run the following scripts with the same set of arguments.

  1. ./prepareserver.sh
  2. ./startserver.sh

Adding analytics server configuration to MobileFirst Server

If you have setup a Analytics server and want to connect it to this MobileFirst Server then edit the fie mfpfproperties.xml in the folder package_root/mfpf-server-libertyapp/usr/config as specified below. Replace the tokens marked with <> with correct values from yur deployment.

<jndiEntry jndiName="${env.MFPF_RUNTIME_ROOT}/mfp.analytics.url" value='"https://<AnalyticsContainerGroupRoute>:443/analytics-service/rest"'/>
<jndiEntry jndiName="${env.MFPF_RUNTIME_ROOT}/mfp.analytics.console.url" value='"https://<AnalyticsContainerPublicRoute>:443/analytics/console"'/>
<jndiEntry jndiName="${env.MFPF_RUNTIME_ROOT}/mfp.analytics.username" value='"<AnalyticsUserName>"'/>
<jndiEntry jndiName="${env.MFPF_RUNTIME_ROOT}/mfp.analytics.password" value='"<AnalyticsPassword>"'/>


<jndiEntry jndiName="${env.MFPF_PUSH_ROOT}/mfp.push.analytics.endpoint" value='"https://<AnalyticsContainerGroupRoute>:443/analytics-service/rest"'/>
<jndiEntry jndiName="${env.MFPF_PUSH_ROOT}/mfp.push.services.ext.analytics" value="com.ibm.mfp.push.server.analytics.plugin.AnalyticsPlugin"/>
<jndiEntry jndiName="${env.MFPF_PUSH_ROOT}/mfp.push.analytics.user" value='"<AnalyticsUserName>"'/>
<jndiEntry jndiName="${env.MFPF_PUSH_ROOT}/mfp.push.analytics.password" value='"<AnalyticsPassword>"'/>

Applying MobileFirst Server Fixes

Interim fixes for the MobileFirst Server on IBM Cloud can be obtained from IBM Fix Central.
Before you apply an interim fix, back up your existing configuration files. The configuration files are located in the following folders:

  • MobileFirst Analytics: package_root/mfpf-analytics/usr
  • MobileFirst Server Liberty Cloud Foundry Application: package_root/mfpf-server-libertyapp/usr
  • Application Center: package_root/mfp-appcenter-libertyapp/usr

Steps to apply the iFix:

  1. Download the interim fix archive and extract the contents to your existing installation folder, overwriting the existing files.
  2. Restore your backed-up configuration files into the package_root/mfpf-analytics/usr, package_root/mfpf-server-libertyapp/usr and package_root/mfp-appcenter-libertyapp/usr folders, overwriting the newly installed configuration files.
  3. Edit package_root/mfpf-server/usr/env/jvm.options file in your editor and remove the following line, if it exists: 
    -javaagent:/opt/ibm/wlp/usr/servers/mfp/newrelic/newrelic.jar

    You can now build and deploy the updated server. Re-run the following scripts with the same set of arguments.

    a. ./prepareserver.sh to upload the updated artifacts to IBM Cloud.

    b. ./startserver.sh to start the updated server

    A copy of the the arguments that you used in your previous deployment would have been saved in recorded-args/ directory. You can use these properties for your deployment.

Removing the database service configuration from IBM Cloud

If you ran the prepareserverdbs.sh script during the configuration of the MobileFirst Server image, the configurations and database tables required for MobileFirst Server are created. This script also creates the database schema for the MobileFirst Server.

To remove the database service configuration from IBM Cloud, perform the following procedure using IBM Cloud dashboard.

  1. From the IBM Cloud dashboard, select the dashDB service you have used. Choose the dashDB service name that you had provided as parameter while running the prepareserverdbs.sh script.
  2. Launch the dashDB console to work with the schemas and database objects of the selected dashDB service instance.
  3. Select the schemas related to IBM MobileFirst Server configuration. The schema names are ones that you have provided as parameters while running the prepareserverdbs.sh script.
  4. Delete each of the schema after carefully inspecting the schema names and the objects under them. The database configurations are removed from IBM Cloud.

Similarly, if you ran the prepareappcenterdbs.sh while configuring MobileFirst Application Center then follow the steps above to remove the database service configuration in IBM Cloud.

▲
Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.
Last modified on October 30, 2019