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
What you need to have installed | Debian/Ubuntu notes | Mac notes |
---|---|---|
Google Chrome | Google Chrome On Ubuntu 16.06 LTS | Google Chrome |
Ensure that you have Oracle Java SDK 8 | You can use this tutorial to do that. | See this tutorial at mkyong. |
You might have multiple Java versions installed so make sure that Java 8 is used. java -version # should display java version "1.8.0_XXX". | This tutorial teaches how to choose the correct Java version like this:
| |
Install Git | Install git using This Article | Here we use Homebrew approach (not the only package manager but one that is preferred on mac)
|
Install MySQL 5.7 | Install MySQL 5.7 Using This Guide | brew install mysql@5.7 and to start the service: brew services start mysql@5.7 |
Optional step: install Maven and ensure that artifacts are stored in $USER_HOME/.m2/repository | Install maven using mkyong | brew install maven |
Optional step: install Gradle This step is optional as all the Fineract CN | Use sdkman to install Gradle 4.5 | brew install gradle |
You need NoSQL database Alternative: If you have Docker installed you docker run -p9042:9042 -p7199:7199 cassandra:3.11 | Install cassandra 3.11 using this guide |
|
Node 6.10+ and NPM 3+ | Ensure you have Node 6.10.0+ and NPM 3+ installed. |
npm (node package manager for javascript) is another package manager, homebrew still treats it like a keg to be installed, instructions |
Node packages | npm i | npm i |
Optional step: Install Nginx | Install Nginx using this guide |
Step 2: (Optionally fork and) clone the repositories
You have two options.
- You clone Fineract CN repositories directly
- later if you want to contribute to some microservice then you have to create a fork and switch to that fork to create a pull request
- this way you don't have to fork anything
- Run the script using `bash script.sh apache`,
- You fork all the Apache Fineract CN repositories to yourGithubHandle and check out code from there.
- This way you can directly work on your forks (but your forks don't get code updates automatically with git pull)
- after you have logged in to Github with yourGithubHandle and create forks of apache Fineract CN repositories
- run the script using `bash script.sh yourGithubHandle`,
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
Note: 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`.
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 = 127.0.0.1 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 in i.) failed for any reason, delete any residual databases or keyspaces '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;`. Also, log into Cassandra's cassandra user account and type `describe keyspaces;` to ensure that `seshat` and `playground`
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.
- Open http://localhost:4200 on fims - backoffice
- Login to the platform using the credentials,
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
- Clean up your tmp folder after every build using `sudo rm -fr /tmp/*`
- 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 - Restart the system if necessary.
Related articles
Useful external links