...
Info |
---|
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. |
Info |
---|
There are multiple routes to building and running fineract-CN. You may also want to review the minimalist approach using docker and docker-compose. |
Step 1 : What You Will Need
...
What you need to have installed | Debian/Ubuntu notes | Mac notes |
---|---|---|
Web browser (like Google Chrome) | Google Chrome On Ubuntu 16.06 |
...
...
have Oracle Java SDK 8 |
...
You can |
...
use this tutorial |
...
to do that. |
...
Install git using This Article
...
Install MySQL 5.7 Using This Guide
...
Install maven using mkyong & Ensure that artifacts are stored in $USER_HOME/.m2/repository
...
Use sdkman to install Gradle 4.5
...
Install cassandra 3.11 using this guide
...
Ensure you have Node 6.10.0+ and NPM 3+ installed.
...
Install Nginx using this guide
...
Install Node packages using npm i
See this tutorial at mkyong. |
You might have multiple Java versions installed so make sure that Java 8 is used. java |
If you're not using a Mac, then Skip Adjustment for Mac developers below
Adjustment for Mac developers
...
-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)
|
...
|
...
|
...
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
...
|
...
| ||
Install PostgreSQL
| PostgreSQL installation guide | |
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 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: Get program code
You have 3 options.
> brew services start cassandra # starts the cassandra service - noSQL database
Step 2: Clone The Repositories
Fork the Apache Fineract CN repositories to yourGithubHandle
Run the script using `bash script.sh yourGithubHandle`,
...
Recommended: You clone demo-server and let it download all dependendent fineract-cn-* libraries and projects from Artifactory to your local Maven repository
Follow the instructions:
mkdir integration-tests
cd integration-tests
git clone https://github.com/apache/fineract-cn-demo-server.git
cd fineract-cn-demo-server/
cd scripts/dependencies_to_local_maven
mvn package (this brings all the fineract-cn-* dependencies from Artifactory to your local maven repo)
cd ../..
./gradlew build- You can switch to options #2 or #3 below later, once you start changing the program code.
- Fineract uses Gradle for building but for demo server we need to get dependent projects to local maven repository because this is where demo server looks for them.
- 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 and you can use `git pull` to get latest updates
- For this option: download and run the script using `bash initial-setup.sh apache`
- 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/
- 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 created forks of apache Fineract CN repositories
- For this option: download and run the script using `bash initial-setup.sh yourGithubHandle`
- 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
Read what demo server is about. Explanatory note: To better understand what the demo server does, optionally consider manually orchestrating the services as illustrated at https://github.com/vishwasbabu/ProvisioningFineractCN. Following this link takes you to a different process.
NoteTip: On average t the build build process below 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, then you should ensure that mysqld service is inactive by `service mysql stop`. Else, you should use another default port for mysqld like 3307 say.To only work with a minimum set of services (to get started quickly), add additional flag to each of the following commands: -Ddemoserver.lite=true (more info from demo-server readme)
Prerequisites
cd into `integration-tests/fineract-cn-demo-server/build/libs/`
...
(or if you just cloned demo-server (option #1 in previous step) then just cd into build/libs)
No services locally listening on ports: 4200, 61616, 2021, 2022, 2022, 2023, 2024, 2025, 2026, 2028, 2029, 2030, 2031, 2032, 2033
Running demo-server with or without persistence
You can use key "demoserver.persistent" to run demo server in two separate modes:
- Option A - without persistence. During startup the demo server starts internal relational (PostgreSQL) and No-SQL (Cassandra) databases which are teared down when demo server is stopped and all state is lost.
- Option B - with persistence. You run the demo-server using directly your local data stores , i.e. locally-installed PostgreSQL and Cassandra. The changes are saved between restarts of demo server.
You can look up starting the internal databases from the code.
Option A - run demo-server without persistence
If you don't add argument -Ddemoserver.persistent when starting demo-server then demo-server starts up internal PostgreSQL and Cassandra databases.
- For internally launched database to be able to start accepting connections on PostgreSQL default port 3306 you need to stop your local PostgreSQL or make your locally installed PostgreSQL listen to some other port (like 3307). You can check if PostgreSQL is still listening on port 3306 using: `netstat -plnt`
- Also you need to make sure Cassandra (or any other service) is not running locally and listening on port 9042.
Use the command `java -jar -Ddemoserver.provision=true demo-server-0.1.0-BUILD-SNAPSHOT.jar`
...
(and add -Ddemoserver.lite=true if you only want a subset of services)
Option B - run demo-server with persistence
If you add -Ddemoserver.persistent=true argument when starting demo-server then demo-server doesn't launch databases internally and you need to run the databases locally yourself.
Make sure Cassandra and PostgreSQL services are started using `service postgresql start` and `service cassandra start`
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 PostgreSQL and cassandra - will have to conform to the specifications in demo-server to work. You'll have to ensure MySQLPostgreSQL's `rootpostgres` user user has password `mysqlpostgres` 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 .
...
Running for the first time - use "command I"
If you are running Fineract CN for the first time on on your OS, use i) to create MySQL command I to create PostgreSQL and Cassandra local databases.
i.) Command 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.mariadbpostgresql.host=localhost -Dcustom.mariadbpostgresql.user=root postgres -Dcustom.mariadbpostgresql.password=mysql postgres -jar demo-server-0.1.0-BUILD-SNAPSHOT.jar`
Feedback Note: If the first run failed if running command I failed for any reason, delete any residual database databases or keyspaces 'seshat' and/or 'playground' in MySQL PostgreSQL and Cassandra, and start over i.)over with command I until it succeeds.
After i.) After command I runs to completion, You could verify that databases `playground` and `seshat` have indeed been created by logging into mysqlPostgreSQL's `root` `postgres` user account and running `show databases;``\l ;`.
Also, log into Cassandra's cassandra user account and type `describe keyspaces;` to ensure that `seshat` and `playground`
If you have used i.) successfully used command I to run demo-server before, then use ii.)use command II HENCEFORTH which 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.
by command I.
Running demo-server after initial run has been successful - use "command II"
Command II: `ii.) `java -Ddemoserver.persistent=true -Dcustom.cassandra.contactPoints=127.0.0.1:9042 -Dcassandra.cluster.user=cassandra -Dcassandra.cluster.pwd=password -Dcustom.mariadbpostgresql.host=localhost -Dcustom.mariadbpostgresql.user=root postgres -Dcustom.mariadbpostgresql.password=mysql postgres -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]}
...
Troubleshooting Step 3.
- Increase max_connections in `postgresql.conf`: Edit /var/lib/pgsql/data/postgresql.conf.
- max_connection = 100 => max_connection = 260
How to verify demo server started up successfully
This takes some time so be patient. From console output you see demo-server starting up services one by one. Eventually the following services should be set up:
Service | Port | Link |
---|---|---|
Identity Service: | 2021 | http://localhost:2021/identity/v1 |
Office Service: | 2023 | http://localhost:2023/office/v1 |
Customer Service |
...
2024 | http://localhost:2024/customer/v1 | |
Accounting Service |
...
2025 | http://localhost:2025/accounting/v1 | |
Portfolio Service |
...
2026 | http://localhost:2026/portfolio/v1 | |
Deposit Service |
...
2027 | http://localhost:2027/deposit/v1 | |
Teller Service |
...
2028 | http://localhost:2028/teller/v1 | |
Reporting Service |
...
2029 | http://localhost:2029/reporting/v1 | |
Cheque Service |
...
2030 | http://localhost:2030/cheques/v1 | |
Payroll Service |
...
2031 | http://localhost:2031/payroll/v1 | |
Group Service |
...
2032 | http://localhost:2032/group/v1 | |
Notification Service |
...
...
The following log statement signals the completion of the build:
“INFO o.e.jetty.server.AbstractConnector - StoppedServerConnector@1bdb0376{HTTP/1.1,[http/1.1]}
Only after this has occurred can you move to the next step. Note that the logs won't stop after this statement.
Step 4: Run The Fims Web App
Read what fims-web-app is about.
- 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 Wait until a similar message is displayed in logs:
chunk {0} index.html 1.03 XX 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,
...
Congratulations! You’ve Successfully Ran Apache Fineract CNRelevant
Tips: Preparing For The Next Build
- Clean If you used option A: 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.
Common Issues When Running Fineract CN on a Virtual Machine
- Low Entropy: Solution - Increase Virtual Machine's Entropy using this guide .
Related articles
Content by Label | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Page properties | ||
---|---|---|
| ||
| |
...
Useful external links