Skip to content

Onboarding.md

Latest commit

 

History

History
287 lines (208 loc) · 8.97 KB

Onboarding.md

File metadata and controls

287 lines (208 loc) · 8.97 KB

Onboarding

Note: Before completing this guide, make sure you have completed the general onboarding guide in the base mojaloop repository.

Contents

  1. Prerequisites
  2. Installing and Building
  3. Running Locally
  4. Running Inside Docker
  5. Testing
  6. Common Errors/FAQs

1. Prerequisites

If you have followed the general onboarding guide, you should already have the following cli tools installed:

  • brew (macOS), [todo: windows package manager]
  • curl, wget
  • docker + docker-compose
  • node, npm and (optionally) nvm

In addition to the above cli tools, you will need to install the following to build and run the ml-api-adapter:

2. Installing and Building

Firstly, clone your fork of the ml-api-adapter onto your local machine:

git clone https://github.com/<your_username>/ml-api-adapter.git

Then cd into the directory and install the node modules:

cd ml-api-adapter
npm install

If you run into problems running npm install, make sure to check out the Common Errors/FAQs below.

3. Running Locally

In this method, we will run all of the core dependencies (kafka, mysql and mockserver) inside of docker containers, while running the central-ledger server on your local machine.

Alternatively, you can run the ml-api-adapter inside of docker-compose with the rest of the dependencies to make the setup a little easier: Running Inside Docker.

3.1 Run all back-end dependencies as part of the Docker Compose

Note: mockserver below is optional. Include it if you require its use.

# start all back-end dependencies in Docker
docker-compose up -d mysql kafka simulator mockserver central-ledger

This will do the following:

  • docker pull down any dependencies defined in the docker-compose.yml file, and the services (mysql, kafka, etc) specified in the above command
  • run all of the containers together
  • ensure that all dependencies (i.e. mysql, kafka) have started for each services.

3.2 Configure the DB environment variable and run the server

# start the server
npm run start

Upon running npm run start, your output should look similar to:

> @mojaloop/ml-api-adapter@4.4.1 start /fullpath/to/ml-api-adapter
> run-p start:api


> @mojaloop/ml-api-adapter@4.4.1 start:api /fullpath/to/ml-api-adapter
> node src/api/index.js

http://hostname.local:4000
  GET    /                              Metadata
  GET    /documentation
  GET    /health                        Status of adapter
  GET    /metrics                       Prometheus metrics endpoint
  GET    /swagger.json
  GET    /swaggerui/{path*}
  GET    /swaggerui/extend.js
  POST   /transfers                     Transfer API.
  GET    /transfers/{id}                Get a transfer by Id
  PUT    /transfers/{id}                Fulfil a transfer

2019-02-01T13:30:30.454Z - info: participantEndpointCache::initializeCache::start
2019-02-01T13:30:30.456Z - info: participantEndpointCache::initializeCache::Cache initialized successfully
2019-02-01T13:30:30.457Z - info: Notification::startConsumer
2019-02-01T13:30:30.458Z - info: Notification::startConsumer - starting Consumer for topicNames: [topic-notification-event]

3. Follow logs of the back-end dependencies

docker-compose logs -f

4. Running Inside Docker

We use docker-compose to manage and run the ml-api-adapter along with its dependencies with one command.

4.1 Run Central-Ledger and all dependencies as part of the Docker Compose

# start all services in Docker
docker-compose up -d

This will do the following:

  • docker pull down any dependencies defined in the docker-compose.yml file
  • docker build the ml-api-adapter image based on the Dockerfile defined in this repo
  • run all of the containers together
  • ensure that all dependencies (i.e. mysql, kafka) have started for each services.

4.2 Follow the logs

docker-compose logs -f

5. Handy Docker Compose Tips

You can run docker-compose in 'detached' mode as follows:

npm run docker:up -- -d

And then attach to the logs with:

docker-compose logs -f

When you're done, don't forget to stop your containers however:

npm run docker:stop

5. Testing

We use npm scripts as a common entrypoint for running the tests.

Note: Ensure that you stop all Docker services (docker-compose stop) prior to running the below commands.

# unit tests:
npm run test:unit

# integration tests
npm run test:integration

# functional tests
npm run test:functional

# check test coverage
npm run test:coverage

6. Testing the central-ledger API with Postman

6.1 Prerequisites:

  1. Follow the steps as described in 5.2. Verifying Mojaloop Deployment from the Deployment Guide.
  2. Clone the Postman Collection repo: 
    # Clone Mojaloop Postman repo
git clone https://github.com/mojaloop/postman.git

# Switch to postman directory
cd ./postman
  3. Refer to 4. Support Scripts for Docker-compose of the readme for additional prerequisites.

6.2 Pre-loading Test Data

Refer to section 4. Support Scripts for Docker-compose of the readme.

6.3 Running Example Requests

Refer to section 4. Support Scripts for Docker-compose of the readme.

7. Common Errors/FAQs

7.1 sodium v1.2.3 can't compile during npm install

Resolved by installing v2.0.3 npm install sodium@2.0.3

7.2 On macOS, npm install fails with the following error

Undefined symbols for architecture x86_64:
  "_CRYPTO_cleanup_all_ex_data", referenced from:
      _rd_kafka_transport_ssl_term in rdkafka_transport.o
  "_CRYPTO_num_locks", referenced from:
  ........
  ld: symbol(s) not found for architecture x86_64
clang: error: linker command failed with exit code 1 (use -v to see invocation)

Resolved by installing openssl brew install openssl and then running:

export CFLAGS=-I/usr/local/opt/openssl/include 
export LDFLAGS=-L/usr/local/opt/openssl/lib 
npm install

7.3 Docker-Compose Issues

7.3.1 On Linux, Simulator is unable to send callback to the ML-API-Adapter service

Shutdown all docker images, and modify the following line in the docker-compose: - TRANSFERS_ENDPOINT=http://host.docker.internal:3000

  simulator:
    image: mojaloop/simulator:latest
    container_name: ml_simulator
    ports:
      - "8444:8444"
    environment:
      - LOG_LEVEL=info
      - TRANSFERS_ENDPOINT=http://host.docker.internal:3000
      - TRANSFERS_FULFIL_RESPONSE_DISABLED=false
    networks:
      - ml-mojaloop-net
    healthcheck:
      test: ["CMD", "sh", "-c" ,"apk --no-cache add curl", ";", "curl", "http://localhost:8444/health"]
      timeout: 20s
      retries: 10
      interval: 30s

Replace host.docker.internal with 172.17.0.1 as per the following example:

  simulator:
    image: mojaloop/simulator:latest
    container_name: ml_simulator
    ports:
      - "8444:8444"
    environment:
      - LOG_LEVEL=info
      - TRANSFERS_ENDPOINT=http://172.17.0.1:3000
      - TRANSFERS_FULFIL_RESPONSE_DISABLED=false
    networks:
      - ml-mojaloop-net
    healthcheck:
      test: ["CMD", "sh", "-c" ,"apk --no-cache add curl", ";", "curl", "http://localhost:8444/health"]
      timeout: 20s
      retries: 10
      interval: 30s

Note: This will ensure that the simulator can send requests to the host machine. Refer to the following issue for more information or if the above ip-address is not working for you: docker/for-linux#264.

Restart all docker images.