Setting Up MobileFirst Server on IBM Bluemix using Scripts for IBM Containers

improve this page | report issue

Overview

Follow the instructions below to configure a MobileFirst Server instance as well as MobileFirst Analytics instance on IBM Bluemix. To achieve this you will go through the following steps:

  • Setup your host computer with the required tools (Cloud Foundry CLI, Docker, and IBM Containers Extension (cf ic) Plug-in)
  • Setup your Bluemix account
  • Build a MobileFirst Server image and push it to the Bluemix repository.

Finally, you will run the image on IBM Containers as a single Container or a Container group, and register your applications 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 Containers.

Jump to:

Register an account at Bluemix

If you do not have an account yet, visit the Bluemix 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 Bluemix Dashboard

After signing in to Bluemix, you are presented with the Bluemix Dashboard, which provides an overview of the active Bluemix 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 containers and images, you need to install the following tools: Docker, Cloud Foundry CLI, and IBM Containers (cf ic) Plug-in.

Docker

Go to the Docker Documentation on the left menu, select Install → Docker Engine, select your OS type, and follow the instructions to install the Docker Toolbox.

Note: IBM does not support Docker’s Kitematic.

In macOS, two options are available to run Docker commands:

  • From the macOS Terminal.app: No further setup is needed. You can work only from it.
  • From the Docker Quickstart Terminal: proceed as follows.

  • Run the command:

    docker-machine env default
    
  • Set the result as environment variables, for example:

    $ docker-machine env default
    export DOCKER_TLS_VERIFY="1"
    export DOCKER_HOST="tcp://192.168.99.101:2376"
    export DOCKER_CERT_PATH="/Users/mary/.docker/machine/machines/default"
    export DOCKER_MACHINE_NAME="default"
    

For further information consult the Docker documentation.

Cloud Foundry Plug-in and IBM Containers plug-in

  1. Install the Cloud Foundry CLI.
  2. Install the IBM Containers Plugin (cf ic).

Download the ibm-mfpf-container-8.0.0.0 archive

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

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

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 and mfpf-analytics folders

  • Dockerfile: Text document that contains all the commands that are necessary to build an image.
  • scripts folder: This folder contains the args folder, which contains a set of configuration files. It also contains scripts to run for logging into Bluemix, building a MobileFirst Server/MobileFirst Analytics image and for pushing and running the image on Bluemix. 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:
    • bin folder: Contains the script file that gets executed when the container starts. You can add your own custom code to be executed.
    • config folder: Contains the server configuration fragments (keystore, server properties, user registry) used by MobileFirst Server/MobileFirst Analytics.
    • 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 and MobileFirst Analytics. 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).

  • Property Default Value Description
    MFPF_SERVER_HTTPPORT 9080* The port used for client HTTP requests. Use -1 to disable this port.
    MFPF_SERVER_HTTPSPORT 9443* The port used for client HTTP requests secured with SSL (HTTPS). Use -1 to disable this port.
    MFPF_CLUSTER_MODE Standalone Configuration not required. Valid values are Standalone or Farm. The Farm value is automatically set when the container is run as a container group.
    MFPF_ADMIN_ROOT mfpadmin The context root at which the MobileFirst Server Administration Services are made available.
    MFPF_CONSOLE_ROOT mfpconsole The context root at which the MobileFirst Operations Console is made available.
    MFPF_ADMIN_GROUP mfpadmingroup The name of the user group assigned the predefined role mfpadmin.
    MFPF_DEPLOYER_GROUP mfpdeployergroup The name of the user group assigned the predefined role mfpdeployer.
    MFPF_MONITOR_GROUP mfpmonitorgroup The name of the user group assigned the predefined role mfpmonitor.
    MFPF_OPERATOR_GROUP mfpoperatorgroup The name of the user group assigned the predefined role mfpoperator.
    MFPF_SERVER_ADMIN_USER WorklightRESTUser The Liberty server administrator user for MobileFirst Server Administration Services.
    MFPF_SERVER_ADMIN_PASSWORD mfpadmin. Ensure that you change the default value to a private password before deploying to a production environment. The password of the Liberty server administrator user for MobileFirst Server Administration Services.
    MFPF_ADMIN_USER admin The user name for the administrator role for MobileFirst Server operations.
    MFPF_ADMIN_PASSWORD admin The password for the administrator role for MobileFirst Server operations.

    Property Default Value Description
    ANALYTICS_SERVER_HTTP PORT 9080* The port used for client HTTP requests. Use -1 to disable this port.
    ANALYTICS_SERVER_HTTPS PORT 9443* The port used for client HTTP requests. Use -1 to disable this port.
    ANALYTICS_ADMIN_GROUP analyticsadmingroup The name of the user group possessing the predefined role worklightadmin.

    </li>
  • jre-security folder: You can update the JRE security-related files (truststore, policy JAR files, and so on) by placing them in this folder. The files in this folder get copied to the JAVA_HOME/jre/lib/security/ folder in the container.
  • security folder: used to store the key store, trust store, and the LTPA keys files (ltpa.keys).
  • ssh folder: used to store the SSH public key file (id_rsa.pub), which is used to enable SSH access to the container.
  • wxs folder (only for MobileFirst Server): Contains the data cache / extreme-scale client library when Data Cache is used as an attribute store for the server.

Prerequisites

The below steps are mandatory as you will be running IBM Containers commands during the following section.

  1. Login to the IBM Bluemix environment.

    Run: cf login.
    When prompted, enter the following information:

    • Bluemix API endpoint
    • Email
    • Password
    • Organization, if you have more than one
    • Space, if you have more than one
  2. To run IBM Containers commands, you must first log in to the IBM Container Cloud Service.
    Run: cf ic login.

  3. Make sure that the namespace for container registry is set. The namespace is a unique name to identify your private repository on the Bluemix registry. The namespace is assigned once for an organization and cannot be changed. Choose a namespace according to following rules:

    • It can contain only lowercase letters, numbers, or underscores.
    • It can be 4 - 30 characters. If you plan to manage containers from the command line, you might prefer to have a short namespace that can be typed quickly.
    • It must be unique in the Bluemix registry.

    To set a namespace, run the command: cf ic namespace set <new_name>.
    To get the namespace that you have set, run the command: cf ic namespace get.

To learn more about IC commands, use the ic help command.

Setting Up the MobileFirst, Analytics Servers and Application Center on IBM Containers

As explained above, you can choose to run the scripts interactively or by using the configuration files:

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

Note: 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

If you intend to use MobileFirst Application Center start here.

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. Fill in the argument values in the following files.

initenv.properties

  • BLUEMIX_USER - Your Bluemix username (email).
  • BLUEMIX_PASSWORD - Your Bluemix password.
  • BLUEMIX_ORG - Your Bluemix organization name.
  • BLUEMIX_SPACE - Your Bluemix space (as explained previously).

prepareappcenterdbs.properties

The MobileFirst Application Center requires an external dashDB Enterprise Transactional database instance (Enterprise Transactional 2.8.500 or Enterprise Transactional 12.128.1400).

Note: The deployment of the dashDB Enterprise Transactional plans may not be immediate. You might be contacted by the Sales team before the deployment of the service.

After you have set up your dashDB instance, provide the following required arguments:
  • APPCENTER_DB_SRV_NAME - Your dashDB service instance name, for storing application center data
  • APPCENTER_SCHEMA_NAME - Your database schema name, used to store application center data.
  • Note: If your dashDB service instance is being shared by multiple users, ensure you provide unique schema names.

prepareappcenter.properties

  • SERVER_IMAGE_TAG - A tag for the image. Should be of the form: registry-url/namespace/your-tag.

startappcenter.properties

  • SERVER_IMAGE_TAG - Same as in prepareappcenter.sh.
  • SERVER_CONTAINER_NAME - A name for your Bluemix container.
  • SERVER_IP - An IP address that the Bluemix container should be bound to.
  • To assign an IP address, run: cf ic ip request. IP addresses can be reused in multiple containers in a given Bluemix space. If you have already assigned an IP, you can run: cf ic ip list.

startappcentergroup.properties

  • SERVER_IMAGE_TAG - Same as in prepareappcenter.sh.
  • SERVER_CONTAINER_GROUP_NAME - A name for your Bluemix container group.
  • SERVER_CONTAINER_GROUP_HOST - Your host name.
  • SERVER_CONTAINER_GROUP_DOMAIN - Your domain name. The default is: mybluemix.net.

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 Bluemix
    Run the initenv.sh script to create an environment for building and running Mobile Foundation on the IBM Containers:
    ./initenv.sh args/initenv.properties
    Command-line argument Description
    [-u|--user] BLUEMIX_USER Bluemix user ID or email address
    [-p|--password] BLUEMIX_PASSWORD Bluemix password
    [-o|--org] BLUEMIX_ORG Bluemix organization name
    [-s|--space] BLUEMIX_SPACE Bluemix space name
    Optional. [-a|--api] BLUEMIX_API_URL Bluemix API endpoint. (Defaults to https://api.ng.bluemix.net)

    For example:

    initenv.sh --user Bluemix_user_ID --password Bluemix_password --org Bluemix_organization_name --space Bluemix_space_name
  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. 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
    Command-line argument Description
    [-db | --acdb ] APPCENTER_DB_SRV_NAME Bluemix dashDB service (with Bluemix service plan of Enterprise Transactional).
    Optional: [-ds | --acds ] APPCENTER_SCHEMA_NAME Database schema name for Application Center service. Defaults to APPCNTR.

    For example:

    prepareappcenterdbs.sh --acdb AppCenterDashDBService
  3. initenv.sh (Optional) – Logging in to Bluemix
    This step is required only if you need to create your containers in an Organization and Space different from 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), rerun the initenv.sh script:
  4. ./initenv.sh args/initenv.properties
  5. prepareappcenter.sh - Prepare a MobileFirst Application Center image
    Run the prepareappcenter.sh script in order to build a MobileFirst Application Center image and push it to your Bluemix repository. To view all available images in your Bluemix repository, run: cf ic images The list contains the image name, date of creation, and ID. Run:
    ./prepareappcenter.sh args/prepareappcenter.properties
    Command-line argument Description
    [-t|--tag] SERVER_IMAGE_NAME Name to be used for the customized MobileFirst Application Center image. Format: registryUrl/namespace/imagename

    For example:

    prepareappcenter.sh --tag SERVER_IMAGE_NAME registryUrl/namespace/imagename
  6. startappcenter.sh - Running the image in an IBM Container
    The startappcenter.sh script in used in order to run the MobileFirst Application Center image in an IBM Container. It also binds your image to the public IP that you configured in the SERVER_IP property. Run:
    ./startappcenter.sh args/startappcenter.properties
    Command-line argument Description
    [-t|--tag] SERVER_IMAGE_TAG Name of the MobileFirst Application Center image.
    [-i|--ip] SERVER_IP IP address that the MobileFirst Application Center container should be bound to. (You can provide an available public IP or request one using the cf ic ip request command.)
    Optional: [-si|--services] SERVICE_INSTANCES Comma-separated Bluemix service instances that you want to bind to the container.
    Optional: [-h|--http] EXPOSE_HTTP Expose HTTP Port. Accepted values are Y (default) or N.
    Optional: [-s|--https] EXPOSE_HTTPS Expose HTTPS Port. Accepted values are Y (default) or N.
    Optional: [-m|--memory] SERVER_MEM Assign a memory size limit to the container in megabytes (MB). Accepted values are 1024 MB (default) and 2048 MB.
    Optional: [-se|--ssh] SSH_ENABLE Enable SSH for the container. Accepted values are Y (default) or N.
    Optional: [-sk|--sshkey] SSH_KEY The SSH Key to be injected into the container. (Provide the contents of your id_rsa.pub file.)
    Optional: [-tr|--trace] TRACE_SPEC The trace specification to be applied. Default: *=info
    Optional: [-ml|--maxlog] MAX_LOG_FILES The maximum number of log files to maintain before they are overwritten. The default is 5 files.
    Optional: [-ms|--maxlogsize] MAX_LOG_FILE_SIZE The maximum size of a log file. The default size is 20 MB.
    Optional: [-v|--volume] ENABLE_VOLUME Enable mounting volume for container logs. Accepted values are Y or N (default).

    For example:

    startappcenter.sh --tag image_tag_name --name container_name --ip container_ip_address
  7. startappcentergroup.sh - Running the image on an IBM Container group
    The startappcentergroup.sh script is used to run the MobileFirst Application Center image on an IBM Container group. It also binds your image to the host name that you configured in the SERVER_CONTAINER_GROUP_HOST property. Run:
    ./startappcentergroup.sh args/startappcentergroup.properties
    Command-line argument Description
    [-t|--tag] SERVER_IMAGE_TAG The name of the MobileFirst Application Center container image in the Bluemix registry.
    [-gn|--name] SERVER_CONTAINER_NAME The name of the MobileFirst Application Center container group.
    [-gh|--host] SERVER_CONTAINER_GROUP_HOST The host name of the route.
    [-gs|--domain] SERVER_CONTAINER_GROUP_DOMAIN The domain name of the route.
    Optional: [-gm|--min] SERVERS_CONTAINER_GROUP_MIN The minimum number of container instances. The default value is 1.
    Optional: [-gx|--max] SERVER_CONTAINER_GROUP_MAX The maximum number of container instances. The default value is 2.
    Optional: [-gd|--desired] SERVER_CONTAINER_GROUP_DESIRED The desired number of container instances. The default value is 1.
    Optional: [-a|--auto] ENABLE_AUTORECOVERY Enable the automatic recovery option for the container instances. Accepted values are Y or N (default).
    Optional: [-si|--services] SERVICES Comma-separated Bluemix service instance names that you want to bind to the container.
    Optional: [-tr|--trace] TRACE_SPEC The trace specification to be applied. Default </code>*=info</code>.
    Optional: [-ml|--maxlog] MAX_LOG_FILESC The maximum number of log files to maintain before they are overwritten. The default is 5 files.
    Optional: [-ms|--maxlogsize] MAX_LOG_FILE_SIZE The maximum size of a log file. The default size is 20 MB.
    Optional: [-m|--memory] SERVER_MEM Assign a memory size limit to the container in megabytes (MB). Accepted values are 1024 MB (default) and 2048 MB.
    Optional: [-v|--volume] ENABLE_VOLUME Enable mounting volume for container logs. Accepted values are Y or N (default).

    For example:

    startappcentergroup.sh --tag image_name --name container_group_name --host container_group_host_name --domain container_group_domain_name

MobileFirst Analytics

If you intend to use analytics with your MobileFirst Server start here.

The args folder contains a set of configuration files which contain the arguments that are required to run the scripts. Fill in the argument values in the following files.
Note: We only include the required arguments. To learn about the additional arguments, see the documentation inside the properties files.

initenv.properties

  • BLUEMIX_USER - Your Bluemix username (email).
  • BLUEMIX_PASSWORD - Your Bluemix password.
  • BLUEMIX_ORG - Your Bluemix organization name.
  • BLUEMIX_SPACE - Your Bluemix space (as explained previously).

prepareanalytics.properties

  • ANALYTICS_IMAGE_TAG - A tag for the image. Should be of the form: registry-url/namespace/your-tag.

startanalytics.properties

  • ANALYTICS_IMAGE_TAG - Same as in prepareserver.sh.
  • ANALYTICS_CONTAINER_NAME - A name for your Bluemix Container.
  • ANALYTICS_IP - An IP address that the Bluemix Container should be bound to.
    To assign an IP address, run: cf ic ip request.
    IP addresses can be reused in multiple containers in a space.
    If you've already assigned one, you can run: cf ic ip list.

startanalyticsgroup.properties

  • ANALYTICS_IMAGE_TAG - Same as in prepareserver.sh.
  • ANALYTICS_CONTAINER_GROUP_NAME - A name for your Bluemix Container group.
  • ANALYTICS_CONTAINER_GROUP_HOST - Your host name.
  • ANALYTICS_CONTAINER_GROUP_DOMAIN - Your domain name. The default is: mybluemix.net.

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 Bluemix
    Run the initenv.sh script to create an environment for building and running MobileFirst Analytics on the IBM Containers:
    ./initenv.sh args/initenv.properties
    Command-line argument Description
    [-u|--user] BLUEMIX_USER Bluemix user ID or email address
    [-p|--password] BLUEMIX_PASSWORD Bluemix password
    [-o|--org] BLUEMIX_ORG Bluemix organization name
    [-s|--space] BLUEMIX_SPACE Bluemix space name
    Optional. [-a|--api] BLUEMIX_API_URL Bluemix API endpoint. (Defaults to https://api.ng.bluemix.net)

    For example:

    initenv.sh --user Bluemix_user_ID --password Bluemix_password --org Bluemix_organization_name --space Bluemix_space_name
  2. prepareanalytics.sh - Prepare a MobileFirst Analytics image
    Run the prepareanalytics.sh script to build a MobileFirst Analytics image and push it to your Bluemix repository:
    ./prepareanalytics.sh args/prepareanalytics.properties
    To view all available images in your Bluemix repository run: cf ic images
    The list contains the image name, date of creation, and ID.
    Command-line argument Description
    [-t|--tag] ANALYTICS_IMAGE_TAG Name to be used for the customized analytics image. Format: Bluemix registry URL/private namespace/image name

    For example:

    prepareanalytics.sh --tag registry.ng.bluemix.net/your_private_repository_namespace/mfpfanalytics80
  3. startanalytics.sh - Running the image on an IBM Container
    The startanalytics.sh script is used to run the MobileFirst Analytics image on an IBM Container. It also binds your image to the public IP that you configured in the ANALYTICS_IP property.
  4. Run:
    ./startanalytics.sh args/startanalytics.properties
    Command-line argument Description
    [-t|--tag] ANALYTICS_IMAGE_TAG Name of the analytics container image that has been loaded into the IBM Containers registry. Format: BluemixRegistry/PrivateNamespace/ImageName:Tag
    [-n|--name] ANALYTICS_CONTAINER_NAME Name of the analytics container
    [-i|--ip] ANALYTICS_IP IP address that the container should be bound to. (You can provide an available public IP or request one using the cf ic ip request command.)
    Optional. [-h|--http] EXPOSE_HTTP Expose HTTP port. Accepted values are Y (default) or N.
    Optional. [-s|--https] EXPOSE_HTTPS Expose HTTPS port. Accepted values are Y (default) or N.
    Optional. [-m|--memory] SERVER_MEM Assign a memory size limit to the container in megabytes (MB). Accepted values are 1024 MB (default) and 2048 MB.
    Optional. [-se|--ssh] SSH_ENABLE Enable SSH for the container. Accepted values are Y (default) or N.
    Optional. [-sk|--sshkey] SSH_KEY The SSH Key to be injected into the container. (Provide the contents of your id_rsa.pub file.)
    Optional. [-tr|--trace] TRACE_SPEC The trace specification to be applied. Default: *=info
    Optional. [-ml|--maxlog] MAX_LOG_FILES The maximum number of log files to maintain before they are overwritten. The default is 5 files.
    Optional. [-ms|--maxlogsize] MAX_LOG_FILE_SIZE The maximum size of a log file. The default size is 20 MB.
    Optional. [-v|--volume] ENABLE_VOLUME Enable mounting volume for container logs. Accepted values are Y or N (default).
    Optional. [-ev|--enabledatavolume] ENABLE_ANALYTICS_DATA_VOLUME Enable mounting volume for analytics data. Accepted values are Y or N (default).
    Optional. [-av|--datavolumename] ANALYTICS_DATA_VOLUME_NAME Specify the name of the volume to be created and mounted for the analytic data. The default name is mfpf_analytics_container_name.
    Optional. [-ad|--analyticsdatadirectory] ANALYTICS_DATA_DIRECTORY Specify the location to store the data. The default folder name is /analyticsData.
    Optional. [-e|--env] MFPF_PROPERTIES Provide MobileFirst Analytics properties as comma-separated key:value pairs. Note: If you specify properties using this script, ensure that these same properties have not been set in the configuration files in the usr/config folder.

    For example:

                            startanalytics.sh --tag image_tag_name --name container_name --ip container_ip_address
                            
  5. startanalyticsgroup.sh - Running the image on an IBM Container group
    The startanalyticsgroup.sh script is used to run the MobileFirst Analytics image on an IBM Container group. It also binds your image to the host name that you configured in the ANALYTICS_CONTAINER_GROUP_HOST property. Run:
    ./startanalyticsgroup.sh args/startanalyticsgroup.properties
    Command-line argument Description
    [-t|--tag] ANALYTICS_IMAGE_TAG Name of the analytics container image that has been loaded into the IBM Containers registry. Format: BluemixRegistry/PrivateNamespace/ImageName:Tag
    [-gn|--name] ANALYTICS_CONTAINER_GROUP_NAME The name of the analytics container group.
    [-gh|--host] ANALYTICS_CONTAINER_GROUP_HOST The host name of the route.
    [-gs|--domain] ANALYTICS_CONTAINER_GROUP_DOMAIN The domain name of the route.
    Optional. [-gm|--min] ANALYTICS_CONTAINER_GROUP_MIN The minimum number of container instances. The default value is 1.
    Optional. [-gx|--max] ANALYTICS_CONTAINER_GROUP_MAX The maximum number of container instances. The default value is 1.
    Optional. [-gd|--desired] ANALYTICS_CONTAINER_GROUP_DESIRED The desired number of container instances. The default value is 2.
    Optional. [-tr|--trace] TRACE_SPEC The trace specification to be applied. Default: *=info
    Optional. [-ml|--maxlog] MAX_LOG_FILES The maximum number of log files to maintain before they are overwritten. The default is 5 files.
    Optional. [-ms|--maxlogsize] MAX_LOG_FILE_SIZE The maximum size of a log file. The default size is 20 MB.
    Optional. [-e|--env] MFPF_PROPERTIES Specify MobileFirst properties as comma-separated key:value pairs. Example: mfp.analytics.url:http://127.0.0.1/analytics-service/rest/v2
    Optional. [-m|--memory] SERVER_MEM Assign a memory size limit to the container in megabytes (MB). Accepted values are 1024 MB (default) and 2048 MB.
    Optional. [-v|--volume] ENABLE_VOLUME Enable mounting volume for container logs. Accepted values are Y or N (default).
    Optional. [-av|--datavolumename] ANALYTICS_DATA_VOLUME_NAME Specify name of the volume to be created and mounted for analytics data. Default value is mfpf_analytics_ANALYTICS_CONTAINER_GROUP_NAME
    Optional. [-ad|--analyticsdatadirectory] ANALYTICS_DATA_DIRECTORY Specify the directory to be used for storing analytics data. Default value is /analyticsData

    For example:

    startanalyticsgroup.sh --tag image_name --name container_group_name --host container_group_host_name --domain container_group_domain_name
Launch the Analytics Console by loading the following URL: http://ANALYTICS-CONTAINER-HOST/analytics/console (it may take a few moments).

MobileFirst Server

The args folder contains a set of configuration files which contain the arguments that are required to run the scripts. Fill in the argument values in the following files:

initenv.properties

  • BLUEMIX_USER - Your Bluemix username (email).
  • BLUEMIX_PASSWORD - Your Bluemix password.
  • BLUEMIX_ORG - Your Bluemix organization name.
  • BLUEMIX_SPACE - Your Bluemix space (as explained previously).

prepareserverdbs.properties

The Mobile Foundation service requires an external dashDB Enterprise Transactional database instance (Enterprise Transactional 2.8.500 or Enterprise Transactional 12.128.1400).
Note: The deployment of the dashDB Enterprise Transactional plans may not be immediate. You might be contacted by the Sales team before the deployment of the service.

After you have set up your dashDB instance, provide the required arguments:
  • ADMIN_DB_SRV_NAME - Your dashDB service instance name for storing admin data.
  • ADMIN_SCHEMA_NAME - Your schema name for admin data. The default is MFPDATA.
  • RUNTIME_DB_SRV_NAME - Your dashDB service instance name for storing runtime data. The default is the admin service name.
  • RUNTIME_SCHEMA_NAME - Your schema name for runtime data. The default is MFPDATA.
  • Note: If your dashDB service instance is being shared by many users, make sure that you provide unique schema names.

prepareserver.properties

  • SERVER_IMAGE_TAG - A tag for the image. Should be of the form: registry-url/namespace/your-tag.

startserver.properties

  • SERVER_IMAGE_TAG - Same as in prepareserver.sh.
  • SERVER_CONTAINER_NAME - A name for your Bluemix Container.
  • SERVER_IP - An IP address that the Bluemix Container should be bound to.
    To assign an IP address, run: cf ic ip request.
    IP addresses can be reused in multiple containers in a space.
    If you've already assigned one, you can run: cf ic ip list.
  • MFPF_PROPERTIES - MobileFirst Server JNDI properties separated by comma (without spaces). Here is where you define the analytics-related properties: MFPF_PROPERTIES=mfp/mfp.analytics.url:http://ANALYTICS-CONTAINER-IP:9080/analytics-service/rest,mfp/mfp.analytics.console.url:http://ANALYTICS-CONTAINER-IP:9080/analytics/console,mfp/mfp.analytics.username:ANALYTICS_USERNAME,mfp/mfp.analytics.password:ANALYTICS_PASSWORD

startservergroup.properties

  • SERVER_IMAGE_TAG - Same as in prepareserver.sh.
  • SERVER_CONTAINER_GROUP_NAME - A name for your Bluemix Container group.
  • SERVER_CONTAINER_GROUP_HOST - Your host name.
  • SERVER_CONTAINER_GROUP_DOMAIN - Your domain name. The default is: mybluemix.net.
  • MFPF_PROPERTIES - MobileFirst Server JNDI properties, separated by commas (without spaces). Here is where you define the analytics-related properties: MFPF_PROPERTIES=mfp/mfp.analytics.url:http://ANALYTICS_CONTAINER_GROUP_HOSTNAME:80/analytics-service/rest,mfp/mfp.analytics.console.url:http://ANALYTICS_CONTAINER_GROUP_HOSTNAME:80/analytics/console,mfp/mfp.analytics.username:ANALYTICS_USERNAME,mfp/mfp.analytics.password:ANALYTICS_PASSWORD

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 Bluemix
    Run the initenv.sh script to create an environment for building and running Mobile Foundation on IBM Containers:
    ./initenv.sh args/initenv.properties
    Command-line argument Description
    [-u|--user] BLUEMIX_USER Bluemix user ID or email address
    [-p|--password] BLUEMIX_PASSWORD Bluemix password
    [-o|--org] BLUEMIX_ORG Bluemix organization name
    [-s|--space] BLUEMIX_SPACE Bluemix space name
    Optional. [-a|--api] BLUEMIX_API_URL Bluemix API endpoint. (Defaults to https://api.ng.bluemix.net)

    For example:

    initenv.sh --user Bluemix_user_ID --password Bluemix_password --org Bluemix_organization_name --space Bluemix_space_name
  2. prepareserverdbs.sh - Prepare the MobileFirst Server database
    The prepareserverdbs.sh script is used to configure your MobileFirst Server with the dashDB database 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
    Command-line argument Description
    [-adl |--admindb ] ADMIN_DB_SRV_NAME Bluemix dashDB™ service (with Bluemix service plan of Enterprise Transactional)
    Optional. [-as |--adminschema ] ADMIN_SCHEMA_NAME Database schema name for administration service. Defaults to MFPDATA
    Optional. [-rd |--runtimedb ] RUNTIME_DB_SRV_NAME Bluemix database service instance name for storing runtime data. Defaults to the same service as given for admin data.
    Optional. [-p |--push ] ENABLE_PUSH Enable configuring database for push service. Accepted values are Y (default) or N.
    [-pd |--pushdb ] PUSH_DB_SRV_NAME Bluemix database service instance name for storing push data. Defaults to the same service as given for runtime data.
    [-ps |--pushschema ] PUSH_SCHEMA_NAME Database schema name for push service. Defaults to the runtime schema name.

    For example:

    prepareserverdbs.sh --admindb MFPDashDBService
  3. initenv.sh(Optional) – Logging in to Bluemix
    This step is required only if you need to create your containers 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 image
    Run the prepareserver.sh script in order to build a MobileFirst Server image and push it to your Bluemix repository. To view all available images in your Bluemix repository, run: cf ic images
    The list contains the image name, date of creation, and ID.
    ./prepareserver.sh args/prepareserver.properties
    Command-line argument Description
    [-t|--tag] SERVER_IMAGE_NAME Name to be used for the customized MobileFirst Server image. Format: registryUrl/namespace/imagename

    For example:

    prepareserver.sh --tag SERVER_IMAGE_NAME registryUrl/namespace/imagename

  5. startserver.sh - Running the image on an IBM Container
    The startserver.sh script is used to run the MobileFirst Server image on an IBM Container. It also binds your image to the public IP that you configured in the SERVER_IP property. Run:
  6. ./startserver.sh args/startserver.properties
    Command-line argument Description
    [-t|--tag] SERVER_IMAGE_TAG Name of the MobileFirst Server image.
    [-i|--ip] SERVER_IP IP address that the MobileFirst Server container should be bound to. (You can provide an available public IP or request one using the cf ic ip request command.)
    Optional. [-si|--services] SERVICE_INSTANCES Comma-separated Bluemix service instances that you want to bind to the container.
    Optional. [-h|--http] EXPOSE_HTTP Expose HTTP Port. Accepted values are Y (default) or N.
    Optional. [-s|--https] EXPOSE_HTTPS Expose HTTPS Port. Accepted values are Y (default) or N.
    Optional. [-m|--memory] SERVER_MEM Assign a memory size limit to the container in megabytes (MB). Accepted values are 1024 MB (default) and 2048 MB.
    Optional. [-se|--ssh] SSH_ENABLE Enable SSH for the container. Accepted values are Y (default) or N.
    Optional. [-sk|--sshkey] SSH_KEY The SSH Key to be injected into the container. (Provide the contents of your id_rsa.pub file.)
    Optional. [-tr|--trace] TRACE_SPEC The trace specification to be applied. Default: *=info
    Optional. [-ml|--maxlog] MAX_LOG_FILES The maximum number of log files to maintain before they are overwritten. The default is 5 files.
    Optional. [-ms|--maxlogsize] MAX_LOG_FILE_SIZE The maximum size of a log file. The default size is 20 MB.
    Optional. [-v|--volume] ENABLE_VOLUME Enable mounting volume for container logs. Accepted values are Y or N (default).
    Optional. [-e|--env] MFPF_PROPERTIES Specify MobileFirst properties as comma-separated key:value pairs. Example: mfp.analytics.url:http://127.0.0.1/analytics-service/rest,mfp.analytics.console.url:http://127.0.0.1/analytics/console. Note: If you specify properties using this script, ensure that these same properties have not been set in the configuration files in the usr/config folder.

    For example:

    startserver.sh --tag image_tag_name --name container_name --ip container_ip_address

  7. startservergroup.sh - Running the image on an IBM Container group
    The startservergroup.sh script is used to run the MobileFirst Server image on an IBM Container group. It also binds your image to the host name that you configured in the SERVER_CONTAINER_GROUP_HOST property.
  8. Run:
    ./startservergroup.sh args/startservergroup.properties
    Command-line argument Description
    [-t|--tag] SERVER_IMAGE_TAG The name of the MobileFirst Server container image in the Bluemix registry.
    [-gn|--name] SERVER_CONTAINER_NAME The name of the MobileFirst Server container group.
    [-gh|--host] SERVER_CONTAINER_GROUP_HOST The host name of the route.
    [-gs|--domain] SERVER_CONTAINER_GROUP_DOMAIN The domain name of the route.
    Optional. [-gm|--min] SERVERS_CONTAINER_GROUP_MIN The minimum number of container instances. The default value is 1.
    Optional. [-gx|--max] SERVER_CONTAINER_GROUP_MAX The maximum number of container instances. The default value is 1.
    Optional. [-gd|--desired] SERVER_CONTAINER_GROUP_DESIRED The desired number of container instances. The default value is 2.
    Optional. [-a|--auto] ENABLE_AUTORECOVERY Enable the automatic recovery option for the container instances. Accepted values are Y or N (default).
    Optional. [-si|--services] SERVICES Comma-separated Bluemix service instance names that you want to bind to the container.
    Optional. [-tr|--trace] TRACE_SPEC The trace specification to be applied. Default *=info
    Optional. [-ml|--maxlog] MAX_LOG_FILES The maximum number of log files to maintain before they are overwritten. The default is 5 files.
    Optional. [-ms|--maxlogsize] MAX_LOG_FILE_SIZE The maximum size of a log file. The default size is 20 MB.
    Optional. [-e|--env] MFPF_PROPERTIES Specify MobileFirst properties as comma-separated key:value pairs. Example: mfp.analytics.url:http://127.0.0.1/analytics-service/rest
    mfp.analytics.console.url:http://127.0.0.1/analytics/console
    Note: If you specify properties using this script, ensure that the same properties have not been set in the configuration files in the usr/config folder.
    Optional. [-m|--memory] SERVER_MEM Assign a memory size limit to the container in megabytes (MB). Accepted values are 1024 MB (default) and 2048 MB.
    Optional. [-v|--volume] ENABLE_VOLUME Enable mounting volume for container logs. Accepted values are Y or N (default).

    For example:

    startservergroup.sh --tag image_name --name container_group_name --host container_group_host_name --domain container_group_domain_name

Note: Containers must be restarted after any configuration changes have been made (cf ic restart containerId). For container groups, you must restart each container instance within the group. For example, if a root certificate changes, each container instance must be restarted after the new certificate has been added.

Launch the MobileFirst Operations Console by loading the following URL: http://MF_CONTAINER_HOST/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 Bluemix, you can now start your application development. Review the Mobile Foundation tutorials.

Port number limitation

There is currently an IBM Containers limitation with the port numbers that are available for public domain. Therefore, the default port numbers given for the MobileFirst Analytics container and the MobileFirst Server container (9080 for HTTP and 9443 for HTTPS) cannot be altered. Containers in a container group must use HTTP port 9080. Container groups do not support the use of multiple port numbers or HTTPS requests.

Applying MobileFirst Server Fixes

Interim fixes for the MobileFirst Server on IBM Containers 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 the following folders:

  • MobileFirst Analytics: package_root/mfpf-analytics/usr
  • MobileFirst Server Liberty Cloud Foundry Application: package_root/mfpf-server/usr
  • Application Center: package_root/mfp-appcenter/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/usr and package_root/mfp-appcenter/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.

    a. Run the prepareserver.sh script to rebuild the server image and push it to the IBM Containers service.

    b. Run the startserver.sh script to run the server image as a standalone container or startservergroup.sh to run the server image as a container group.

Removing a Container from Bluemix

When you remove a container from Bluemix, you must also remove the image name from the registry.
Run the following commands to remove a container from Bluemix:

  1. cf ic ps (Lists the containers currently running)
  2. cf ic stop container_id (Stops the container)
  3. cf ic rm container_id (Removes the container)

Run the following cf ic commands to remove an image name from the Bluemix registry:

  1. cf ic images (Lists the images in the registry)
  2. cf ic rmi image_id (Removes the image from the registry)

Removing the database service configuration from Bluemix

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

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

  1. From the Bluemix 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 Bluemix.

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

Last modified on July 20, 2017