FINERACT-2336: improve asciidoc post-1.12.1 release
* update release notice years in NOTICE_RELEASE and NOTICE_SOURCE
* step 5
* simplify mention of tests: "Ensure all tests pass for this commit both in CI and locally"
* recommend GPG signing annotated release tag
* step 8: improve svn commands
* This way is simpler and more efficient, especially with a bunch of release candidate dirs in the staging area.
* step 10: mention need to test rc before +1 vote -- See:
* https://www.apache.org/legal/release-policy.html#release-approval
* https://www.apache.org/legal/release-policy.html#approving-a-release
* step 12: only PMC members can upload releases
* step 13: simplify & explain "finalize branch" instructions
* Document what worked for me for 1.12.1.
* I didn't need to create the extra `merge-$VERSION` branch and do the recursive merge.
* document how asciidoctor upgrade is blocked
* see "official docs - deps stuck" thread on fineract dev mailing list
* https://lists.apache.org/thread/7mmsj13spb11vgz0z38fhwgzwtq03brr
* can't upgrade to 4.x because of one of these:
* https://github.com/asciidoctor/asciidoctorj-pdf/issues/25
* https://github.com/jruby/jruby/issues/5573
* https://github.com/asciidoctor/asciidoctorj-pdf/issues/16
* improve asciidoc config - opt for simplicity where the complexity adds nothing
* compat-mode is off by default, no need for it here
* default optimization should be fine
* media should have been screen | print | prepress, just leave it as default instead
* page size? I really don't think this is going to be printed much, just go with default
* PDF version 1.8 is invalid, just use the default unless we someday have a good reason to pin this
* reduce copyright years sources of truth
* see also: https://docs.asciidoctor.org/pdf-converter/latest/asciidoc-attributes/
* remove unnecessary asciidoctorj 3.0.0 version string -- no need to pin this
* remove prompt character from Bash shell examples
* it isn't properly syntax-highlighted and it looks confusing with line numbers (which we might want to add)
* it isn't necessary
* the prompt character ("%" in this case) is not typically included in shell code examples because it makes it harder to copy and paste shell code examples
* $ is likely more common than % (at least on Debian/Ubuntu), but either way I'd say exclude it
* fix source code syntax labels - use "bash" only when it is actually Bash shell code
* persistence.adoc
* fix broken enumerated list
* resolves these warnings seen with, e.g.: `gradle --info doc`
* `Jul 27, 2025 8:26:48 PM uri:classloader:/gems/asciidoctor-2.0.10/lib/asciidoctor/parser.rb parse_list_item`
* `WARNING: chapters/architecture/persistence.adoc: line 104: list item index: expected 1, got 2`
* `Jul 27, 2025 8:26:48 PM uri:classloader:/gems/asciidoctor-2.0.10/lib/asciidoctor/parser.rb parse_list`
* `WARNING: chapters/architecture/persistence.adoc: line 110: list item index: expected 1, got 3`
* fix wrapping (we use hardbreaks)
* fix typo: `s/plane text/plain text/`
* switch to rouge syntax highlighter - it handles more source languages
* fix broken long shell code lines
* fix .avro file syntax highlighting (it's JSON)
* configuration-gpg.adoc
* fix accidental block continuation
* One little plus sign was making `= Email` appear verbatim in rendered output because it was interpreted as a list continuation.
* See https://docs.asciidoctor.org/asciidoc/latest/lists/continuation/#list-continuation
* recommend more secure keys
* add a line continuation for an enumerated list
* architecture-overview.puml: remove this unused (likely a "Hello World") diagram
* release-schedule.puml: fix pluralization of days
* purely aesthetic: doesn't affect chart rendering
* fix src/bin/binary tarball name typos
* missed a few in e090da2a01
* fix release branch name
* must match `release/{revnumber}`, per gitVersioning stanza in top level build.gradle
* harden.adoc: fix broken link to CISA
* fineract-doc/build.gradle
* ensure HTML task has diagrams and images availble
This commit is contained in:
Adam Monsen
@@ -213,7 +213,7 @@ The business steps are configurable through APIs:
|
||||
|
||||
Retrieving the configuration for a job:
|
||||
|
||||
[source]
|
||||
[source,text]
|
||||
----
|
||||
GET /fineract-provider/api/v1/jobs/{jobName}/steps?tenantIdentifier={tenantId}
|
||||
HTTP 200
|
||||
@@ -235,7 +235,7 @@ HTTP 200
|
||||
|
||||
Updating the business step configuration for a job:
|
||||
|
||||
[source]
|
||||
[source,text]
|
||||
----
|
||||
PUT /fineract-provider/api/v1/jobs/{jobName}/steps?tenantIdentifier={tenantId}
|
||||
|
||||
@@ -274,7 +274,7 @@ When the Inline job gets triggered then the corresponding existing job will run
|
||||
|
||||
Triggering the Inline Loan COB Job:
|
||||
|
||||
[source]
|
||||
[source,text]
|
||||
----
|
||||
POST /fineract-provider/api/v1/jobs/LOAN_COB/inline?tenantIdentifier={tenantId}
|
||||
|
||||
|
||||
@@ -33,22 +33,32 @@ The actual code can be found in the `DatabaseTypeResolver` class.
|
||||
|
||||
== Tenant database security
|
||||
|
||||
The tenant database schema password is stored in the `tenant_server_connections` table in the tenant database.
|
||||
The password and the read only schema password are encrypted using the `fineract.tenant.master-password` property.
|
||||
By default, the database property will be encrypted in the first start from a plane text.
|
||||
The tenant database schema password is stored in the `tenant_server_connections` table in the tenant database. The password and the read only schema password are encrypted using the `fineract.tenant.master-password` property. By default, the database property will be encrypted in the first start from a plain text.
|
||||
|
||||
When you want to generate a new encrypted password, you can use the `org.apache.fineract.infrastructure.core.service.database.DatabasePasswordEncryptor` class.
|
||||
|
||||
=== Database password encryption usage
|
||||
```
|
||||
java -cp fineract-provider.jar -Dloader.main=org.apache.fineract.infrastructure.core.service.database.DatabasePasswordEncryptor org.springframework.boot.loader.PropertiesLauncher <masterPassword> <plainPassword>
|
||||
```
|
||||
|
||||
[%nowrap,bash]
|
||||
----
|
||||
java -cp fineract-provider.jar \
|
||||
-Dloader.main=org.apache.fineract.infrastructure.core.service.database.DatabasePasswordEncryptor \
|
||||
org.springframework.boot.loader.PropertiesLauncher \
|
||||
<masterPassword> \
|
||||
<plainPassword>
|
||||
----
|
||||
|
||||
For example:
|
||||
```
|
||||
java -cp fineract-provider-0.0.0-48f7e315.jar -Dloader.main=org.apache.fineract.infrastructure.core.service.database.DatabasePasswordEncryptor org.springframework.boot.loader.PropertiesLauncher fineract-master-password fineract-tenant-password
|
||||
|
||||
[%nowrap,text]
|
||||
----
|
||||
java -cp fineract-provider-0.0.0-48f7e315.jar \
|
||||
-Dloader.main=org.apache.fineract.infrastructure.core.service.database.DatabasePasswordEncryptor \
|
||||
org.springframework.boot.loader.PropertiesLauncher \
|
||||
fineract-master-password \
|
||||
fineract-tenant-password
|
||||
The encrypted password: VLwGl7vOP/q275ZTku+PNGWnGwW4mzzNHSNaO9Pr67WT5/NZMpBr9tGYYiYsqwL1eRew2jl7O3/N1EFbLlXhSA==
|
||||
```
|
||||
----
|
||||
|
||||
== Data-access layer
|
||||
|
||||
@@ -85,38 +95,38 @@ The switch from Flyway (1.6.x) to Liquibase (1.7.x) was planned to be as smooth
|
||||
=== Troubleshooting
|
||||
|
||||
1. During upgrade from Fineract 1.5.0 to 1.6.0, Liquibase fails
|
||||
|
||||
+
|
||||
After dropping the flyway migrations table (schema_version), Liquibase runs its
|
||||
own migrations which fails (in recreating tables which already exist) because
|
||||
we are aiming to re-use DB with existing data from Fineract 1.5.0.
|
||||
|
||||
+
|
||||
Solution: The latest release version (1.6.0) doesn't have Liquibase at all, it
|
||||
still runs Flyway migrations. Only the develop branch (later to be 1.7.0) got
|
||||
switched to Liquibase. Do not pull the develop before upgrading your instance.
|
||||
|
||||
+
|
||||
Make sure first you upgrade your instance (aka database schema with Fineract 1.6.0).
|
||||
Then upgrade with the current develop branch. Check if some migration scripts
|
||||
did not run which led to some operations failing due to slight differences in
|
||||
schema. Try with running the missing migrations manually.
|
||||
|
||||
+
|
||||
Note: develop is considered unstable until released.
|
||||
|
||||
2. Upgrading database from MySQL 5.7 as advised to Maria DB 10.6, fails. If we
|
||||
use data from version 18.03.01 it fails to migrate the data. If we use databases
|
||||
running on 1.5.0 release it completes the startup but the system login fails.
|
||||
|
||||
+
|
||||
Solution: A database upgrade is separate thing to take care of.
|
||||
|
||||
3. We are getting `ScehmaUpgradeNeededException: Make sure to upgrade to Fineract
|
||||
1.6 first and then to a newer version` error while upgrading to `tag 1.6`.
|
||||
|
||||
+
|
||||
1.6 version shouldn't include Liquibase. It will only be released after 1.6.
|
||||
Make sure Liquibase is dropping `schema_version` table, as there is no Flyway
|
||||
it is not required. Drop Flyway and use Liquibase for both migrations and
|
||||
database independence. In case, if you still get errors, you can use git SHA
|
||||
`746c589a6e809b33d68c0596930fcaa7338d5270` and Flyway migration will be done to
|
||||
the latest.
|
||||
|
||||
+
|
||||
```
|
||||
TENANT_LATEST_FLYWAY_VERSION = 392;
|
||||
TENANT_LATEST_FLYWAY_SCRIPT_NAME =
|
||||
|
||||
@@ -156,7 +156,7 @@ For example the OfficeDataV1 Avro schema looks the following:
|
||||
.`OfficeDataV1.avsc`
|
||||
[%collapsible]
|
||||
====
|
||||
[source,avroschema]
|
||||
[source,json]
|
||||
----
|
||||
include::{rootdir}/fineract-avro-schemas/src/main/avro/office/v1/OfficeDataV1.avsc[]
|
||||
----
|
||||
@@ -175,7 +175,7 @@ This implies that for putting a single event message onto a message queue for ex
|
||||
The message schema looks the following:
|
||||
|
||||
.`MessageV1.avsc`
|
||||
[source,avroschema]
|
||||
[source,json]
|
||||
----
|
||||
include::{rootdir}/fineract-avro-schemas/src/main/avro/MessageV1.avsc[]
|
||||
----
|
||||
@@ -370,7 +370,7 @@ New Avro schemas can be easily created. Just create a new Avro schema file in th
|
||||
=== BigDecimal support in Avro schemas
|
||||
Apache Avro by default doesn't support complex types like a BigDecimal. It has to be implemented using a custom snippet like this:
|
||||
|
||||
[source,avroschema]
|
||||
[source,json]
|
||||
----
|
||||
include::{rootdir}/fineract-avro-schemas/src/main/resources/avro-templates/bigdecimal.avsc[]
|
||||
----
|
||||
@@ -380,7 +380,7 @@ It's a 20 precision and 8 scale BigDecimal.
|
||||
Obviously it's quite challenging to copy-paste this snippet to every single BigDecimal field, so there's a customization in place for Fineract.
|
||||
The type `bigdecimal` is supported natively, and you're free to use it like this:
|
||||
|
||||
[source,avroschema]
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"default": null,
|
||||
|
||||
Reference in New Issue
Block a user