Skip to content

Onboarding.md

Latest commit

 

History

History
272 lines (183 loc) · 9.28 KB

Onboarding.md

File metadata and controls

272 lines (183 loc) · 9.28 KB
Raw

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 central-ledger:

1.1. macOS

#none - you have everything you need!

1.2. Linux

[todo]

1.3. Windows

[todo]

2. Installing and Building

Firstly, clone your fork of the central-ledger onto your local machine:

git clone https://github.com/<your_username>/central-ledger.git

Then cd into the directory and install the node modules:

cd central-ledger
npm install

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

3. Running Locally (with dependencies inside of docker)

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 central-ledger inside of docker-compose with the rest of the dependencies to make the setup a little easier: Running Inside Docker.

1. Set up the MySQL container, and give it time to initialize

Note: Before starting all of the containers, start the mysql container alone, to give it some more time to set up the necessary permissions (this only needs to be done once, or every time you remove and re-create the container).

docker-compose up mysql

2. Run all of the dependencies in docker-compose:

# start all the dependencies inside of docker
docker-compose up ml-api-adapter mysql kafka mockserver temp_curl

3. Configure the default files and run the server

# disable SIDECAR in config/default.json temporary by setting 
# "SIDECAR": { "DISABLED": "true", ...

# set the CLEDG_DATABASE_URI* environment variable:
export CLEDG_DATABASE_URI=mysql://central_ledger:password@localhost:3306/central_ledger

# start the server
npm run start

4. Populate the test database

./test/util/scripts/populateTestData.sh

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]

4. Running Inside Docker

We use docker-compose to manage and run the central-ledger along with its dependencies with one command.

Note: Before starting all of the containers however, start the mysql container alone, to give it some more time to set up the necessary permissions (this only needs to be done once). This is a short-term workaround because the central-ledger doesn't retry it's connection to MySQL.

1. First run the mysql container, then run the test of the containers

docker-compose up mysql #first time only - the initial mysql load takes a while, and if it's not up in time, the central-ledger will just crash

npm run docker:up

This will do the following:

  • docker pull down any dependencies defined in the docker-compose.yml file
  • docker build the central-ledger image based on the Dockerfile defined in this repo
  • run all of the containers together

2. Populate the test database - this only needs to be done once

./test/util/scripts/populateTestData.sh

4.1 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

4.2 (Optional) Connecting MySQLWorkbench to MySQL inside Docker

If you installed MySQLWorkbench from the general onboarding guide, follow these instructions to get MySQLWorkbench connected to the mysql container running in docker.

Please follow the below instructions:

  1. Click the add (+) icon

  1. Enter the following details:

    • Connection Name: central_ledger@localhost
    • Username: central_ledger

    And Click "Test Connection"

  1. Enter the Password: 'password' > click "OK"

  1. If successful, you will see the following dialogue:
    • click "OK" to dismiss the dialogue
    • click "OK" once more to confirm the database connection

  1. This should now be shown on you MySQLWorkbench dashboard
    • click on the connection to open the database

  1. In the top left, click the schema tab > and expand central_ledger section
    • You should see the central_ledger database underneath
    • if you haven't yet started your server, no tables will be present, but they will be populated when you start your server

5. Testing

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

# unit tests:
npm run test:unit

# integration tests
npm run test:integration

# check test coverage
npm run test:coverage

5.1 Testing the central-ledger API with Postman

Note: Make sure you have installed Postman and cloned the mojaloop/postman repo, which contains all the required collections and environments. You can find detailed instructions for this in the general onboarding guide.

Prerequisites:

  • ml-api-adapter and central-ledger services running (follow Running Locally or Running Inside Docker to get these services up and running)
  • Optionally, run central-timeout , cental-settlement as well.

Running Example Requests

  1. Import the Mojaloop v0.1 draft collection, and open API Examples > mojaloop v1.0 > 6.a. Transfer Prepare Request
  2. Click Send
  3. If you get a valid response, continue to the next step, otherwise it reveals an issue in your configuration.
  4. Select the 7.a. Transfer Fulfil Request and perform a corresponding fulfilment request
  5. You can check the database to see the transfer state, status changes, positions and other such information. After this if everything looks good, you should be ready to go.

6. Common Errors/FAQs

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

Resolved by installing v2.0.3 npm install sodium@2.0.3

6.2 ./src/argon2_node.cpp:6:10: fatal error: 'tuple' file not found

Resolved by running CXX='clang++ -std=c++11 -stdlib=libc++' npm rebuild

6.3 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