This reference architecture can be deployed in either a production or a trial environment. In both cases, it is assumed that rhmap-master1 refers to one (or the only) OpenShift master host and that the environment includes six OpenShift schedulable hosts with the host names of rhmap-node1 to rhmap-node6. Production environments would have at least 3 master hosts to provide High Availability (HA) resource management.

It is further assumed that OpenShift Container Platform has been installed by the root user and that a regular user has been created with basic access to the host machine, as well as access to OpenShift through its identity providers.

Red Hat provides a sizing tool for Red Hat Mobile Application Platform. For the purpose of installing and configuring an environment, this reference application is assumed to be a Business to Employee (B2E) internal application, deployed on an on-premise platform that includes both the core and MBaaS components. We further assume that it qualifies as a single application for the use of up to 200 employees. Based on these parameters, the sizing tool suggests:

Set up six virtual or physical machines to host the nodes of the OpenShift cluster, as suggested by the results of the sizing tool.

In the reference architecture environment, rhmap-node1, rhmap-node2, and rhmap-node3 are used for MBaaS. The next three nodes, rhmap-node4, rhmap-node5, and rhmap-node6 deploy the core components.

Use root or another user with the required privileges to create a Linux user that will run the Ansible provisioning scripts. For example, to create the user, assign a password, and give it superuser privileges:

# useradd rhmapAdmin
# passwd rhmapAdmin
# usermod -aG wheel rhmapAdmin

Allow members of the wheel group to execute privileged actions without typing the password.

# visudo

Uncomment the line that specifies a NOPASSWD policy:

Repeat this process on all masters and nodes.

Next, generate SSH keys for the new user. The keys will be used to allow the user to access all the nodes from the master, without having to provide a password. Press enter to accept default values or provide empty values for the prompts:

# su - rhmapAdmin
$ ssh-keygen

Generating public/private rsa key pair.
Enter file in which to save the key (/home/rhmapAdmin/.ssh/id_rsa):
Created directory '/home/rhmapAdmin/.ssh'.

Enter passphrase (empty for no passphrase):

Enter same passphrase again:
Your identification has been saved in /home/rhmapAdmin/.ssh/id_rsa.
Your public key has been saved in /home/rhmapAdmin/.ssh/id_rsa.pub.

The key fingerprint is:
d0:d2:d9:ed:31:63:28:d0:c0:4c:91:8b:34:d5:03:b8 rhmapAdmin@rhmap-master1.xxx.example.com
The key's randomart image is:
+--[ RSA 2048]----+
|     *BB         |
|    + +++o o     |
|   . +o.=.o *    |
|    E .o . o +   |
|        S   .    |
|                 |
|                 |
|                 |
|                 |
+-----------------+

Now that the keys are generated, copy the public key to all machines to allow the holder of the private key to log in:

$ for host in rhmap-master1 rhmap-node1 rhmap-node2 rhmap-node3 rhmap-node4 rhmap-node5 rhmap-node6; \
    do ssh-copy-id -i ~/.ssh/id_rsa.pub $host; \
    done

This reference architecture environment uses Network File System (NFS) to make storage available to all OpenShift nodes.

Attach 66GB of storage for core and 151GB for MBaaS. Create a volume group for each of them, and logical volumes for each required persistent volume:

$ sudo pvcreate /dev/vdc
$ sudo vgcreate rhmapcore /dev/vdc
$ sudo lvcreate -L 5G -n gitlabshell rhmapcore
$ sudo lvcreate -L 5G -n mysql rhmapcore
$ sudo lvcreate -L 5G -n metricslog rhmapcore
$ sudo lvcreate -L 25G -n mongodb rhmapcore
$ sudo lvcreate -l 25G -n fhscm rhmapcore
$ sudo lvcreate -L 1G -n nagios rhmapcore

$ sudo pvcreate /dev/vdd
$ sudo vgcreate mbaas /dev/vdd
$ sudo lvcreate -L 50G -n mongo1 mbaas
$ sudo lvcreate -L 50G -n mongo2 mbaas
$ sudo lvcreate -l 50G -n mongo3 mbaas
$ sudo lvcreate -L 1G -n nagios mbaas

Create a corresponding mount directory for each logical volume and mount them.

$ sudo systemctl stop nfs
$ for i in rhmapcore/nagios rhmapcore/gitlabshell rhmapcore/mysql rhmapcore/metricslog rhmapcore/mongodb rhmapcore/fhscm mbaas/nagios mbaas/mongo1 mbaas/mongo2 mbaas/mongo3;
> do
> sudo mkfs.ext4 /dev/$i;
> sudo mkdir -p /mnt/$i;
> sudo mount /dev/$i /mnt/$i;
> done

Share these mounts with all nodes by configuring the /etc/exports file on the NFS server and make sure to restart the NFS service.

Create an OpenShift user, optionally with the same name, to use for the provisioning. Assuming the use of HTPasswd as the authentication provider:

$ sudo htpasswd -c /etc/origin/master/htpasswd rhmapAdmin
New password: PASSWORD
Re-type new password: PASSWORD
Adding password for user rhmapAdmin

Grant OpenShift admin and cluster admin roles to this user:

$ sudo oadm policy add-cluster-role-to-user admin rhmapAdmin
$ sudo oadm policy add-cluster-role-to-user cluster-admin rhmapAdmin

At this point, the new OpenShift user can be used to sign in to the cluster through the master server:

$ oc login -u rhmapAdmin -p PASSWORD --server=https://rhmap-master1.xxx.example.com:8443

Login successful.

$ CA=/etc/origin/master
$ sudo oadm ca create-server-cert --signer-cert=$CA/ca.crt \
      --signer-key=$CA/ca.key --signer-serial=$CA/ca.serial.txt \
      --hostnames='.rhmap.xxx.example.com' \*
      --cert=cloudapps.crt --key=cloudapps.key
$ sudo cat cloudapps.crt cloudapps.key $CA/ca.crt > cloudapps.router.pem

$ oc delete all -l router=router -n default
$ oc delete secret router-certs -n default

$ sudo oadm router --default-cert=cloudapps.router.pem --service-account=router

Configure and run the provisioning steps for Red Hat Mobile Application Platform from the rhmap-master1 machine.

Enable the yum repository for Red Hat Mobile Application Platform 4.4:

$ sudo subscription-manager repos --enable="rhel-7-server-rhmap-4.4-rpms"

Install the OpenShift templates for Red Hat Mobile Application Platform, as well as the Ansible playbooks and configuration files through its package:

$ sudo yum install rhmap-fh-openshift-templates

Configure an Ansible inventory file for the reference architecture environment. Several templates are provided as part of the package installed in the previous step. For this environment, use /opt/rhmap/4.4/rhmap-installer/inventories/templates/multi-node-example as a starting point. The inventory file used for this environment is provided as an appendix to this document.

The cluster_hostname variable is set to the OpenShift cluster subdomain. The domain_name value is a name that is used to build the address to the studio web console.

The specified user for the ansible_ssh_user variable is used to log in to the required machines during installation. The OpenShift user and password are also specified in this file.

To run the provided ansible books, change to the /opt/rhmap/4.4/rhmap-installer/ directory. The roles directory is expected in the current directory when running the playbooks. Save the modified host inventory file detailed in the appendix in this directory as rhmap_hosts.

Download the required docker images to make the platform setup process faster, and avoid timeouts. Run the two following playbooks to download the images:

$ ansible-playbook -i rhmap-hosts playbooks/seed-images.yml -e "project_type=core" -e "rhmap_version=4.4"
$ ansible-playbook -i rhmap-hosts playbooks/seed-images.yml -e "project_type=mbaas" -e "rhmap_version=4.4"

Before creating a project and starting with development, an environment and an MBaaS target are required. Discover the web address of the RHMAP studio by querying its associated OpenShift route:

$ oc get route rhmap -n rhmap-core
NAME      HOST/PORT                                    PATH      SERVICES      PORT               TERMINATION   WILDCARD
rhmap     app.rhmap.xxx.example.com             rhmap-proxy   server-http-port   edge/Allow    None

The password for the studio is generated by OpenShift during deployment. It can be retrieved from the millicore deployment config environment:

$ oc env dc millicore --list -n rhmap-core | grep FH_ADMIN
FH_ADMIN_USER_PASSWORD=3QlIf7RBqwmRa4yrH2rNYTKOSC
FH_ADMIN_USER_NAME=rhmap-admin@example.com

Use these credentials to log in to the studio. Once signed in, navigate through the Admin menu to MBaaS Targets:

Figure 4.2. MBaaS Targets

Click the button to create an MBaaS target. This requires providing a number of values, some of which are discretionary names and labels, but others are generated by OpenShift during deployment and should be looked up.

Find the values for MBaaS Service Key, MBaaS URL, and Nagios URL:

$ oc env dc fh-mbaas --list -n rhmap-3-node-mbaas | grep FHMBAAS_KEY
FHMBAAS_KEY=rpmAV2Mr0RCNegEBb6MM0xv3wq2QW7TWmHBXUHPG

$ echo "https://"$(oc get route/mbaas -n rhmap-3-node-mbaas -o template --template {{.spec.host}})
https://mbaas-rhmap-3-node-mbaas.rhmap.xxx.example.com

$ echo "https://"$(oc get route/nagios -n rhmap-3-node-mbaas -o template --template {{.spec.host}})
https://nagios-rhmap-3-node-mbaas.rhmap.xxx.example.com

Use the above, and assign other valid values, to fill out the form to create a new MBaaS target:

Figure 4.3. Create MBaaS Target

Once an MBaaS target is successfully created, proceed to create an environment that references it:

Figure 4.4. Environments

Each environment is associated with an OpenShift project, that must be created through a user’s credentials. While logged in to OpenShift as rhmapAdmin, use the following command to discover and note the user’s security token:

$ oc whoami -t
rPTnAjyYFxczPMd5vGXyaOjALn1cYEdCiSVCzGrWnhA

Use this token to create the environment:

Figure 4.5. Create Environment

Verify that an OpenShift environment has been created for this environment:

$ oc get projects
NAME                 DISPLAY NAME                                     STATUS
default                                                               Active
kube-system                                                           Active
logging                                                               Active
management-infra                                                      Active
openshift                                                             Active
openshift-infra                                                       Active
rhmap-3-node-mbaas                                                    Active
rhmap-app-dev        RHMAP Environment: app-Development Environment   Active
rhmap-core                                                            Active

To start, a suite of back-end logic microservices will be installed in a secondary OpenShift Container Platform project native to the cluster housing the Mobile Application Platform installation.

Utilize remote or direct terminal access to log in to the OpenShift environment as the user who will create, and have ownership of the new project:

$ oc login -u ocuser

Create the new project which will house the microservices suite:

$ oc new-project ecom-services --display-name="E-Commerce Services Suite" --description="Back-end logic microservice suite"

Within the new project, execute the provided YAML template to configure and instantiate the full services suite:

$ oc new-app -f https://raw.githubusercontent.com/RHsyseng/FIS2-MSA/ecom-svcs/project-template.yaml

Once all services are deployed and running, instantiate the e-commerce data set via a GET request to the gateway service route:

$ curl -i http://ecom.rhmap.xxx.example.com/demo/testApi
HTTP/1.1 200 OK
...

Before beginning, download the following artifact. The archive contains a series of source code zip artifacts, which are used to import the various apps and services. Unzip the top-level artifact, but don’t unzip the child artifacts contained within.

$ curl -O -L https://github.com/RHsyseng/RHMAP/raw/master/import-artifacts.zip
$ unzip import-artifacts.zip

Within App Studio, the Mobile Application Platform web interface, select the Projects widget:

Figure 4.6. App Studio

Press the New Project button, then select Empty Project. Provide project name 'ecom-refarch' and then hit Create.

Figure 4.7. Empty Project Creation

Figure 4.8. Project Creation Complete

Use the Finish button after completion to navigate to the project dashboard.

Figure 4.9. Project Dashboard

From the top of the screen, select Services and APIs to start service creation. Once there, click the Provision MBaaS Service/API button to start the creation process.

Next, select Import Existing Service, name the service ecom-svcs-health, and click Next.

For Import From, select Zip File, provide the ecom-status.zip file downloaded in previous steps, then click Next, followed by Finish.

From the new service app’s Details page, scroll down and mark Make this Service Public to all Projects and Services, then Save Service.

Figure 4.10. Marking Service Public

If prompted, confirm pushing of environment variables, then from the left-hand Navigation panel, select Deploy.

Use the Deploy Cloud App button to instantiate a new build and deployment of the service.

Figure 4.11. Deploy Cloud App

After initiating deployment, use the left-hand navigation to return to Details.

The status of the project will change from Stopped to Running once the triggered build and deployment complete.

Once running, copy the 'Current Host' URL value and open a new tab, append /admin to the copied value, and navigate to the service page.

Figure 4.12. Health Monitor Service Details

Use the Add New button in the upper right-hand corner, configure the modal prompt as shown below, then click Create:

Figure 4.13. Gateway Service Check Configuration

Use the Add New button once again to create a check for Billing Service, this time utilizing the HTTP(s) protocol option instead of TCP, as shown below:

Figure 4.14. Billing Service Check Configuration

Create 3 additional new services in the same fashion for the sales-service, product-service, and warehouse-service, altering the HTTP(s) URL to match the service destination for each.

Figure 4.15. Health Monitor Service

At this point, click checkbox next to all 5 services and then click the Summary Url button. Copy the URL somewhere close at hand, as it will be required further on.

Lastly, use the Projects link in the upper navigation bar to navigate to the ecom-refarch project dashboard. Click the plus button in the upper right corner of the MBaaS Services widget and click the service to associate it to your project.

Figure 4.16. Associating the Service

Return to the project dashboard, and use the plus button to add a new Cloud Code App.

Just as with the Health Monitor service creation, choose to Import Existing App, name the app ecom-cloud, provide the previously acquired ecom-cloud.zip file, and follow the prompts until reaching the application’s dashboard.

Using the left-hand navigation, go to Environment Variables, then click the Add Variable button.

Provide a new variable with the name of MBAAS_HEALTH_URL, and use the URL copied from the Monitoring service in the previous step, as the variable value. Click Push Environment Variables.

Navigate to Deploy and start a new deployment of the cloud app. Monitor the application dashboard Details screen for results.

Once deployment is complete, it’s possible to directly reach your cloud application via browser at the given Current Host address, however, since the cloud application is not intended as a public-facing tool, the page will simply indicate the general availability of the application.

Return to the project dashboard and use the plus button on the Apps widget.

As before, choose to Import Existing App of type Cordova, name the application ecom-shop, and use the provided artifact with the same name as the import source. The various steps for integration are presented and can be reviewed, but no action is necessary. Follow the prompts until taken to the application Details page as before.

Figure 4.17. App Import from Zip

From Details, select the Connections link found in the horizontal navigation bar, then click the ecom-shop link inside the Client App column. Copy the SDK configuration JSON contents in the bottom box to clipboard, then hit Cancel to close the modal window.

Figure 4.18. Connection Details

Return to the ecom-shop dashboard, navigate to Editor on the left-hand side, expand the www directory, then select the fhconfig.json file. Replace the contents of the file with the clipboard contents attained from the Connections window and then click File > Save.

Navigate to Build from the left-hand bar, select the platform of your choice, and use Build to create a native application artifact for the ecom-shop project.

Figure 4.19. Build Screen

After the build completes, a modal window presents both QR code and direct download link for fetching of the resulting artifact.

Figure 4.20. Download Artifact

Once more, return to the project dashboard and add a new client application under Apps.

As with the ecom-shop application, begin the import process for the provided ecom-portal artifact file, this time using the Web App type instead of Cordova. As before, follow the prompts to completion. Lastly, visit Connections to capture the ecom-portal details, which will differ from those provided for ecom-shop, and replace the contents of the src/fhconfig.json file with the new connection information.

Once finished, navigate to Deploy and start a new deployment for the cloud portal app. Monitor the Details page for application state change.

Once complete, the Current Host URL can be used to navigate to the portal landing page, showing a list of featured products. Successful loading and visibility of this page indicates that all cloud and client application setup is complete and properly functioning.