DEV Community

Cover image for Configuring Apache Fineract Properly: A Practical Guide.
Kevin Wasonga
Kevin Wasonga

Posted on

Configuring Apache Fineract Properly: A Practical Guide.

I stumbled upon Apache Fineract the way many developers discover powerful open source tech while trying to solve a specific, real world problem.

If you’ve ever thought about how microfinance apps, digital lending platforms manage savings, loans, repayments, and customer accounts behind the scenes, there’s a good chance you were standing on the shoulders of systems like Fineract even if you didn’t know it yet.

Apache Fineract is a core banking engine designed for building financial services. It’s the kind of toolkit that can power microfinance institutions, fintech startups, digital wallets, and more. Think of it like an operating system but for money.

It’s open source, APIfirst, and extremely extensible. But like many powerful tools, it doesn’t come prepackaged with a nice “doubleclick start” installer. To get it running reliably, especially in production, proper configuration matters.

That’s where this guide comes in:
Let’s skip the marketing and focus on getting it done right.

📁 1️⃣ Repository and Directory Setup

git clone https://github.com/apache/fineract.git
cd fineract
Enter fullscreen mode Exit fullscreen mode

Dependencies:

Java 17+
Gradle (wrapper provided)
MariaDB (preferred) or MySQL

🗄️ 2️⃣ Database Configuration (MariaDB Recommended)

Create the Main Database

CREATE DATABASE fineract_tenants CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
Enter fullscreen mode Exit fullscreen mode

Create a Fineract Database User

CREATE USER 'fineract'@'localhost' IDENTIFIED BY 'StrongPasswordHere';
GRANT ALL PRIVILEGES ON fineract_tenants. TO 'fineract'@'localhost';
FLUSH PRIVILEGES;
Enter fullscreen mode Exit fullscreen mode

Ensure the user has:

CREATE
ALTER
DROP
INSERT
SELECT
UPDATE
DELETE

3️⃣ Configuring application.properties

Location:
fineractprovider/src/main/resources/config/application.properties

Key configurations to review/edit:

 Database Connection
fineract.datasource.url=jdbc:mariadb://localhost:3306/fineract_tenants
fineract.datasource.username=fineract
fineract.datasource.password=StrongPasswordHere

 Liquibase Migrations
fineract.database.schemausername=fineract
fineract.database.schemapassword=StrongPasswordHere
Enter fullscreen mode Exit fullscreen mode

⚠️ Security Tip: Never commit application.properties with credentials to version control.

4️⃣ Running Database Migrations with Liquibase

./gradlew databaseMigration
Enter fullscreen mode Exit fullscreen mode

Common Issue:
ERROR 1044 (42000) → Usually permission related → Verify user grants with:

SHOW GRANTS FOR 'fineract'@'localhost';
Enter fullscreen mode Exit fullscreen mode

5️⃣ Running Fineract (Dev Mode)

./gradlew bootRun
Enter fullscreen mode Exit fullscreen mode

Default REST endpoint (secured with basic auth):

https://localhost:8443/fineractprovider/api/v1/clients
Enter fullscreen mode Exit fullscreen mode

6️⃣ HTTPS Configuration (Recommended for Production)

Recommended setup: Reverse Proxy with NGINX + Let’s Encrypt

Example nginx.conf snippet:

server {
    listen 443 ssl;
    server_name yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    location / {
        proxy_pass https://localhost:8443/;
        proxy_set_header Host $host;
        proxy_set_header XRealIP $remote_addr;
    }
}
Enter fullscreen mode Exit fullscreen mode

7️⃣ Configuring Tenants (MultiTenant Support)

Fineract supports multitenant architecture.

Example fineract_tenants.tenant_server_connections row:

INSERT INTO tenant_server_connections (id, tenant_identifier, schema_server, schema_name, schema_username, schema_password, schema_port)
VALUES (1, 'default', 'localhost', 'fineract_default', 'fineract', 'StrongPasswordHere', 3306);
Enter fullscreen mode Exit fullscreen mode

Each tenant points to its own schema/database.

8️⃣ Logging Configuration

Location:
fineractprovider/src/main/resources/logbackspring.xml

Adjust log level here:

<root level="INFO">
    <appenderref ref="STDOUT"/>
</root>
Enter fullscreen mode Exit fullscreen mode

Example change for debugging:

<root level="DEBUG">
Enter fullscreen mode Exit fullscreen mode

Logs output:
build/fineract.log or console with bootRun

9️⃣ Externalized Configuration (Advanced)

For larger deployments:
Consider using Spring Cloud Config or environment variables to manage credentials securely.

Example override using environment variables:

export FINERACT_DATASOURCE_USERNAME=fineract
export FINERACT_DATASOURCE_PASSWORD=StrongPasswordHere
Enter fullscreen mode Exit fullscreen mode

1️⃣0️⃣ API Authentication Configuration

API access requires Basic Auth by default.

curl u tenantId+username:password https://yourdomain.com/fineractprovider/api/v1/clients
Enter fullscreen mode Exit fullscreen mode

For advanced deployments, consider integrating with OAuth2 or external Identity Providers.

1️⃣1️⃣ Docker (Optional)

Fineract does not yet maintain an official Dockerfile in the main repo, but you can find community supported ones here:
https://github.com/apache/fineract/pull/1922

Conclusion

Apache Fineract provides a serious foundation for modern fintech products but it expects you to know what you’re doing with configuration.

Get these pieces right, and you’ll have a reliable, extensible platform that can run everything from a neighborhood SACCO to the next big neobank startup.

Top comments (0)