Setting up AeroGear Mobile Services on OpenShift

Mobile Services run natively on OpenShift.

There are two options for installing Mobile Services:

using an installation script
using the OpenShift CLI

Typically, developers use the installation script method.

Prerequisites

OpenShift 3.11 instance
- This instance must have Service Catalog, Ansible Service Broker and Template Service Broker services installed.
- You need to have full access to this OpenShift instance, i.e. user with cluster-admin privileges.
  
  If you don’t have OpenShift instance you can use oc cluster up or Minishift to setup OpenShift locally.
OpenShift client tools version 3.11
Docker
A local mobile development environment for the platform you want to develop on.
Ansible 2.7.x installed on the machine where you want to run the installation scripts from

Installing Mobile Services using the installer script

Clone the Mobile Services Installer repository:

The repository contains installation script for AeroGear Mobile Services.

Clone this repo to your local machine and check out the 2.0.0 tag using:
```
git clone https://github.com/aerogear/mobile-services-installer.git
cd mobile-services-installer
git checkout 2.0.0
```
Login to your OpenShift instance as user with cluster-admin privileges:
```
$ oc login <OPENSHIFT_MASTER_URL>
```
Change directory SELinux security context (RHEL/Fedora):

This step is only required on RHEL/Fedora with SELinux enabled.
```
$ chcon -Rt svirt_sandbox_file_t .
```

In the same directory, run the installer:

$ ansible-playbook install-mobile-services.yml

Verify the installation:
1. Browse to the Web console of your OpenShift instance and log in.
2. Check that the Mobile tab is displayed in the service catalog. If this tab is not displayed, wait a few minutes to make sure that the installation process has completed.

Installing Mobile Services using the OpenShift CLI

Create a Custom Resource Definition file:

cat > /tmp/crd.yaml << EOF
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
  name: mobileclients.mobile.k8s.io
spec:
  group: mobile.k8s.io
  version: v1alpha1
  scope: Namespaced
  names:
    plural: mobileclients
    singular: mobileclient
    kind: MobileClient
    shortNames:
    - mc
  validation:
    openAPIV3Schema:
      properties:
        spec:
          properties:
            apiKey:
              type: string
              pattern: '(\w{8}-\w{4}-\w{4}-\w{4}-\w{11})'
            name:
              type: string
              pattern: '([\w-])'
            dmzUrl:
              type: string
              nullable: true
EOF

Run the following commands to setup the Custom Resource on OpenShift:

oc create -f /tmp/crd.yaml
oc create clusterrole mobileclient-admin --verb=create,delete,get,list,patch,update,watch --resource=mobileclients
oc adm policy add-cluster-role-to-group mobileclient-admin system:authenticated

Update the configuration of the Automation Service Broker to add new registries:

Edit the config map object using oc

oc edit configmap broker-config -n openshift-automation-service-broker

Add the following new registries to the registry section of the config:

registry:
- type: dockerhub
  name: ag
  url: https://registry.hub.docker.com
  org: aerogearcatalog
  tag: 1.0.0
  white_list:
    - '.*-apb$'
  black_list:
    - '.*mobile-developer-console-apb$'
- type: dockerhub
  name: ag-mdc
  org: aerogearcatalog
  tag: 1.0.0-alpha
  url: https://registry.hub.docker.com
  white_list:
  - '.*mobile-developer-console-apb$'

Update the following attributes in the openshift section of the config:
```
openshift:
  image_pull_policy: Always
  sandbox_role: admin
```
Update the following attributes in the broker section of the config:
```
broker:
  launch_apb_on_bind: true
```

Save the configmap object, and restart the automation service broker:

oc rollout latest openshift-automation-service-broker -n openshift-automation-service-broker

Verify the installation:
1. Browse to the Web console of your OpenShift instance and log in.
2. Check that the Mobile tab is displayed in the service catalog. If this tab is not displayed, wait a few minutes to make sure that the installation process has completed.

Additional resources

Local OpenShift setup

You can run OpenShift locally on your machine. There are two scripts in Mobile Services Installer repository which will create the cluster using Minishift or oc cluster up, and enable AeroGear Mobile Services.

On Mac only Minishift is currently supported.

Prerequisites

Minishift
oc cluster up

Minishift
OpenShift client tools version 3.11
Docker
Ansible 2.7.x installed on the machine where you want to run the installation scripts from

Linux
OpenShift client tools version 3.11
Docker
Ansible 2.7.x installed on the machine where you want to run the installation scripts from

Firewall configured:

firewall-cmd --permanent --add-port=8443/tcp
firewall-cmd --permanent --add-port=8053/tcp
firewall-cmd --permanent --add-port=53/udp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --reload

Procedure

Clone the Mobile Services Installer repository:

git clone https://github.com/aerogear/mobile-services-installer.git
cd mobile-services-installer
git checkout 2.0.0

Run the installation script:

Minishift
oc cluster up

$ ./scripts/minishift.sh

$ ./scripts/oc-cluster-up.sh

Copy cluster self-signed certificate:

When the script finishes it will save OpenShift’s self-signed certificate to /tmp/oc-certs/localcluster.crt. Copy this file so you can later install it to your mobile device.

This is needed so that your mobile app can communicate with OpenShift.
Browse to the Web console of your local OpenShift instance, accept self-signed certificate and log in.

You can get OpenShift URL with:
```
$ oc status
```
Browser may redirect you to localhost. If that happens just enter the URL again and make sure to add /console at the end.

Provisioning Mobile Developer Console

To provision the Mobile Developer Console:

Log into the OpenShift console.
Create a new project or choose an existing project.
Select Catalog from the left hand menu.

You can filter the catalog items to only show mobile specific items by selecting the Mobile tab.
Choose the Mobile Developer Console service.
Follow the wizard for provisioning that service.

If prompted to Create a Binding, choose Do not bind at this time.

Once the wizard steps are completed, navigate to the Project Overview in OpenShift to see the newly provisioned service. Provisioning the Mobile Developer Console may take some time.