= Fineract Instance types

In cases where Fineract has to deal with high load, it can cause a performance problem for a single Fineract instance.
To overcome this problem, Fineract instances can be started in different instance types for better scalability and performance in a multi-instance environment:

.Fineract instance types
* Read instance
* Write instance
* Batch instance

Each instance type comes with different restrictions. The specifics can be found in the table below.

.Instance types
|===
^| ^| Read instance ^| Write instance ^| Batch instance

| Using only read-only DB connection | Yes | No | No
| Batch jobs are automatically scheduled or startable via API | No | No | Yes
| Can receive events (business events, hook template events) | No | Yes | No
| Can send events (business events, hook template events) | No | Yes | Yes
| Read APIs supported | Yes | Yes | No
| Write APIs supported | No | Yes | No
| Batch job APIs supported | No | No | Yes
| Liquibase migration initiated upon startup | No | Yes |No
|===

== Configuring instance types in single instance setup

If Fineract is running as a single instance, then all of the 3 instance types should be enabled. In this case, there is no need to worry about the configuration, because this is the default behavior.

[ditaa, target="single-instance-diagram"]
----
    +---------+
    |         |
    |  Read   |
    |  Write  |
    |  Batch  |
    |         |
    +----+----+
         |
         v
 +----------------+
 |{s}             |
 |  Fineract DB   |
 |                |
 +----------------+
----

== Configuring instance types in multi-instance setup

A common solution to dealing with the high load is to deploy 1 write and 1 batch instances and deploy multiple read instances with read replicas of the Fineract database.
In this case, the write instance and the database will be freed from part of the load, because read request will use the separated read instance and its read replica database.

[ditaa, target="multiple-read-instances-diagram"]
----
    +---------+      +---------+     +---------+         +---------+
    |         |      |         |     |         |         |         |
    |         |      |         |     |         |         |         |
    |  Write  |      |  Batch  |     |  Read   |  [...]  |  Read   |
    |         |      |         |     |         |         |         |
    |         |      |         |     |         |         |         |
    +----+----+      +----+----+     +----+----+         +----+----+
         |                |               |                   |
         +-------+--------+               |                   |
                 |                        |                   |
                 v                        v                   v
         +----------------+        +-------------+     +-------------+
         |{s}             |        |{s}          |     |{s}          |
         |  Fineract DB   +-=----->+    Read     |[...]|    Read     |
         |                |        |   Replica   |     |   Replica   |
         +----------------+        +-------------+     +-------------+
                 |                                           ^
                 |                                           |
                 +-----=-------------------------------------+
----

Also a common scenario when Close of Business jobs are running and Fineract has to deal with a high amount of processes.
(In a future release) Fineract (will be) is able to run this CoB jobs in batches.
In multi-instances environment these CoB jobs can run on multiple batch instances and they don't have any impact on the performance of the read and write processes.
The best practice is to deploy 1 master batch instance and multiple worker batch instances.

[ditaa, target="multiple-batch-instances-diagram"]
----
    +---------+      +---------+     +---------+       +---------+         +---------+
    |         |      |         |     |         |       |         |         |         |
    |         |      |         |     |         |       |         |         |         |
    |  Read   |      |  Write  |     |  Batch  |       |  Batch  |  [...]  |  Batch  |
    |         |      |         |     | Manager |       |  Worker |         |  Worker |
    |         |      |         |     |         |       |         |         |         |
    +----+----+      +----+----+     +----+----+       +----+----+         +----+----+
         |                |               |                 |                   |
         +----------------+---------------+-----------------+-------------------+
                                          |
                                          v
                                  +----------------+
                                  |{s}             |
                                  |  Fineract DB   |
                                  |                |
                                  +----------------+
----
These solutions can be mixed with each other, based on the load of the Fineract deployment.

== Configuring instance type via environment variables

The Fineract instance type is configurable via environment variables for the following 3 values:

.Environment variables
|===
^| Instance type ^| Environment variable

| Read instance | FINERACT_READ_MODE_ENABLED
| Write instance | FINERACT_WRITE_MODE_ENABLED
| Batch instance | FINERACT_BATCH_MODE_ENABLED
|===

The environment variable values are booleans (true/false). The Fineract instance can be configured in any combination of these instance types, although if all 3 configurations are false, startup will fail. The default value for all 3 values is true.

The configured Fineract instance types are easily accessible via a single Spring bean, named `FineractProperties.FineractModeProperties` that has 4 methods: `isReadMode()`, `isWriteMode()`, `isBatchMode()`, `isReadOnlyMode()`

== Liquibase Database Migration

Liquibase data migration is allowed only for write instances

== APIs

=== Read APIs are allowed only for read and write instances

A Fineract instance is ONLY able to serve read API calls when it’s configured as a read or write instance. In batch instance mode, it won’t serve read API calls.
If it’s a read or write instance, the read APIs will be served.
If it’s a batch instance, the read APIs won't be served and a proper HTTP status code will be returned.
The distinction whether something is a read API can be decided based on the HTTP request method. If it’s a GET, we can assume it’s a read call.

=== Write APIs are allowed only for write instances

A Fineract instance is ONLY able to serve write API calls when it’s configured as a write instance. In read or batch instance mode, it won't serve write API calls.
If the write APIs won't be served and a proper HTTP status code will be returned.
If it’s a write instance, the write APIs will be served except the ones related to batch jobs.
The distinction whether something is a write API can be decided based on the HTTP request method. If it’s non-GET, we can assume it’s a write call. Also, the write APIs related to batch jobs (starting/stopping jobs) will not be served either.

=== Batch job APIs are allowed only for batch instances

A Fineract instance is ONLY able to serve batch API calls when it’s configured as a batch instance. In read or write instance mode, it won’t serve batch API calls.
If the batch APIs won't be served and a proper HTTP status code will be returned.
If it’s a batch instance, the batch APIs will be served.

== Batch jobs

=== Batch job scheduling is allowed only for batch instances

Batch jobs are scheduled only if the Fineract instance running as a batch instance


== Read-only instance type restrictions

If the read mode is enabled, but the write mode and batch mode are disabled, Fineract instance runs in read-only mode.

=== Events are disabled for read-only instances

When a Fineract instance is running in read-only mode, all event receiving/sending will be disabled.

=== Read-only tenant connection support

With read separation, there’s a possibility to use read-only database connections for read-only instances.
If the instance is read-only , the DataSource connection used for the tenant will be read-only.
If the instance is read-only and the configuration for the read-only datasource is not set, the application startup will fail.

== Batch-only instance type restrictions

If the batch mode is enabled, but the read mode and write mode are disabled, Fineract instance runs in batch-only mode.

=== Receiving events is disabled for batch-only instances

When a Fineract instance is running as batch, event receiving will be disabled while sending events will be still possible since the batch jobs are potentially generating business events.