From fc885db73255c3d38bd913fcc50f2b4166f53353 Mon Sep 17 00:00:00 2001 From: Vijay Date: Wed, 16 Oct 2024 14:31:16 +0530 Subject: [PATCH] chore: added doc --- .../docker_arm_rebuild/README.md | 116 ++++++++++++++++++ .../docker_arm_rebuild/{run.sh => rebuild.sh} | 5 +- local-deployment-methods/helmfile/README.md | 76 +++--------- 3 files changed, 136 insertions(+), 61 deletions(-) create mode 100644 local-deployment-methods/docker_arm_rebuild/README.md rename local-deployment-methods/docker_arm_rebuild/{run.sh => rebuild.sh} (99%) diff --git a/local-deployment-methods/docker_arm_rebuild/README.md b/local-deployment-methods/docker_arm_rebuild/README.md new file mode 100644 index 000000000..e5e95c093 --- /dev/null +++ b/local-deployment-methods/docker_arm_rebuild/README.md @@ -0,0 +1,116 @@ +# Docker Image Re-Builder from Helm Charts + +## Overview + +The official **Mojaloop Docker images** are currently only available for the **AMD64** platform. When deploying Mojaloop Helm charts on an **ARM-based macOS**, these images run in **emulation mode**, which significantly slows down performance compared to native applications. + +This script aims to address that issue by: + +1. Extracting Mojaloop Docker image references from the Helm chart. +2. Cloning the respective repositories from GitHub. +3. Checking out the appropriate tags. +4. Rebuilding the Docker images for **ARM64** architecture. + +By building native ARM64 images, the goal is to improve the performance during local testing and development. **In the future**, it is hoped that Mojaloop’s official Docker images will natively support ARM architecture, eliminating the need for such custom builds. + + +--- + +## Prerequisites + +- **Git**: Ensure `git` is installed on your system. +- **Docker**: Docker daemon must be running and accessible. +- **Helm**: Helm must be installed and the charts should be accessible from the specified path. + +--- + +## Usage + +Make the script executable and run it from your terminal: + +```bash +cd local-deployment-methods/docker_arm_rebuild +chmod +x rebuild.sh +./rebuild.sh +``` + +## Script Parameters and Components + +### Variables: + +- HELM_RELEASE: + The name used for the Helm release. Example: moja. + +- HELM_CHART: + Path to the Helm chart folder to extract the templates. Example: ../../mojaloop/ or + +## Example Output +``` +Building Docker image from repo https://github.com/mojaloop/account-lookup-service.git with tag v15.4.0-snapshot.33 +Skipping duplicate image: mojaloop/central-ledger:v15.3.1 +Skipping non-mojaloop image: some-other-service:latest +``` + +## Limitations +- Helm Chart Assumptions: + The script assumes all Helm chart image references follow the format mojaloop/repo-name:tag. + +- ARM64 Architecture: + The script builds Docker images for ARM64 only. Adjust the docker build command if other architectures are needed. + +--- + +# Deploying Mojaloop on macOS using Docker Desktop + +## Prerequisites + +Before deploying Mojaloop, ensure the following tools are installed and configured on your macOS machine: + +- **Docker Desktop for macOS**: Ensure Kubernetes is enabled in Docker Desktop. +- **Helm**: Install Helm for managing your Kubernetes deployments. +- **Helmfile**: Install Helmfile to manage multiple Helm charts effectively. + +--- + +## Step-by-Step Deployment + +### 1. Adjust Resource Limits in Docker Desktop + +To run Mojaloop smoothly, adjust the CPU and memory allocations in Docker Desktop: + +1. Open **Docker Desktop**. +2. Navigate to **Settings** (⚙️) → **Resources**. +3. Set: + - **CPUs**: 8 cores + - **Memory**: 16 GB RAM +4. Click **Apply & Restart** to save the changes. + +### 2. Install Ingress NGINX Controller + +Mojaloop requires an Ingress controller to route external traffic to the services. Use the following Helm command to install. + +**Ingress NGINX**: + +```bash +helm upgrade --install ingress-nginx ingress-nginx \ + --repo https://kubernetes.github.io/ingress-nginx \ + --namespace ingress-nginx --create-namespace +``` + +### 3. Prepare Helm Chart Dependencies + +Navigate to the root directory of the project and run the update-charts-dep.sh script to update the chart dependencies: + +``` +sh update-charts-dep.sh +``` + +### 4. Deploy Mojaloop Using Helmfile + +Change to the local-deployment-methods/helmfile directory, where the Helmfile configuration is located. Then, run the following commands to deploy Mojaloop: + +``` +cd local-deployment-methods/helmfile +sh update-charts-dep.sh +helmfile apply +``` diff --git a/local-deployment-methods/docker_arm_rebuild/run.sh b/local-deployment-methods/docker_arm_rebuild/rebuild.sh similarity index 99% rename from local-deployment-methods/docker_arm_rebuild/run.sh rename to local-deployment-methods/docker_arm_rebuild/rebuild.sh index 8d3e50137..8d116f37c 100644 --- a/local-deployment-methods/docker_arm_rebuild/run.sh +++ b/local-deployment-methods/docker_arm_rebuild/rebuild.sh @@ -1,5 +1,8 @@ #!/bin/bash +HELM_CHART="../../mojaloop/" +HELM_RELEASE="moja" + # Function to clone repo, checkout specific tag, and build docker image build_docker_image_from_repo() { IMAGE=$1 @@ -27,8 +30,6 @@ build_docker_image_from_repo() { } # 1. Render the Helm chart template and extract image lines -HELM_RELEASE="moja" -HELM_CHART="../../mojaloop/" IMAGES=$(helm template "$HELM_RELEASE" "$HELM_CHART" | grep "image:" | awk '{print $2}') diff --git a/local-deployment-methods/helmfile/README.md b/local-deployment-methods/helmfile/README.md index de98ed3c9..6a9e660cb 100644 --- a/local-deployment-methods/helmfile/README.md +++ b/local-deployment-methods/helmfile/README.md @@ -1,73 +1,31 @@ -## Helmfile +# Helmfile-based Mojaloop Installation -### Install helmfile +This guide covers the steps to install and manage Mojaloop using **Helmfile**. Helmfile simplifies deploying and managing Helm charts, especially in complex environments with multiple services like Mojaloop. -https://github.com/helmfile/helmfile#installation +--- -### Install Mojaloop +## Prerequisites -``` -cd local-deployment-methods/helmfile -sh update-charts-dep.sh -helmfile apply -``` +- **Kubernetes cluster** (local or cloud-based) +- **Helm** (v3+): [Install Helm](https://helm.sh/docs/intro/install/) +- **kubectl**: [Install kubectl](https://kubernetes.io/docs/tasks/tools/) +- **Docker**: Required for building and managing images +- **Helmfile**: Installation instructions below -## K3D -### Install and create K3D cluster +## Mojaloop Deployment with Helmfile -``` -wget -q -O - https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash -k3d cluster create --k3s-arg "--no-deploy=traefik@server:*" mycluster -kubectl get nodes -``` +Follow the below steps assume that you have a Kubernetes cluster up and running. ``` -k3d cluster create --api-port 6550 -p "80:80@loadbalancer" --agents 2 -export KUBECONFIG="$(k3d kubeconfig write k3s-default)" - +sh update-charts-dep.sh +cd local-deployment-methods/helmfile +helmfile apply ``` -### Deploy ingress controller - -https://kubernetes.github.io/ingress-nginx/deploy/#using-helm - -``` -helm upgrade --install ingress-nginx ingress-nginx \ - --repo https://kubernetes.github.io/ingress-nginx \ - --namespace ingress-nginx --create-namespace +## Uninstalling Mojaloop +To remove the Mojaloop deployment, use: ``` -Or +helmfile delete ``` -kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v0.43.0/deploy/static/provider/baremetal/deploy.yaml -``` - -## Microk8s - -brew install ubuntu/microk8s/microk8s - -microk8s install --channel=1.29/edge - -microk8s enable ingress - - -## Minikube - -curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-darwin-arm64 -sudo install minikube-darwin-arm64 /usr/local/bin/minikube -minikube start -minikube addons enable ingress - -## Vagrant -brew tap hashicorp/tap -brew install hashicorp/tap/hashicorp-vagrant - -brew cask install virtualbox - -## Docker desktop MacOS - -helm upgrade --install ingress-nginx ingress-nginx \ ---repo https://kubernetes.github.io/ingress-nginx \ ---namespace ingress-nginx --create-namespace -