Skip to content

Latest commit

 

History

History
163 lines (134 loc) · 7.59 KB

installing-mobile-services.adoc

File metadata and controls

163 lines (134 loc) · 7.59 KB

Setting up {org-name} {product-name} on OpenShift

To use {product-name}, you must run OpenShift and install an add-on which enables {product-name}. For more information about OpenShift, see OpenShift website.

Note
 {org-name} recommends running OpenShift using the method described in this document. However, there are many ways to run OpenShift, and {product-name} is compatible with most of these methods. There is a known issue with Minishift that makes it unsuitable for mobile development. This issue is described in Issue 1287.

Prerequisites

  • MacOS or Linux

    Note
    		 Due to an OpenShift bug, {product-name} will not run on RHEL/CentOS 7.4 or RHEL/CentOS 7.5.

  • A system running OpenShift oc cluster up as described in Local Cluster Management

    Note
    		 Installation on macOS with Docker Machine has not been tested, use the Docker for Mac instructions when installing OpenShift.

    • Use OpenShift client tools version 3.9

      Important
      		 OpenShift oc executable must be located in a system location that is known to all shells (e.g. /usr/local/bin)
      Important
      		 Ensure that you can run oc cluster up with no errors before moving on to the installation of AeroGear.

  • Access to a Docker Hub account. The installer uses Docker Hub as a source for AeroGear Docker images.

  • Ansible (version 2.6 or above)

  • For Linux (Fedora), add an extra port to the dockerc zone:

$ firewall-cmd --permanent --zone dockerc --add-port 443/tcp
$ firewall-cmd --reload

  • A local mobile development environment for the platform you want to develop on.

Procedure

  1. Clone the Mobile-core installer:

    The installer configures the local development installation of {org-name} {product-name} using ansible scripts in our mobile-core repo.

    Clone this repo to your local machine and check out the {release-number} tag using:

    git clone https://github.com/aerogear/mobile-core.git
cd mobile-core
git checkout {release-number}

  2. In the same directory, run the installer:

    $ ./installer/install.sh

    The installer checks that valid versions of Ansible, Docker and the OpenShift Client Tools are installed.

  3. Enter your Docker Hub login credentials when prompted. The installer checks these credentials are valid before continuing.

  4. Accept the default values for the next set of prompts, unless you have specific requirements and understand the implications of changing the values. For more information about these values, see the DockerHub, Cluster IP and Wildcard DNS Host values section in Additional Resources.

    Note
    		 If your Cluster IP address is reported as 127.0.0.1, the installation will not succeed. Check your network connection and restart the installer. 
    DockerHub Tag (Defaults to latest):
DockerHub Organisation (Defaults to aerogearcatalog):
Cluster IP (Defaults to < Network IP Address >)
Wildcard DNS Host (Defaults to nip.io):

    For more information, see the DockerHub, Cluster IP and Wildcard DNS Host values section in Additional resources.

    The following installation can take a while the first time it runs, as it pulls a number of Docker images. Once completed successfully, this results in an output similar to the following:

    TASK [output-oc-cluster-status : debug] ******************************************************************************************************************************************************
ok: [localhost] => {
    "msg": [
        "Web console URL: https://192.168.37.1:8443/console/",
        "",
        "Config is at host directory /var/lib/origin/openshift.local.config",
        "Volumes are at host directory /var/lib/origin/openshift.local.volumes",
        "Persistent volumes are at host directory /var/lib/origin/openshift.local.pv",
        "Data is at host directory /path/to/mobile-core/ui/openshift-data"
    ]
}

PLAY RECAP ***********************************************************************************************************************************************************************************
localhost                  : ok=44   changed=17   unreachable=0    failed=0

    The log above is displayed after a successful installation.

  5. Verify the installation:

    1. Browse to the Web console URL displayed at the end of the installation, and log in, accepting the self-signed certificate if displayed.

      The developer login credentials are:

      username: developer
password: password

      The service catalog is displayed

    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. If the Mobile tab still is not displayed, follow the troubleshooting steps below.

catalog mobile clients

Additional resources

Troubleshooting

If you have problems running {org-name} {product-name}, run the installer using the --debug option to capture as much information as possible:

$ ./installer/install.sh --debug

Firewall issues can occur with external devices trying to communicate with {product-name} provisioned on a Linux machine.

This is due to a number of {product-name} using ports which are restricted to root users only. If you encounter these issues, you can add the ports to your firewall. Depending on the port your service uses an example of the ports you may want to add to your firewall are:

Note
 The following command will only add the specified port for the current session. If you reload your firewall or restart your machine the specified port will be restricted again. 
$ firewall-cmd --add-port 443/tcp
$ firewall-cmd --add-port 80/tcp

DockerHub, Cluster IP and Wildcard DNS Host values

Use DockerHub Tag and DockerHub Organisation to configure the location of the APBs used by the service-catalog in the cluster you are creating:

DockerHub Tag (Defaults to latest):
DockerHub Organisation (Defaults to aerogearcatalog):

The Cluster IP value defaults to the IP address of your primary network interface. If you want to connect to your OpenShift instance from a mobile device, ensure that your device is on the same network. Typically, you should ensure you are using the IP Address of your Wireless Adapter (if one exists):

Cluster IP (Defaults to < Network IP Address >)

The Wildcard DNS Host option alters the wildcard DNS host you want to use:

Wildcard DNS Host (Defaults to nip.io):