# Mojaloop Deployment

The document is intended for an audience with a stable technical knowledge that would like to setup an environment for development, testing and contributing to the Mojaloop project.

# 1. Pre-requisites

Versions numbers below are hard requirements, not just recommendations (more recent versions are known not to work).

A list of the pre-requisite tool set required for the deployment of Mojaloop:

For local guides on how to setup the pre-requisites on your laptop or desktop, refer to the appropriate link document below;

# 2. Deployment Recommendations

This provides environment resource recommendations with a view of the infrastructure architecture.

Resources Requirements:

Mojaloop Deployment Recommendations - Infrastructure Architecture

# 3. Kubernetes

This section will guide the reader through the deployment process to setup Kubernetes.

If you are new to Kubernetes it is strongly recommended to familiarize yourself with Kubernetes. Kubernetes Concepts (opens new window) is a good place to start and will provide an overview.

The following are Kubernetes concepts used within the project. An understanding of these concepts is imperative before attempting the deployment;

  • Deployment
  • Pod
  • ReplicaSets
  • Service
  • Ingress
  • StatefulSet
  • DaemonSet
  • Ingress Controller
  • ConfigMap
  • Secret

Insure kubectl is installed. A complete set of installation instruction are available here (opens new window).

# 3.1. Kubernetes Dashboard:

  1. Kubernetes Dashboard roles, services & deployment.

    Install for Dashboard using Helm (not needed if MicroK8s is installed): kubernetes-dashboard (opens new window)

    IMPORTANT: Always verify the current kubernetes-dashboard (opens new window) yaml file is still correct as used in the below command.

    kubectl create -f https://raw.githubusercontent.com/kubernetes/dashboard/v1.10.1/src/deploy/recommended/kubernetes-dashboard.yaml

    If you have installed MicroK8s, enable the MicroK8s dashboard;

    microk8s.enable dashboard

    Remember to prefix all kubectl commands with microk8s if you opted not to create an alias.

  2. Verify Kubernetes Dashboard. Windows replace grep with findstr;

    kubectl get pod --namespace=kube-system |grep dashboard

  3. Start proxy for local UI in new terminal;

    kubectl proxy ui

  4. Open URI in default browser:

    http://localhost:8001/api/v1/namespaces/kube-system/services/https:kubernetes-dashboard:/proxy/

    Select Token. Generate a token to use there by: Windows replace grep with findstr

    kubectl describe secret kubernetes-dashboard --namespace=kube-system

    The token to use is shown on the last line of the output of that command;

    kubectl -n kube-system describe secrets/kubernetes-dashboard-token-btbwf

    The {kubernetes-dashboard-token-btbwf} is retrieved from the output in the previous step. For more information on generating the token, follow the Authentication link in the window.

kubernetes-dashboard

# 4. Helm

Please review Mojaloop Helm Chart to understand the relationships between the deployed Mojaloop helm charts.

Refer to the official documentation on how to install the latest version of Helm v3: https://helm.sh/docs/intro/install/

Refer to the following document if are using Helm v2: Deployment with (Deprecated) Helm v2

Refer to the Helm v2 to v3 Migration Guide if you wish to migrate an existing Helm v2 deployment to v3.

# 4.1. Helm configuration

  1. Add mojaloop repo to your Helm config:

    helm repo add mojaloop https://mojaloop.io/helm/repo/

    If the repo already exists, substitute 'add' with 'apply' in the above command.

  2. Add the additional dependency Helm repositories. This is needed to resolve Helm Chart dependencies required by Mojaloop charts.

    helm repo add incubator http://storage.googleapis.com/kubernetes-charts-incubator
helm repo add kiwigrid https://kiwigrid.github.io
helm repo add elastic https://helm.elastic.co
helm repo add bitnami https://charts.bitnami.com/bitnami

  3. Update helm repositories:

    helm repo update

  4. Optionally Install nginx-ingress for load balancing & external access:

    helm --namespace kube-public install stable/nginx-ingress

# 5. Mojaloop

# 5.1. Mojaloop Helm Deployment

  1. Install Mojaloop:

    Default installation:

    helm --namespace demo install moja mojaloop/mojaloop

    Version specific installation:

    helm --namespace demo install moja mojaloop/mojaloop --version {version}

    List of available versions:

    helm search repo -l mojaloop/mojaloop

    Custom configured installation:

    helm --namespace demo install moja mojaloop/mojaloop -f {custom-values.yaml}

    Note: Download and customize the values.yaml (opens new window). Also ensure that you are using the value.yaml from the correct version which can be found via Helm Releases (opens new window).

# 5.2. Verifying Mojaloop Deployment

  1. Update your /etc/hosts for local deployment:

    Note: This is only applicable for local deployments, and is not needed if custom DNS or ingress rules are configured in a customized values.yaml (opens new window).

    vi /etc/hosts

    Windows the file can be updated in notepad - need to open with Administrative privileges. File location C:\Windows\System32\drivers\etc\hosts.

    Include the following lines (or alternatively combine them) to the host config.

    The below required config is applicable to Helm release >= versions 6.2.2 for Mojaloop API Services;

    127.0.0.1       central-ledger.local central-settlement.local ml-api-adapter.local account-lookup-service.local account-lookup-service-admin.local quoting-service.local moja-simulator.local central-ledger central-settlement ml-api-adapter account-lookup-service account-lookup-service-admin quoting-service simulator host.docker.internal transaction-request-service.local

    The below optional config is applicable to Helm release >= versions 6.2.2 for Internal components, please include the following in the host configuration.

    127.0.0.1       forensic-logging-sidecar.local central-kms.local central-event-processor.local email-notifier.local

    For Helm legacy releases prior to versions 6.2.2, please include the following in the host configuration.

    127.0.0.1       interop-switch.local central-end-user-registry.local central-directory.local central-hub.local

  2. Test system health in your browser after installation. This will only work if you have an active helm chart deployment running.

    Note: The examples below are only applicable to a local deployment. The entries should match the DNS values or ingress rules as configured in the values.yaml (opens new window) or otherwise matching any custom ingress rules configured.

    ml-api-adapter health test:

    http://ml-api-adapter.local/health

    central-ledger health test:

    http://central-ledger.local/health

# 6. Postman

Postman is used to send requests and receive responses.

# 6.1. Installing Postman

Please, follow these instructions: Get Postman (opens new window) and install the Postman application.

# 6.2. Setup Postman

Grab the latest collections & environment files from Mojaloop Postman Github repo (opens new window).

After an initial setup or new deployment, the OSS New Deployment FSP Setup section needs to be completed. This will seed the Database with the required enumerations and static data to enable the sucessful execution of any manual or automation tests by the other collections.

Refer to the QA and Regression Testing in Mojaloop documentation for more complete information to complement your testing requirements.