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

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

  2. Login to your OpenShift instance as user with cluster-admin privileges:

    $ oc login <OPENSHIFT_MASTER_URL>

  3. Change directory SELinux security context (RHEL/Fedora):

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

  4. In the same directory, run the installer:

    $ ansible-playbook install-mobile-services.yml

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

  1. Log in to the OpenShift console as a user with cluster-admin privileges using the oc command.

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

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

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

    1. Edit the config map object using oc

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

    2. 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$'

    3. Update the following attributes in the openshift section of the config:

      openshift:
  image_pull_policy: Always
  sandbox_role: admin

    4. Update the following attributes in the broker section of the config:

      broker:
  launch_apb_on_bind: true

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

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

  5. 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 Developer Console 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

  • 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

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

  2. Run the installation script:

    • Minishift

    • oc cluster up

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

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

  4. 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:

  1. Log into the OpenShift console.

  2. Create a new project or choose an existing project.

  3. Select Catalog from the left hand menu.

    You can filter the catalog items to only show mobile specific items by selecting the Mobile tab.

  4. Choose the Mobile Developer Console service.

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