This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Page tree
Skip to end of metadata
Go to start of metadata

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 installedDebian/Ubuntu notesMac notes
Web browser (like Google Chrome)Google Chrome On Ubuntu 16.06 LTSGoogle Chrome 
Ensure that you have Oracle Java SDK 8You 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:

export JAVA_HOME=`/usr/libexec/java_home -d 64 -v "1.8*"`
launchctl setenv JAVA_HOME `/usr/libexec/java_home`

Install GitInstall git using This ArticleHere we use 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
  • you can specify version "@version.number", without the "@" sign brew assumes the most recent stable release 
  • you can install all at same go: brew install git, maven, gradle, cassandra, npm, node

    brew install git
Install MySQL 5.7

You don't need to install MySQL if you just
want to run demo server
without persistence (Option A in Step 3).
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
Install maven using mkyong brew install maven

Optional step: install Gradle

This step is optional as all the Fineract CN
applications package Gradle wrapper into
the project, run it: ./gradlew

Use sdkman to install Gradle 4.5brew install gradle

You need NoSQL database
Cassandra 3.11 running.

You don't need to have Cassandra
running if you just
to run demo server
without persistence (Option A in Step 3).

Alternative: If you have Docker installed you
have the option to not install Cassandra and
run it from inside a container like this:

docker run -p9042:9042 cassandra:3.11

Install cassandra 3.11 using this guide

brew install cassandra

brew services start cassandra

Node 6.10+ and NPM 3+Ensure you have Node 6.10.0+ and NPM 3+ installed.

brew install node

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 NginxInstall Nginx using this guide

Step 2: Get program code

You have 3 options.

  1. 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
      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.
  2. 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 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/
  3. 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 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.

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: 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)


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 (MariaDB) 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 MySQL 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 MySQL and Cassandra databases. 

  • For internally launched database to be able to start accepting connections on MySQL default port 3306 you need to stop your local MySQL or make your locally installed MySQL listen to some other port (like 3307). You can check if MySQL 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 MySQL services are started using `service mysql start` and `service cassandra start`.

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` .

Running for the first time - use "command I"

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

Command I: `java -Ddemoserver.provision=true -Ddemoserver.persistent=true -Dcustom.cassandra.contactPoints= -Dcassandra.cluster.user=cassandra -Dcassandra.cluster.pwd=password -Dcustom.mariadb.user=root -Dcustom.mariadb.password=mysql -jar demo-server-0.1.0-BUILD-SNAPSHOT.jar`

Note: if running command I failed for any reason, delete any residual databases or keyspaces 'seshat' and/or 'playground' in MySQL and Cassandra, and start over with command I until it succeeds.

After command I runs to completion, 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 successfully used command I to run demo-server before, then use command II HENCEFORTH which uses the local databases created by command I.

Running demo-server after initial run has been successful - use "command II"

Command II: `java -Ddemoserver.persistent=true -Dcustom.cassandra.contactPoints= -Dcassandra.cluster.user=cassandra -Dcassandra.cluster.pwd=password -Dcustom.mariadb.user=root -Dcustom.mariadb.password=mysql -jar demo-server-0.1.0-BUILD-SNAPSHOT.jar`

Troubleshooting Step 3.

  • 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 = in your /etc/mysql/mysql.conf.d/mysqld.cnf . 
  • If you experience an error related to insufficient memory  when running command 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. 

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:

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.

  • 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

Wait until a similar message is displayed in logs:

   chunk    {0} index.html 1.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.

    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


  1. There's good discussion on this thread relevant to this page... about running on a local machine, role of "demo server" for fineract-CN in development tasks, and distinctions between test types (unit, component, integration), and call out to some Jira tickets.