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

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