You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 29 Next »

Instructions for pulling the sources, building and starting Apache Fineract CN. This guide assumes that default OS is Debian/Ubuntu flavours of Linux with some adjustments for developers using MacOS.


Step 1 : What You Will Need

If you're not using a Mac, then Skip Adjustment for Mac developers below

Adjustment for Mac developers

  • Install Google Chrome 
  • Make sure you have Oracle Java SDK 8.  See this tutorial at mkyong.
    • verify you have the correct java with > java -version # should display 

      java version "1.8.0_192" or any 1.8.* 

  • Homebrew approach (not the only package manager but one that is preferred on mac) 

    • Install homebrew to make life easier See how to instructions. 

    • on older macs, you may first need to  >xcode-select --install

    • Homebrew has "kegs" for each of the various libraries and software pieces 

> Brew help   #gets the list of commands  

> brew install mysql@5.7 
and to start the service, >brew services start mysql@5.7 

> brew git, maven, gradle, cassandra, npm node  #installs them all in one go 

notes: a) alternatively you could install each of these, one at a time;
b) you can specify which versions of some of these, without the "@" sign brew assumes the most recent stable release; 
c) npm (node package manager for javascript) is another package manager, homebrew still treats it like a keg to be installed, instructions

> brew services start cassandra # starts the cassandra service - noSQL database 


Step 2: Clone The Repositories

Feedback Note :  Ensure that you get BUILD SUCCESSFUL after iteration for EACH repository. Also ensure that artifacts show up in $USER_HOME/.m2/repository/org/apache/fineract/cn/


Step 3: Orchestrate Microservices Using The Demo-server

Tip: On average the build will take at least 30 - 40 mins to complete when building on 8 (x86-64) dedicated cores, >=16 GB of memory and an SSD drive.

Note : Given that MySQL's default port is 3306, if you're running Option A. and your mysqld's default port is 3306 (check using `netstat -plnt` ), then you should ensure that mysqld service is inactive by running `service mysql stop`. Else, you should use another default port for mysqld like 3307 say.

  • cd into `integration-tests/fineract-cn-demo-server/build/libs/`. You will use Use Option A. OR Option B below to build the demo-server jar.

    Option A. You could run the demo-server using the microservice datastores such as fineract-cn-cassandra and fineract-cn-mariadb. Use the command  `java -jar -Ddemoserver.provision=true demo-server-0.1.0-BUILD-SNAPSHOT.jar`. MySQL's default port is 3306 and may be in use when you run Fineract CN, so you may want to use another default port like 3307 say.

OR

           Option B. You could run demo-server using your local data stores , i.e. locally-installed MySQL and Cassandra.

Note that your username and password of your locally-installed datastores - mysql and cassandra - will have to conform to the specifications in demo-server to work. You'll have to ensure MySQL's `root` user has password `mysql` and Cassandra's `cassandra` user has password `password` .

Tip : If you encounter an error where MySQL can't connect such as "org.mariadb.jdbc.internal.util.dao.QueryException: Could not connect to address=(host=localhost)(port=3306)(type=master) : Connection refused (Connection refused)", then ensure that bind-address = 0.0.0.0 in your /etc/mysql/mysql.conf.d/mysqld.cnf .

Also, make sure Cassandra and MySQL services are started using `service mysql start` and `service cassandra start`.

If you are running Fineract CN for the first time on your OS, use i) to create MySQL and Cassandra local databases. 

i.) `java -Ddemoserver.provision=true -Ddemoserver.persistent=true -Dcustom.cassandra.contactPoints=127.0.0.1:9042 -Dcassandra.cluster.user=cassandra -Dcassandra.cluster.pwd=password -Dcustom.mariadb.host=localhost -Dcustom.mariadb.user=root -Dcustom.mariadb.password=mysql -jar demo-server-0.1.0-BUILD-SNAPSHOT.jar`

Feedback Note :  If the first run failed for any reason, delete any residual database 'seshat' and/or 'playground' in MySQL and Cassandra, and start over i.) until it succeeds.

After i.) runs to completion, You could verify that databases `playground` and `seshat` have indeed been created by logging into mysql's `root` user account and running `show databases;`

If you have used i.) to run demo-server before, then use ii.) HENCEFORTH which uses the local databases created in i.).

Tip : Also, if you experience an error related to insufficient memory  when running ii.), you might have to stop all java-related processes and run demo-server with the '"Xms2G -Xmx2G"  option OR just quickly restart your system altogether. 

ii.) `java -Ddemoserver.persistent=true -Dcustom.cassandra.contactPoints=127.0.0.1:9042 -Dcassandra.cluster.user=cassandra -Dcassandra.cluster.pwd=password -Dcustom.mariadb.host=localhost -Dcustom.mariadb.user=root -Dcustom.mariadb.password=mysql -jar demo-server-0.1.0-BUILD-SNAPSHOT.jar`

Tip: Be Patient While This Runs. When Your Logs Show Up; These endpoints below signifies the completion of the build. Only after this has occurred can you move to the next step

“INFO  o.e.jetty.server.AbstractConnector - StoppedServerConnector@1bdb0376{HTTP/1.1,[http/1.1]}

Identity Service: http://localhost:2021/identity/v1

Office Service: http://localhost:2023/office/v1

Customer Service: http://localhost:2024/customer/v1

Accounting Service: http://localhost:2025/accounting/v1

Portfolio Service: http://localhost:2026/portfolio/v1

Deposit Service: http://localhost:2027/deposit/v1

Teller Service: http://localhost:2028/teller/v1

Reporting Service: http://localhost:2029/reporting/v1

Cheque Service: http://localhost:2030/cheques/v1

Payroll Service: http://localhost:2031/payroll/v1

Group Service: http://localhost:2032/group/v1

Notification Service: http://localhost:2033/notification/v1“


Step 4: Run The Fims Web App

  • Open a new terminal And cd into ‘integration-tests/fineract-cn-fims-web-app'
  • Run ‘npm i’

Feedback Note :  If there are packages such as @angular-devkit or @rxjs which you aren’t installed, then do so manually at this point;

Run ’npm run dev’

̂̂̂̂> fims@0.1.0 dev /home/ikamga/Documents/Three/Code/integration-tests/fims-web-app

> ng serve --verbose --proxy-config proxy.conf.json

** NG Live Development Server is listening on localhost:4200, open your browser on http://localhost:4200/ **  ̂

……

……

……

index.html  3.69 kB       0  

   chunk    {0} index.html 1.03 kB [entry] [rendered]

webpack: Compiled successfully.

Note that, if you are running the system from a remote server, you will have to replace 'localhost' in 'http://localhost' in lines 3,10,17,etc with the IP address of your server in your proxy.conf.json file.

Feedback Note :  webpack: Compiled successfully.

    Tenant : playground

    Username : operator

    Password : init1@l 

Feedback Note : You should be on fims - backoffice at http://localhost:4200/quickAccess

Congratulations! You’ve Successfully Ran Apache Fineract CN


Relevant Tips For The Next Build

  1. Clean up your tmp folder after every build using  `sudo rm -fr /tmp/*`
  2. Ensure that all relevant ports are free by viewing them with `sudo netstat -plnt | grep port_number` and killing processing using them with `sudo kill -9 port_number`
    List Of Relevant ports: 3306, 4200, 61616, 2021, 2022, 2022, 2023, 2024, 2025, 2026, 2028, 2029, 2030, 2031, 2032, 2033
  3. Restart the system if necessary.

Related articles

 

Useful external links

Deploying spring boot jars

  • No labels