Repository navigation
feat: add Agent Skill for Mifos Reporting Plugin Docker setup (AI-276) #564
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
IOhacker
merged 1 commit into
openMF:develop
from
parth-sharma-10:AI-276-docker-compose-skill
Nov 18, 2026
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,129 @@ | ||
| --- | ||
| name: reporting-docker-compose | ||
| description: Install, verify and remove the Mifos Reporting Plugin (Eclipse BIRT) running inside Apache Fineract with Docker Compose, using the docker-compose.yml at this repository's root (PostgreSQL + a plugin build from this checkout + the apache/fineract:develop image), and generate a sample PDF report from it. Use when the user asks to install, deploy, run, start, stop, uninstall or troubleshoot the reporting plugin, BIRT reports, or Fineract with the plugin, locally or with Docker, or to generate or run a sample report. | ||
| license: MPL-2.0 | ||
| compatibility: Needs Docker with the Compose plugin (docker compose) 2.23.1 or later, curl, about 4 GB of free memory for Docker, internet access, and a clone of https://github.com/openMF/mifos-reporting-plugin. No local Java or Maven needed. Not for production. | ||
| --- | ||
|
|
||
| # Install the reporting plugin with Docker Compose | ||
|
|
||
| `docker-compose.yml` in the repository root starts three services: | ||
|
|
||
| | Service | What it does | | ||
| |---|---| | ||
| | `db` | PostgreSQL 18 with the `fineract_tenants` and `fineract_default` databases | | ||
| | `plugin-build` | Builds the plugin JAR and collects its Eclipse BIRT libraries with Maven and JDK 25, copies the shipped report designs from `birt/reports/`, then exits | | ||
| | `fineract` | `apache/fineract:develop` with the plugin and BIRT libraries on its classpath, the designs in `/app/birt/reports` and the fonts from `birt/fonts`, on `https://localhost:8443` | | ||
|
|
||
| Run every command yourself, from the repository root; don't hand the steps to the user as | ||
| instructions. Do not report success until every check in step 4 passes. | ||
|
|
||
| ## 1. Preflight | ||
|
|
||
| Run these and stop with the error if any fails: | ||
|
|
||
| ```bash | ||
| docker info --format '{{.ServerVersion}} {{.MemTotal}}' # daemon running; memory in bytes | ||
| docker compose version # Compose v2 plugin | ||
| docker compose ps -a # is the stack already there? | ||
| ``` | ||
|
|
||
| - Docker needs about 4 GB of memory for the stack. If `MemTotal` is below 4000000000, tell the user to | ||
| raise Docker's memory limit before continuing. | ||
| - If `docker compose ps -a` lists a `fineract` container, the stack is already installed. Don't | ||
| reinstall; go to step 4 and verify it. If it is stopped, `docker compose up -d` starts it again. | ||
| - Port 8443 on localhost must be free. Run `curl --noproxy '*' -s -m 2 -o /dev/null http://127.0.0.1:8443/`. The | ||
| port is free only if curl exits with code 7 (connection refused); any other exit code, including a | ||
| TLS, empty-reply or timeout error, means something listens there. If the stack isn't running, | ||
| another program has the port. Tell the user; don't stop it yourself. | ||
|
|
||
| ## 2. Start | ||
|
|
||
| ```bash | ||
| docker compose up -d | ||
| ``` | ||
|
|
||
| This returns once the build has finished and Fineract's container has started. On the first run the | ||
| build takes several minutes, mostly Maven downloads; later runs reuse the `maven-repo` volume and | ||
| the build takes about a minute. Give the command a timeout of at least 20 minutes, or run it in the | ||
| background and check `docker compose ps -a` until `plugin-build` has exited. Fineract then needs | ||
| a few minutes for its and the plugin's database migrations; step 4 waits for that. | ||
|
|
||
| ## 3. Watch for early failures | ||
|
|
||
| ```bash | ||
| docker compose ps -a | ||
| ``` | ||
|
|
||
| | Symptom | Cause and fix | | ||
| |---|---| | ||
| | `plugin-build` exited with a non-zero code | Build failed. Show `docker compose logs --tail=80 plugin-build`. `Connect timed out` or other network errors mean Maven couldn't reach a repository: run `docker compose up -d` again once (finished downloads are kept in the `maven-repo` volume), and report the error if it fails twice | | ||
| | `fineract` stays `Created` | It waits for `plugin-build` to finish and `db` to be healthy. Not a failure while the build runs | | ||
| | `fineract` restarting or `Exited` | Show `docker compose logs --tail=100 fineract`. `Connection refused` to `db` means the database wasn't ready: `docker compose restart fineract` | | ||
| | `fineract` exits with code 137 | Out of memory. Docker needs about 4 GB; ask the user to raise the limit | | ||
| | `database "fineract_default" does not exist` | The database volume was created by an older version of `docker-compose.yml`. Ask the user before `docker compose down -v` (it deletes the data), then `docker compose up -d` | | ||
| | `UnsupportedClassVersionError` or `NoSuchMethodError` in the fineract log | The Fineract image doesn't match the Fineract version the plugin is built against. Run `docker compose pull fineract` and `docker compose up -d` | | ||
| | `port is already allocated` | Something else uses port 8443. Tell the user | | ||
| | The report answers `503` with `There is no ReportingProcessService registered` | Fineract started without the plugin. Check that `docker compose ps -a` shows `plugin-build` exited with 0, then `docker compose up -d --force-recreate plugin-build fineract` | | ||
|
|
||
| ## 4. Verify (all must pass) | ||
|
|
||
| ```bash | ||
| sh .agents/skills/reporting-docker-compose/scripts/verify-install.sh | ||
| ``` | ||
|
|
||
| The script waits up to 10 minutes for Fineract's health to report `UP`, then checks that: | ||
|
|
||
| 1. Fineract's overall health is `UP` (HTTP 200 from `actuator/health`). | ||
| 2. The plugin JAR and the BIRT libraries are mounted in `/app/birt/plugin`. | ||
| 3. The admin login `mifos` / `password` works on the `default` tenant. | ||
| 4. `GET /fineract-provider/api/v1/runreports/Active_Loans_Details?output-type=PDF...` returns `200` | ||
| with a PDF. The plugin registers that report as type `BIRT` and renders it; a Fineract without the | ||
| plugin can't. | ||
|
|
||
| It exits 0 only if all four pass, and prints the last 50 lines of the Fineract log if one fails. | ||
| Exit code 2 means `fineract` isn't running (start it with `docker compose up -d`), curl is missing, or Docker isn't reachable. | ||
| Report its PASS/FAIL lines to the user as a table. If it fails, give the failure and the log | ||
| instead of a success message. On a fresh install the report has no loans in it; that is expected. | ||
|
|
||
| ## 5. Tell the user how to use it | ||
|
|
||
| - API base: `https://localhost:8443/fineract-provider/api/v1`. Run a report with | ||
| `GET /runreports/<report name>?output-type=PDF` (also `HTML`, `CSV`, `XLS`, `XLSX`) and the report's | ||
| parameters as `R_<name>`. The certificate is self-signed, so use `curl -k`, and accept the | ||
| certificate once in a browser before a web app can call the API. | ||
| - Every request needs the header `Fineract-Platform-TenantId: default`. | ||
| - Admin login: `mifos` / `password` (HTTP Basic). | ||
| - If the user asks for a sample report, run this and confirm the file starts with `%PDF` | ||
| (`head -c 4 active-loans.pdf`). It saves the `Active_Loans_Details` report for the Head Office | ||
| as `active-loans.pdf` in the repository root; on a fresh install it lists no loans. | ||
|
|
||
| ```bash | ||
| curl -k -s --noproxy '*' -u mifos:password -H 'Fineract-Platform-TenantId: default' -o active-loans.pdf \ | ||
| 'https://localhost:8443/fineract-provider/api/v1/runreports/Active_Loans_Details?output-type=PDF&locale=en&R_branch=1&R_loanOfficer=-1&R_currencyId=-1&R_fundId=-1&R_loanProductId=-1&R_loanPurposeId=-1' | ||
| ``` | ||
| - Report designs live in the `reports` volume at `/app/birt/reports`; designs uploaded for a tenant go | ||
| to `/app/birt/reports/<tenant>/`. | ||
| - To rebuild after changing the plugin source or `birt/reports/`: | ||
| `docker compose up -d --force-recreate plugin-build fineract`. | ||
|
|
||
| ## 6. Stop or uninstall | ||
|
|
||
| ```bash | ||
| docker compose stop # stop, keep the data | ||
| docker compose down # remove containers, keep the named volumes (database, plugin, reports, Maven cache) | ||
| docker compose down -v # remove everything, including the database and uploaded reports | ||
| ``` | ||
|
|
||
| Ask before running `down -v`: it deletes all Fineract data and uploaded report designs. Confirm with | ||
| `docker compose ps -a`, which should list nothing after `down`. | ||
|
|
||
| ## Rules | ||
|
|
||
| - Change the system only through the commands above. Don't edit `docker-compose.yml` or the source | ||
| unless the user asks. | ||
| - Don't run `docker system prune`, `docker volume prune`, or commands that stop or remove containers | ||
| outside this Compose project. | ||
| - The database password `postgres` and the login `mifos` / `password` are fixed values for a local | ||
| demo. The database port isn't published, and Fineract listens on 127.0.0.1 only. Tell the user to | ||
| change both before exposing the install to anyone else. |
106 changes: 106 additions & 0 deletions
106
.agents/skills/reporting-docker-compose/scripts/verify-install.sh
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,106 @@ | ||
| #!/bin/sh | ||
| # Check a Docker Compose install of the BIRT reporting plugin: Fineract health, plugin JAR and | ||
| # BIRT libraries mounted, admin login, and a BIRT report rendered to PDF. | ||
| # Waits up to 10 minutes for Fineract to report UP. Exits 0 only if all checks pass, | ||
| # 1 if a check fails, 2 if the stack isn't running or curl is missing. | ||
| # Usage: verify-install.sh (from any directory; it uses this repository's docker-compose.yml) | ||
| # No set -e: a failing check must still reach the report below. | ||
| [ -z "${ZSH_VERSION:-}" ] || emulate sh | ||
| set -u | ||
| cd "$(dirname "$0")/../../../.." || exit 2 | ||
|
|
||
| BASE=https://localhost:8443/fineract-provider | ||
| WAIT_SECONDS=600 | ||
| REPORT=Active_Loans_Details | ||
| # -1 means "all" for each filter; office 1 is the Head Office every new tenant has. | ||
| REPORT_QUERY="output-type=PDF&locale=en&R_branch=1&R_loanOfficer=-1&R_currencyId=-1&R_fundId=-1" | ||
| REPORT_QUERY="$REPORT_QUERY&R_loanProductId=-1&R_loanPurposeId=-1" | ||
| PDF=$(mktemp) || exit 2 | ||
| trap 'rm -f "$PDF"' EXIT | ||
|
|
||
| # Self-signed certificate (-k); a proxy from the environment must not handle localhost. | ||
| local_curl() { curl -k --noproxy '*' -s -m 60 "$@"; } | ||
|
|
||
| # Print the response body, a newline, then the HTTP status code. | ||
| curl_with_code() { local_curl -w '\n%{http_code}' "$@"; } | ||
|
|
||
| # Overall health is UP only with HTTP 200: Spring Boot answers 503 when the top-level status is | ||
| # DOWN, even if a component inside the body reports "status":"UP". | ||
| health_up() { | ||
| [ "${health##*"$NL"}" = 200 ] || return 1 | ||
| case "${health%"$NL"*}" in *'"status":"UP"'*) return 0 ;; *) return 1 ;; esac | ||
| } | ||
| NL=' | ||
| ' | ||
|
|
||
| command -v curl >/dev/null || { echo "error: curl is needed for the checks" >&2; exit 2; } | ||
| docker info >/dev/null 2>&1 || { echo "error: the Docker daemon isn't reachable" >&2; exit 2; } | ||
| if [ -z "$(docker compose ps -q fineract 2>/dev/null)" ]; then | ||
| echo "error: fineract isn't running; run 'docker compose up -d' in the repository root first" >&2 | ||
| exit 2 | ||
| fi | ||
|
|
||
| health="" | ||
| deadline=$(( $(date +%s) + WAIT_SECONDS )) | ||
| while :; do | ||
| health=$(curl_with_code "$BASE/actuator/health") | ||
| health_up && break | ||
| [ "$(date +%s)" -ge "$deadline" ] && break | ||
| # A container that exited won't come up; don't wait the full 10 minutes for it. | ||
| [ -z "$(docker compose ps -aq --status exited fineract 2>/dev/null)" ] || break | ||
| sleep 10 | ||
| done | ||
|
|
||
| running=$(docker compose ps -q --status running fineract 2>/dev/null) | ||
| # Exit status, not output: ls's "No such file" message also contains the file name. | ||
| docker compose exec -T fineract test -f /app/birt/plugin/birt-plugin.jar 2>/dev/null; jar_rc=$? | ||
| libs=$(docker compose exec -T fineract sh -c 'ls /app/birt/plugin/libs | grep -c birt' 2>/dev/null) | ||
| admin=$(local_curl -X POST "$BASE/api/v1/authentication" \ | ||
| -H 'Content-Type: application/json' -H 'Fineract-Platform-TenantId: default' \ | ||
| -d '{"username":"mifos","password":"password"}') | ||
| # Fineract alone has no BIRT engine: it answers 503 "There is no ReportingProcessService | ||
| # registered" here. Only the plugin answers with a PDF. | ||
| # The first report after a start also loads the BIRT engine, so it gets a longer timeout. | ||
| meta=$(local_curl -m 180 -o "$PDF" -w '%{http_code} %{content_type}' -u mifos:password \ | ||
| -H 'Fineract-Platform-TenantId: default' "$BASE/api/v1/runreports/$REPORT?$REPORT_QUERY") | ||
|
coderabbitai[bot] marked this conversation as resolved.
Resolved
|
||
| # A transfer cut off after the first bytes leaves a partial PDF; only curl's exit status shows it. | ||
| report_rc=$? | ||
| magic=$(head -c 4 "$PDF" 2>/dev/null) | ||
|
|
||
| failed=0 | ||
| # Print a PASS or FAIL line and remember a failure. Usage: report <check> <ok:0|1> <detail> | ||
| report() { | ||
| if [ "$2" -eq 0 ]; then echo "PASS $1: $3"; else echo "FAIL $1: $3"; failed=1; fi | ||
| } | ||
| if health_up; then | ||
| report "Fineract health" 0 "UP" | ||
| else | ||
| body=$(printf '%s' "${health%"$NL"*}" | head -c 200) | ||
| report "Fineract health" 1 "not UP (HTTP ${health##*"$NL"}: ${body:-no response})" | ||
| fi | ||
| if [ -z "$running" ]; then | ||
| report "Plugin mounted" 1 "can't check: the fineract container isn't running (see the log below)" | ||
| elif [ "$jar_rc" -eq 0 ] && [ "${libs:-0}" -gt 0 ]; then | ||
| report "Plugin mounted" 0 "/app/birt/plugin/birt-plugin.jar and $libs BIRT libraries" | ||
| else | ||
| report "Plugin mounted" 1 "plugin JAR or BIRT libraries missing in /app/birt/plugin" | ||
| fi | ||
| login="Admin login mifos/default tenant" | ||
| case "$admin" in | ||
| *'"authenticated":true'*) report "$login" 0 '"authenticated":true' ;; | ||
| *) report "$login" 1 "$(printf '%s' "${admin:-no response}" | head -c 200)" ;; | ||
| esac | ||
| probe="GET /api/v1/runreports/$REPORT (PDF)" | ||
| case "$report_rc:$meta:$magic" in | ||
| "0:200 application/pdf"*:%PDF) | ||
| report "BIRT report" 0 "$probe -> 200, $(wc -c < "$PDF" | tr -d ' ') byte PDF" ;; | ||
| *) report "BIRT report" 1 "$probe -> ${meta:-no response} (curl exit $report_rc):\ | ||
| $(head -c 200 "$PDF" 2>/dev/null | LC_ALL=C tr -d '\0')" ;; | ||
| esac | ||
|
|
||
| if [ $failed -ne 0 ]; then | ||
| echo | ||
| echo "Last 50 lines of the fineract log:" | ||
| docker compose logs --tail=50 fineract | ||
| fi | ||
| exit $failed | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.