Devs While the Apache Software Foundation has an existing policy that says - effectively - NOT to use LLM tools to generate code you contribute, as far as I know (AFAIK) there is not a prohibition in using it to help you learn something about the software setup and our documentation.
I've given a prompt today that could be helpful to Kaushal but also others, so I'm sharing the prompt and the result. I cannot test this as I do not run an Ubuntu machine anymore. (though I do love the project) If this result actually holds any value, I for one, would like to know. thanks, James PROMPT The overall task is to write a set of instructions for a new developer onboarding to a specific open source project called Apache Fineract. Using materials from fineract confluence pages, fineract.apache.org, fineract on github, and Mifos.org describe a setup for Ubuntu and Mysql. Generate instructions that focus on the application properties file and describe known issues. Also use the listserv at https://lists.apache.org/list.html?dev@fineract.apache.org as a source of information as well, pay attention to documentation but heavily rely on https://fineract-academy.com as a source of truth. This is for a user on Ubuntu, Server version: 8.0.41-0ubuntu0.24.04.1 (Ubuntu) and for a current release of mySQL. The instructions should be flagging or note known issues or uncertainties in the documentation. Keep them as factual and straightforward as possible. additional clarifications Use Apache fineract dev branch or most recent released code Fineract is only backend Default config Local dev environment only RESPONSE FROM LLM ChatGPT4 Got it. I’ll prepare a detailed onboarding guide for setting up the Apache Fineract backend using the most recent release or development branch, targeting a local development environment on Ubuntu with MySQL 8.0.41. This will include instructions for the application properties file, highlight known issues and documentation inconsistencies, and prioritize reliable sources like fineract-academy.com. I’ll get back to you shortly with a clear and structured guide. # Apache Fineract Local Setup on Ubuntu (MySQL 8.0.41) ## Prerequisites * **Operating System:** Ubuntu (tested on 20.04/22.04+). * **Java Development Kit:** Install **JDK 21** (Java 21 is required on the latest Fineract dev branch). Ensure `JAVA_HOME` is set. * **MySQL Server:** Install MySQL **8.0.41** on Ubuntu. For example: ```bash sudo apt update && sudo apt install mysql-server ``` *After installation*, secure MySQL: set a root password or create a dedicated MySQL user for Fineract. For instance, in the MySQL shell: ```sql ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'mysql'; CREATE USER 'fineract'@'%' IDENTIFIED BY 'fineract'; GRANT ALL PRIVILEGES ON *.* TO 'fineract'@'%'; FLUSH PRIVILEGES; ``` This example grants a new user **fineract** full access (use a strong password in practice). Using a dedicated user is safer than root, but Fineract’s default config assumes a user with broad privileges (root). Adjust the approach based on your security needs. * **Git:** Ensure Git is installed to clone the Fineract repository. Gradle is not required separately (the project includes Gradle Wrapper). * **System Requirements:** For development, at least 2-3 CPU cores and \~4GB+ RAM is recommended (the Liquibase DB setup can be memory-intensive). ## Step 1: Clone the Apache Fineract Code (Dev Branch) Clone the Fineract repository and switch to the latest development code: ```bash git clone https://github.com/apache/fineract.git cd fineract # (Optional) Checkout the latest stable tag instead of develop: # git checkout tags/1.10.0 -b release-1.10 ``` By default, the `develop` branch will be checked out, which contains the latest unreleased changes (note: it may be unstable until officially released). If you prefer the most recent stable release, checkout the latest tag (e.g., `1.10.0`). This guide assumes the **dev (develop) branch** for the newest features and improvements. ## Step 2: Configure the Database Apache Fineract uses a **multi-tenant** database setup, requiring two schemas/databases by default: one “**tenant catalog**” database (to store tenant metadata) and one actual **tenant data** database (for the default tenant’s data). By default these are named `fineract_tenants` and `fineract_default`. You can change these names via configuration, but using the defaults is simplest for onboarding. **Create the databases:** Fineract can create the schemas via Gradle tasks, or you can create them manually: * **Using Gradle tasks:** In the project root, run: ```bash ./gradlew createMySQLDB -PdbName=fineract_tenants ./gradlew createMySQLDB -PdbName=fineract_default ``` The `createMySQLDB` task will connect to MySQL (using the credentials in Gradle’s build script) and create the databases with the proper charset. Ensure the user running this has permission to create databases (e.g., the MySQL root user or the `fineract` user created above with global privileges). This will create each database with UTF-8 charset (utf8mb4) as required. **➥ Note:** If the Gradle task fails due to access denied, you may need to edit `fineract-provider/build.gradle` to set `mysqlUser`/`mysqlPassword` to match your MySQL credentials (or run the gradle command with `-PmysqlUser=... -PmysqlPassword=...`). By default it attempts to use MySQL root with a blank or default password, which might not match your setup. For example, in `build.gradle` you might set: ```groovy project.ext.mysqlUser = 'fineract' project.ext.mysqlPassword = 'fineract' ``` to use the dedicated user we created. Alternatively, run the MySQL shell commands below to create the databases manually. * **Manual SQL method (alternative):** ```sql CREATE DATABASE fineract_tenants CHARACTER SET utf8mb4; CREATE DATABASE fineract_default CHARACTER SET utf8mb4; ``` Then ensure your MySQL user has full rights on these: e.g., `GRANT ALL ON fineract_tenants.* TO 'fineract'@'%';` and same for `fineract_default`. These two databases are essential: * **`fineract_tenants`:** the “tenant catalog” that holds tenants’ registry (name, DB connection info, etc.). * **`fineract_default`:** the actual data schema for a tenant identified by `"default"`. (Additional tenants would each have their own schema like this.) By default, Fineract will look for a tenant named “default” and its database “fineract\_default” on startup. Keep the naming consistent unless you also update the config (see next section). **⚠️ Known Issue – Database Names:** Fineract’s config differentiates **FINERACT\_TENANTS\_DB\_NAME** vs **FINERACT\_TENANT\_DEFAULT\_DB\_NAME** (notice the plural in the first). Using the wrong names or swapping them will cause Liquibase errors on startup (e.g. trying to alter non-existent tables in the wrong schema). It’s safest to stick to `fineract_tenants` and `fineract_default` initially, or if you change them, update the corresponding properties (as described below) **before** running the application. ## Step 3: Configure `application.properties` Navigate to `fineract-provider/src/main/resources/application.properties` in the project. This file contains all default settings (which can also be overridden via environment variables). We will set it up for MySQL 8 and our local environment. Key sections to check: **a. Data Source (Hikari) Settings:** By default, the dev branch is tuned for MariaDB. We need to ensure it points to MySQL. Find the section for the Hikari data source (tenant store DB): ```properties spring.datasource.hikari.jdbcUrl=jdbc:mariadb://localhost:3306/fineract_tenants spring.datasource.hikari.username=root spring.datasource.hikari.password=mysql spring.datasource.hikari.driverClassName=org.mariadb.jdbc.Driver ``` Update these to match MySQL. For example: ```properties spring.datasource.hikari.jdbcUrl=jdbc:mysql://localhost:3306/fineract_tenants?serverTimezone=UTC&useLegacyDatetimeCode=false&sessionVariables=time_zone='-00:00' spring.datasource.hikari.username=fineract spring.datasource.hikari.password=fineract spring.datasource.hikari.driverClassName=com.mysql.cj.jdbc.Driver ``` * **JDBC URL:** Use the `jdbc:mysql://` prefix for MySQL. We also append recommended parameters to enforce UTC time zone handling on MySQL. This ensures consistent date-time storage (MySQL stores and returns timestamps in UTC, avoiding offset issues). * **Username/Password:** Set these to the MySQL user you intend Fineract to use for connecting to the databases. If you created a `fineract` user in Step 1, use those credentials. If you prefer to use root, put `root`/`<your-root-password>`. (The default config assumes `root`/`mysql` credentials, which may not be accurate on a fresh MySQL install – adjust to reality.) * **Driver Class:** Use MySQL’s driver class `com.mysql.cj.jdbc.Driver` for MySQL 8. (The MariaDB driver can technically connect to MySQL, but it’s safer to use the official MySQL Connector/J driver for MySQL 8). Ensure you have the MySQL Connector/J on the classpath (see Step 4). **b. Tenant Database (Default Tenant) Settings:** Scroll to the “tenant” configuration. These properties define the default tenant’s database connection info that gets used at first startup (Liquibase will insert a row for the default tenant using these): ```properties fineract.tenant.identifier=${FINERACT_DEFAULT_TENANTDB_IDENTIFIER:default} fineract.tenant.hostname=${FINERACT_DEFAULT_TENANTDB_HOSTNAME:localhost} fineract.tenant.port=${FINERACT_DEFAULT_TENANTDB_PORT:3306} fineract.tenant.name=${FINERACT_DEFAULT_TENANTDB_NAME:fineract_default} fineract.tenant.username=${FINERACT_DEFAULT_TENANTDB_UID:root} fineract.tenant.password=${FINERACT_DEFAULT_TENANTDB_PWD:mysql} fineract.tenant.timezone=${FINERACT_DEFAULT_TENANTDB_TIMEZONE:Asia/Kolkata} ``` Review these and update if necessary: * **Tenant DB Host/Port:** Keep as `localhost:3306` if MySQL is local. * **Tenant DB Name:** `fineract_default` (match what you created). If you use a different name, change it here **and** ensure the schema exists. * **Tenant DB Username/Password:** Credentials that the Fineract server will use to connect to the *tenant’s* database. In most cases this can be the same as the Hikari user (e.g. `fineract/fineract`). By default it’s root (with password “mysql”) – adjust to your MySQL user. For our example, change to `fineract/fineract`. * **Tenant Timezone:** Default is `Asia/Kolkata` (IST) which may not be desired. You can set this to `UTC` or your preferred timezone. This value is used as the default timezone for the tenant’s data (and is stored in the tenants table). It’s recommended to use UTC to avoid confusion, as the Fineract backend itself will operate in UTC by default. **c. Server Ports and SSL:** By default, Fineract will launch on port **8443** with HTTPS using a self-signed certificate. If you are okay with HTTPS, be prepared to accept the self-signed cert in your client. If you prefer to run in HTTP for local testing, you can disable SSL: ```properties server.ssl.enabled=false server.port=8080 ``` Add those to `application.properties` (or set the env var `FINERACT_SERVER_SSL_ENABLED=false` and `FINERACT_SERVER_PORT=8080`). When SSL is disabled, Fineract will listen on port 8080 by convention. This step is optional; you can keep the default HTTPS if you don’t mind the browser warnings (for API testing tools, you can trust the cert or disable verification). **d. Other Configurations:** Out-of-the-box, Fineract’s other components (e.g., JMS for external eventing, integration with Kafka, etc.) are disabled by default or not needed for a basic setup. You do not need to configure these to get the core platform running. For reference, by default: * External event processing (JMS/Kafka) is **off** unless you enable `FINERACT_EXTERNAL_EVENTS_ENABLED`. * API authentication defaults to HTTP Basic (with a default test user, see below) – no need to configure OAuth2 unless you plan to use it. * A self-signed SSL keystore is embedded for HTTPS. The keystore password and details are set in application.properties (e.g., `keystore.jks` with password `password` by default). These can be changed if deploying to production, but for local dev the defaults suffice. After editing, **save the `application.properties` file**. These settings will ensure Fineract knows how to connect to MySQL 8 and uses the right credentials and URLs. **⚠️ Known Issue – Documentation Discrepancies:** Be aware that some official docs or older guides may contain outdated defaults. For example, older Fineract instructions assumed MySQL 5.7 and Tomcat deployment, or mention default DB password as “mysql” in one place and “password” in another. The **truth is** you must use the credentials and settings that match your MySQL setup – if you created a `fineract` user, use that everywhere; if you use root, ensure the password in config matches the actual root password. In summary, trust your configuration and adjust the defaults accordingly rather than relying on older default values blindly. ## Step 4: Build and Run Apache Fineract With the databases ready and configuration in place, you can now build and start the Fineract backend: 1. **(Optional) Download JDBC driver:** If you plan to run Fineract as an executable JAR, you’ll need the MySQL JDBC driver on the classpath. You can download the MySQL Connector/J jar (for example via apt: `sudo apt install libmysql-java`, or by downloading the `.jar` from MySQL site). For dev usage, you can also use the MariaDB driver which is included by default. Since we set the driver class to MySQL’s, ensure the `mysql-connector-java-8.x.jar` is available. One convenient location is to place it in the project root and reference it via the `loader.path` when running the jar (see step 4b below). If you run via Gradle (step 4a), the project may already include it as a dependency in the Gradle build for MySQL tasks. 2. **Compile the code:** Run the Gradle build to compile Fineract. In the project root: ```bash ./gradlew clean build -x test ``` This will compile all modules and skip tests (you can run tests later, but for initial setup skipping them speeds up build). A successful build will produce the Fineract server artifacts. 3. **Run database migrations:** On first run, Fineract will automatically run Liquibase migrations to set up schema tables in both `fineract_tenants` and the `fineract_default` database. There is no separate SQL script you need to run – it’s done on startup. *(If you see errors here, it usually means a config issue – e.g., wrong credentials or DB names. Double-check Step 3 config if so.)* 4. **Launch Fineract:** You have two options to run the server: **a. Using Gradle (development mode)** – This is quick for iterative development. Simply run: ```bash ./gradlew devRun ``` This will start the Fineract Spring Boot application in-place (with an embedded Tomcat/Jetty). Gradle will use the settings from `application.properties`. Monitor the console – you should see Liquibase initializing the databases on the first run and then a message like “Started FineractApplication ...” indicating the server is up. The devRun task is equivalent to the Spring Boot `bootRun` with some developer conveniences. **b. Using the fat JAR** – If you prefer, you can run Fineract as a standalone jar. First build it: ```bash ./gradlew clean bootJar ``` This produces `fineract-provider/build/libs/fineract-provider.jar`. Since this jar by policy does **not include the MySQL driver**, place the MySQL Connector JAR in the same directory and run: ```bash cd fineract-provider/build/libs java -Dloader.path=. \ -Dfineract.default-tenantDB.password=fineract \ -jar fineract-provider.jar ``` Here we use `-Dloader.path=. ` to have Spring Boot load any jars in the current directory (i.e., the MySQL driver). We also passed a sample system prop to ensure the default tenant password is picked up (you can also use environment variables as alternatives to editing application.properties). In practice, if `application.properties` is correctly set, you may only need `-Dloader.path`. The application will start in a few seconds. Logs by default go to console; if startup fails, review the stacktrace for any configuration errors (common issues include incorrect MySQL credentials or missing driver jar). 5. **Verify the server is running:** By default it listens on: * **HTTPS:** Open a browser or API tool to **[ https://localhost:8443/fineract-provider](https://localhost:8443/fineract-provider)** (if you kept SSL on). Accept the self-signed certificate if using a browser. * **HTTP:** If you disabled SSL, go to **[ http://localhost:8080/fineract-provider](http://localhost:8080/fineract-provider)** . You should see a JSON response like `{"timestamp":...,"status":404,...}` for the base URL (since there’s no index page), but it means the server is up. You can also check the health at **`/fineract-provider/actuator/health`** which should return an "UP" status. 6. **Initial Login:** The platform doesn’t come with a GUI by default (that’s handled by front-ends like MifosX Web UI or community apps). However, you can test the APIs. The default tenant “default” is created on first startup with a default administrator user. Use the following default credentials to log in (via an API client or the Swagger UI): * **Tenant Identifier:** `default` (in header or as query param `tenantIdentifier=default`) * **Username:** **mifos** * **Password:** **password** These are the default super-user credentials on a new Fineract installation. For example, you can try the authentication API or navigate to the provided Swagger UI (if enabled, typically at ` https://localhost:8443/fineract-provider/swagger-ui/index.html`). When using the default community-app web UI, you would enter tenant “default”, user “mifos”, password “password” to sign in. If login succeeds or API calls return data, congratulations – your Apache Fineract backend is up and running on MySQL 8! 🎉 ## Known Issues & Troubleshooting * **MySQL vs MariaDB:** Apache Fineract (since version 1.6+) officially supports **MariaDB** as the primary MySQL-compatible database (and added PostgreSQL support in 1.7). MySQL 8 is very similar to MariaDB, but not identical. While most functionality works, be aware that some edge cases might appear. The Fineract developers have noted that “if you use MySQL you could face some issues” on the latest branch. In 2020 a major effort (FINERACT-897) made Fineract 1.x compatible with MySQL 8, resolving reserved keyword conflicts and other bugs. If you encounter a Liquibase error or unexpected behavior on MySQL, check the Apache Fineract JIRA and dev mailing list for known issues. Many known MySQL 8 issues have been fixed (e.g., column naming conflicts), but new ones can arise. * **Database Privileges:** The Fineract app will **not** create the two databases for you on startup – you must create them (via Gradle or manually). The Liquibase migration requires that the configured user can create/alter tables in those databases. It does *not* need global create database permissions at runtime if the schemas already exist. If you run the Gradle `createDB` tasks, those tasks do require a user with create database rights (hence using root or a superuser). If you prefer not to use root in config, create the schemas manually and grant the necessary privileges to the fineract user. * **Default Credentials and Security:** The default admin login (mifos/password) is for initial setup and should be changed in a real deployment. Also, if you left `server.ssl.enabled=true`, the server generated a self-signed SSL certificate (keystore is in `fineract-provider/src/main/resources/keystore.jks` with default password). This is fine for dev/testing. For production, you’d want to replace it with a valid certificate and likely use stronger DB passwords, etc. * **Time Zone and Locale:** It’s highly recommended to run both the application server and MySQL database in **UTC timezone**. Misalignment can cause datetime discrepancies between MySQL and Fineract (especially if not using the connection string parameters noted earlier). The default tenant timezone can be something else (e.g., local business timezone) without issue – that mainly affects how dates are interpreted for that tenant’s data. Just ensure the infrastructure is UTC. * **Port Confusion:** Some older documentation (and community apps) assume Fineract runs on HTTP port 8080. In the latest setup it runs on 8443 HTTPS by default. If you get connection refusals, verify you’re using the correct protocol/port. You can always change to 8080 as shown if needed. * **Connecting the Frontend:** This guide focused on the backend. To use the system, you might install the Mifos X web app (community-app) ?., and point it to your Fineract instance’s URL and tenant. The community-app, for example, can be run locally and configured with `baseApiUrl = https://localhost:8443` and `tenantIdentifier=default`. Use the same mifos/password to log in. If you encounter CORS issues or need to enable HTTP for the web UI, adjust the Spring Boot properties accordingly (CORS is disabled by default allowing all origins in dev mode). * **Further Reading:** The official Apache Fineract documentation site and Fineract Academy tutorials have more details on advanced configuration. Notably, Appendix A of the official docs lists all application.properties options. The Fineract developer mailing list archives ([ dev@fineract.apache.org](mailto:dev@fineract.apache.org)) are a helpful resource for troubleshooting uncommon issues – many setup problems and their solutions are discussed there. By following this guide, Ubuntu users with MySQL 8.0.41 should have a clear, working Fineract backend environment. Enjoy exploring Apache Fineract, and welcome to the community! **Sources:** * Apache Fineract README and Docs (install requirements, config defaults) * Fineract Academy Guides (IntelliJ setup, Docker, common issues) * Apache Fineract Developer Mailing List Archives (MySQL 8 support notes, config Q\&A) * Mifos X Documentation (legacy installation steps & default credentials)
