Setting Up MobileFirst Server on IBM Bluemix Kubernetes Cluster
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:
- Create a Kubernetes Cluster of type: Standard (paid cluster).
- Setup your host computer with the required tools (Docker, Cloud Foundry CLI ( cf ), Bluemix CLI ( bx ), Container Service Plugin for Bluemix CLI ( bx cs ), Container Registry Plugin for Bluemix CLI ( bx cr ), Kubernetes CLI (kubectl)).
- Build a MobileFirst Server Docker image and push it to the Bluemix repository.
- Finally, you will run the Docker image on a Kubernetes Cluster.
- Windows OS is currently not supported for running these scripts.
- The MobileFirst Server Configuration tools cannot be used for deployments to IBM Containers.
- Register an account on Bluemix
- Set up your host machine
- Create and setup a Kubernetes Cluster with IBM Bluemix Container Service
- Download the ibm-mfpf-container-220.127.116.11 archive
- Setting Up the MobileFirst and Analytics Servers on Kubernetes Cluster with IBM Containers
- Applying MobileFirst Server Fixes
- Removing the container from Bluemix
- Removing the Kubernetes deployments from Bluemix
- Removing the database service configuration from Bluemix
Register an account on 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:
- Bluemix CLI (bx)
- Container Service Plugin for Bluemix CLI ( bx cs )
- Container Registry Plugin for Bluemix CLI ( bx cr )
- Kubernetes CLI (kubectl)
Refer to the Bluemix documentation for steps to setup the prerequisite CLIs.
Create and setup a Kubernetes Cluster with IBM Bluemix Container Service
Refer to the Bluemix documentation to setup a Kubernetes Cluster on Bluemix.
Note: Kubernetes Cluster Type: Standard (paid cluster) is required for deploying Mobile Foundation.
Download the ibm-mfpf-container-18.104.22.168 archive
To set up Mobile Foundation as a Kubernetes Cluster using Bluemix containers, you must first create an image that will later be pushed to Bluemix.
Interim fixes for the MobileFirst Server on IBM Containers can be obtained from the IBM Fix Central.
Download the latest interim fix from Fix central. Kubernetes support is available from iFix 22.214.171.124-IF201707051849.
The archive file contains the files for building an image (dependencies and mfpf-libs) and the files for building and deploying a MobileFirst Server and MobileFirst Analytics on Kubernetes (bmx-kubenetes).
Contains the customization files and scripts required to deploy to a Kubernetes Cluster with IBM Bluemix Container Service.
Dockerfile-mfpf-analytics and Dockerfile-mfpf-server
- Dockerfile-mfpf-server: Text document that contains all the commands that are necessary to build the MobileFirst Server image.
- Dockerfile-mfpf-analytics: Text document that contains all the commands that are necessary to build the MobileFirst Analytics image.
- scripts folder: This folder contains the args folder, which contains a set of configuration files. It also contains scripts required to log 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 pre-configuring the configuration files, explained later. Other than the customizable args/*.properties files, do not modify any elements in this folder. For script usage help, use the
--helpcommand-line arguments (for example,
- usr-mfpf-server and usr-mfpf-analytics folders:
- bin folder: Contains the script file (mfp-init) 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.
- ltpa.xml - the configuration file defining the LTPA key and its password.
- mfpfproperties.xml - configuration properties for MobileFirst Server and MobileFirst Analytics. See the supported properties listed in these documentation topics:
- mfpfsqldb.xml - JDBC Data source definition to connect to the DB2 or dashDB database.
- 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.
- tracespec.xml - Trace specification to enable debugging as well as logging levels.
- 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).
- env folder: Contains the environment properties used for server initialization (server.env) and custom JVM options (jvm.options).
- dependencies folder: Contains the Mobile Foundation runtime and IBM Java JRE 8.
- mfpf-libs folder folder: Contains MobileFirst product component libraries and CLI.
|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_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
|MFPF_DEPLOYER_GROUP||mfpdeployergroup||The name of the user group assigned the predefined role
|MFPF_MONITOR_GROUP||mfpmonitorgroup||The name of the user group assigned the predefined role
|MFPF_OPERATOR_GROUP||mfpoperatorgroup||The name of the user group assigned the predefined role
|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.|
|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.|
You need to have a working knowledge of Kubernetes. Refer to Kubernetes docs, to learn more.
Setting Up the MobileFirst and Analytics Servers on Kubernetes Cluster with 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 read and understand the arguments that you will need to provide.
When you run interactively, a copy of the arguments provided is saved in a directory:
./recorded-args/. So you can use the interactive mode for the first time and reuse the property files as a reference for future deployments.
- BLUEMIX_API_URL - The geo or region where you want your deployment.
For example: api.ng.bluemix.net for US region or api.eu-de.bluemix.net for Germany or api.au-syd.bluemix.net for Sydney
- BLUEMIX_ACCOUNT_ID - Your account id, which is an alpha-numeric value such as a1b1b111d11e1a11d1fa1cc999999999
Use the command
bx targetto get the Account id.
- 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.propertiesThe Mobile Foundation service requires an external DB2 on cloud instance.
Note: You can also use your own DB2 database. The Bluemix Kubenetes Cluster should be configured to connect to the database.After you have set up your DB2 instance, provide the required arguments:
- DB_TYPE - dashDB ( if you are using DB2 on Cloud ) or DB2 if you are using your own DB2 database.
- Provide the following if you are using your own DB2 database (i.e. DB_TYPE=DB2).
- DB2_HOST - hostname of your DB2 setup.
- DB2_DATABASE - name of the database.
- DB2_PORT - port on which you will connect to the database.
- DB2_USERNAME - the DB2 database user ( the user should have the permissions to create Tables within the schema provided or if the schema does not already exist, the user should be able to create a schema )
- DB2_PASSWORD - DB2 user's password.
- Provide the following if you are using DB2 on Cloud (i.e DB_TYPE=dashDB).
- ADMIN_DB_SRV_NAME - Your dashDB service instance name for storing admin data.
- RUNTIME_DB_SRV_NAME - Your dashDB service instance name for storing runtime data. The default is the admin service name.
- PUSH_DB_SRV_NAME - Your dashDB service instance name for storing runtime data. The default is the admin service name.
- ADMIN_SCHEMA_NAME - Your schema name for admin data. The default is MFPDATA.
- RUNTIME_SCHEMA_NAME - Your schema name for runtime data. The default is MFPDATA.
- PUSH_SCHEMA_NAME - Your schema name for runtime data. The default is MFPDATA.
Note: If your DB2 database service instance is being shared by many users or by multiple Mobile Foundation deployments, make sure that you provide unique schema names.
- SERVER_IMAGE_TAG - A tag for the image. Should be of the form: registry-url/namespace/image:tag.
- ANALYTICS_IMAGE_TAG - A tag for the image. Should be of the form: registry-url/namespace/image:tag.
bx cr namespace-add myuniquenamespace
bx cr namespace-list
For example: registry.ng.bluemix.net/myuniquenamespace/mymfpserver:v1
If you have not yet created a docker registry namespace, create the registry namespace using one of these commands:
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 in a non-interactive mode:
- initenv.sh – Logging in to Bluemix
Run the initenv.sh script to create an environment for building and running Mobile Foundation on IBM Containers: Interactive Mode Non-interactive Mode
- prepareserverdbs.sh - Prepare the MobileFirst Server database
The prepareserverdbs.sh script is used to configure your MobileFirst Server with the DB2 database service. The service instance of the DB2 service should be available in the Organization and Space that you logged in to in step 1. Run the following: Interactive Mode Non-interactive Mode
- 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 DB2 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:
- prepareserver.sh - Prepare a MobileFirst Server image
Run the prepareserver.sh script in order to build the MobileFirst Server and MobileFirst Analytics images and push it to your Bluemix repository. To view all available images in your Bluemix repository, run:
bx cr image-list
The list contains the image name, date of creation, and ID.
Interactive Mode Non-interactive Mode
- Deploy MobileFirst Server and MobileFirst Analytics on Docker containers on a Kubernetes cluster using Bluemix Container Service.
- Set your terminal context to your cluster
bx cs cluster-config my-cluster
To know your Cluster name, run the following command:
bx cs clusters
In the output, the path to your configuration file is displayed as a command to set an environment variable, for example:
Copy and paste the command above, after replacing my-cluster with your Cluster name, to set the environment variable in your terminal and press Enter.
- [Mandatory for MobileFirst Analytics]: Create a Persistent Volume Claim. This will be used to persist analytics data. This is a one time step. You can reuse the PVC if you have already created it prior. Edit the yaml file args/mfpf-persistent-volume-claim.yaml and then run the command.
All the variables have to be substituted with their values before executing the following kubectl command.
kubectl create -f ./args/mfpf-persistent-volume-claim.yaml
Note down the name of the Persistent Volume Claim, as you have to provide it in the subsequent step.
- To get your Ingress domain run the following command:
bx cs cluster-get my-cluster
Note down your Ingress domain. If you need to configure TLS, note down the Ingress secret.
- Create the Kubernetes deployments
Edit the yaml file args/mfpf-deployment-all.yaml, and fill out the details. All the variables have to be substituted with their values before executing the kubectl command.
./args/mfpf-deployment-all.yaml contains the deployment for the following:
- a kubernetes deployment for MobileFirst Server consisting of 3 instances (replicas), of 1024MB memory and 1Core CPU.
- a kubernetes deployment for MobileFirst Analytics consisting of 2 instances (replicas), of 1024MB memory and 1Core CPU.
- a kubernetes service for MobileFirst Server.
- a kubernetes service for MobileFirst Analytics.
- an ingress for the whole setup including all the REST endpints for MobileFirst Server and MobileFirst Analytics.
- a configMap to make the environment variables available in the MobileFirst Server and MobileFirst Analytics instances.
- Different occurences of my-cluster.us-south.containers.mybluemix.net with the output of Ingress Domain from the output of
bx cs cluster-getcommand as stated above.
- registry.ng.bluemix.net/repository/mfpfanalytics:latest and registry.ng.bluemix.net/repository/mfpfserver:latest - Use the same names that you used in prepareserver.sh to upload the images.
- claimName: mfppvc - Use the name Persistent Volume Claim name as you have used above to create the PVC.
kubectl create -f ./args/mfpf-deployment-all.yaml
Note:After creation, to use the Kubernetes dashboard, execute the following command:
The following template yaml files are supplied:
- mfpf-deployment-all.yaml: Deploys the MobileFirst Server and the MobileFirst Analytics with http.
- mfpf-deployment-all-tls.yaml: Deploys the MobileFirst Server and the MobileFirst Analytics with https.
- mfpf-deployment-server.yaml: Deploys the MobileFirst Server with http.
- mfpf-deployment-analytics.yaml: Deploys the MobileFirst Analytics with http.
Open localhost:8001/ui, in your browser.
- Set your terminal context to your cluster
With MobileFirst Server running on IBM Bluemix, you can now start your application development. Review the Mobile Foundation tutorials.
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/bmx-kubernetes/usr-mfpf-analytics
- MobileFirst Server Liberty Cloud Foundry Application: package_root/bmx-kubernetes/usr-mfpf-server
Steps to apply the iFix:
- Download the interim fix archive and extract the contents to your existing installation folder, overwriting the existing files.
- Restore your backed-up configuration files into the package_root/bmx-kubernetes/usr-mfpf-server and package_root/bmx-kubernetes/usr-mfpf-analytics folders, overwriting the newly installed configuration files.
- Edit package_root/bmx-kubernetes/usr-mfpf-server/env/jvm.options file in your editor and remove the following line, if it exists:
You can now build and deploy the updated server.
a. Run the
prepareserver.shscript to rebuild the server image and push it to the IBM Containers service.
b. Perform a rolling update by running the following command:
kubectl rolling-update NAME -f FILE
Removing the 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:
cf ic ps(Lists the containers currently running)
cf ic stop container_id(Stops the container)
cf ic rm container_id(Removes the container)
Run the following cf ic commands to remove an image name from the Bluemix registry:
cf ic images(Lists the images in the registry)
cf ic rmi image_id(Removes the image from the registry)
Removing the Kubernetes deployments from Bluemix
Run the following commands to remove your deployed instances from Bluemix Kubernetes cluster:
kubectl delete -f mfpf-deployment-all.yaml ( Removes all the kubernetes types defined in the yaml )
Run the following commands to remove image name from the Bluemix registry:
bx cr image-list (Lists the images in the registry) bx cr image-rm image-name (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.
- From the Bluemix dashboard, select the DB2 on cloud service you have used. Choose the DB2 service name that you had provided as parameter while running the prepareserverdbs.sh script.
- Launch the DB2 console to work with the schemas and database objects of the selected DB2 service instance.
- 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.
- Delete each of the schema after carefully inspecting the schema names and the objects under them. The database configurations are removed from Bluemix.