Skip to main content

{project} Deployment Recommendations

Overview​

This document describes the {project} deployment best practices. For detailed information on {project} configuration, installation and features, please refer to our main https://developers.innovatrics.com/digital-onboarding/technical/remote/dot-dis/latest/documentation/[technical documentation].

System requirements​

note

While the following requirements are minimal (e.g.: we require some disk space for the app itself, logging and configuration), please refer to the https://developers.innovatrics.com/digital-onboarding/technical/performance/[performance measurements] page for detailed results on varying configurations.

  • Rocky Linux 9.x (64-bit)
  • A CPU supporting the AVX2 instruction set
  • Unless agreed otherwise, the machine hosting the {project} needs to be able to access the URL innovatrics.count.ly.

Minimal system requirements​

  • CPU: 2 vCPU
  • RAM: 7 GB
  • DISK: 4 GB

License​

There are different methods for obtaining the license for {project} below and above version 1.20.0 of the project. To access additional information, please refer to our technical documentation for detailed https://developers.innovatrics.com/digital-onboarding/technical/remote/dot-dis/latest/documentation/#_activate_the_dot_license[license information].

warning

If you want to exchange license, the {project} instance needs to be restarted. The bearer token should not be hardcoded, new license will also change your token.

Monitoring​

To ensure the optimal performance and stability of {project} and cache infrastructure, we strongly recommend to use a monitoring tool.

We have good experience with https://prometheus.io/[Prometheus] for monitoring purposes and https://jmeter.apache.org/[Apache JMeter], that we employed for our https://developers.innovatrics.com/digital-onboarding/technical/performance/[performance testing]. However, the choice of monitoring and testing tools is ultimately up to you, based on your project's specific requirements and preferences.

{project} version upgrading​

Upgrading the {project} on live production may cause temporary cache inconsistencies. To avoid these issues, we strongly recommend scheduling a maintenance window for the upgrade.

Scaling​

The {project} is recommended to be scaled horizontally. Multiple service instances can utilize either a shared cache or a cache cluster. If the DIS service is scaled horizontally, you can usually achieve higher throughput or lower latency if your server is overloaded.

note

We strongly recommend using compute-optimized instances (eg. AWS C6a.xlarge) for scaling.

note

We suggest deploying at least two instances of the {project} and cache to enhance availability.

warning

Maintain software version and configuration consistency across all {project} within cluster. Different versions and configurations of {project} instances within cluster might cause compatibility issues and unexpected behavior.

.Horizontal scaling of {project} with a cache cluster Architecture diagram

note

To minimize network latency and improve the overall performance of your application, we recommend hosting {project} instances and Cache in the same (or nearest) region as middleware when using a cloud-based hosting solution like AWS.

Cache​

The {project} currently supports Redis, Memcached and EhCache as the cache options.

Redis is our preferred cache option over Memcached due to its high availability characteristics.

For development and test purposes, the embedded EhCache is also available. However, please note that this option is not suitable for production or an environment with multiple {project} instances.

You can also use cloud-based cache service (e.g.: AWS Elasticache) to minimize the need for managing and maintaining a dedicated cache infrastructure.

note

We recommend to use at least two cache instances to achieve higher availability.

note

Various tools exist to monitor the performance of your Redis or Memcached server, and we recommend using one to ensure the cache is performing as expected.

warning

To maintain independence and optimize resource utilization, you should deploy different cache options on a separate cluster. Cache infrastructure and {project} instances should also run on separate machines.

Cache performance recommendations​

For optimal performance, configure the expiration of records according to the nature of the implemented process:

  • Short expiration time causes smaller memory usage and higher throughput of short requests.
  • Long expiration time enables longer processing of cached records and higher memory requirements.

Memory consumption for longer processes can be lowered by cleaning records once no longer needed. The API provides deletion methods for each resource.

Common cache record expiration configuration​

Every cache option supports setting the expiration time for both customer and face records. The expiration time can be configured independently for all of these resources. The configuration is described in the table below:

|=== h|Property h| Description 2+| innovatrics.dot.dis.persistence.cache .^a|* customer-expiration[[property-cache-onboarding-expiration]] a|The time in seconds to persist all data created and used by Onboarding API.

Example value: 1800 .^a|* face-expiration[[property-cache-face-expiration]] a|The time in seconds to persist face records created and used by Face API. |===

Redis​

The {project} supports Redis as a cache option in various setups which depend on the configuration of your environment. The Lettuce client is used for communication with Redis.

note

We require the Redis server to be of version 7.x.x. Using older versions or a higher major version may result in an unexpected behavior.

Minimal Redis requirements​

Version: 7.x.x

We recommend two nodes with the following configuration:

  • CPU: 2 vCPU
  • RAM: 3 GB

Redis environments​

The following Redis environment setups are supported:

  • Standalone - The standalone mode is the simplest mode of operation. It is suitable for development and testing environments.
  • Master/Replica - The master/replica mode is suitable for production environments. The client is configured in a way where the reads are set to be preferred on the replicas.
  • Cluster The cluster mode is suitable for high-performance production environments with the need for automatic failover.
warning

Ensure that the expiration time for Redis records is accurately configured to optimize memory usage.

To access additional information, please refer to our technical documentation for https://developers.innovatrics.com/digital-onboarding/technical/remote/dot-dis/latest/documentation/#_redis[Redis cache configuration properties].

Memcached​

Minimal Memcached requirements​

We recommend two nodes with the following configuration:

  • CPU: 2 vCPU
  • RAM: 3 GB
warning

Ensure that the expiration time for Memcached records is accurately configured to optimize memory usage.

To access additional information, please refer to our technical documentation for https://developers.innovatrics.com/digital-onboarding/technical/remote/dot-dis/latest/documentation/#_memcached[Memcached cache configuration properties].

EhCache​

This cache option intended for development and test purposes only. Each instance of {project} runs its own embedded EhCache, which is not shared between other instances. This means that running multiple {project} instances in cluster mode will lead to unexpected behavior.

You can set the maximum memory size for the embedded cache through configuration properties. This includes options for both Java heap and off-heap memory. While Java heap memory is faster for I/O operations, it incurs a performance cost due to Java garbage collection. For the {project}, this performance difference is expected to be negligible.

warning

The off-heap-size property is used to set the maximum allocation size in megabytes for Java off-heap memory. If the off-heap-size property is not specified, the cache will exclusively utilize Java heap memory. To access additional information, please refer to our technical documentation for https://developers.innovatrics.com/digital-onboarding/technical/remote/dot-dis/latest/documentation/#_ehcache[EhCache configuration properties].

Docker​

The {project} running inside the container, built from Dockerfile, runs under dot-dis user and not as root user. This may cause issues with files and directories mounted from outside the docker container (e.g. logs directory). To overcome this issue, ensure that the user’s UID (User ID) on the host machine, who owns the file or directory, matches the UID of the dot-dis user, which is 1000.

Alternatively, you have the option to build the Docker container using the root-user.Dockerfile, which runs Digital Identity Service under the root user and does not have this limitation.

The JVM configuration can be customized using the JAVA_OPTS environment variable when running the Docker container. This can be useful when adjusting parameters like Java max heap memory size.

Example use: 1. docker run -e JAVA_OPTS="-Xmx1024m" -v /local/path/to/license/dir/:/srv/dot-digital-identity-service/license -v /local/path/to/config/dir/:/srv/dot-digital-identity-service/config -v /local/path/to/logs/dir/:/srv/dot-digital-identity-service/logs -p 8080:8080 dot-digital-identity-service 1. To access additional information, please refer to https://developers.innovatrics.com/digital-onboarding/technical/remote/dot-dis/latest/documentation/#_activate_the_dot_license[docker section] in our technical documentation.

Conclusion and Final Recommendations for Deploying DIS​

  • The Digital Identity Service is recommended to be scaled horizontally.
  • Cache clusters and {project} instances should be on separate machines.
  • Different cache options should be on separate clusters.
  • Our caching options are Redis, Memcached and EhCache.
  • EhCache should be used for development and test purposes only.
  • Our preferred caching option is Redis.
  • If the off-heap-size property is not specified, the cache will exclusively utilize Java heap memory.
  • If you want to exchange license, the Digital Identity Service instance needs to be restarted.
  • The bearer token should not be hardcoded, new license will also change your token.
  • We highly suggest employing at least two Cache and {project} instances to improve availability.
  • Software version and configuration of {project} instances within a cluster should be consistent.
  • To ensure the optimal performance and stability of {project} and cache infrastructure, we strongly recommend to use a monitoring tool.
  • The JVM configuration can be customized using the JAVA_OPTS environment variable when running the Docker container.
  • We strongly recommend using compute-optimized instances for scaling.
  • We recommend scheduling a maintenance window for the upgrade to avoid cache problems.

Transaction Counting System (TCS)​

In case of a deployment without an active online connection, the Transaction Counting System (TCS) is required to run locally so that {project} can report transactions to the local instance of TCS instead of the public instance available at tcs.innovatrics.com. The TCS stores the transaction count and provides export of the data that can be imported via CustomerPortal. TCS can run in Docker or as JAR and requires a database to store the transactions.

Database​

TCS requires a relational database to store the transactions in offline mode. The database can run as a Docker container or natively, as long as it can be reached by TCS.

We currently support PostgreSQL version 18 and above. One reported transaction takes up approximately 1 kB of database storage, allowing you to estimate the storage size needed for the database.

Backup mechanism should be set up for the database running in any mode in case of a disaster.

Docker​

The easiest way to run TCS is in Docker, since the database can also be run as a Docker container and doesn't have to be deployed manually. The web app for making exporting reports from TCS also runs in a docker container.

TCS has its configuration file with default settings bundled in and requires only a small configuration regarding database connection, which can be done via environment variables as shown in the following example. Below is an example docker-compose.yaml file containing services necessary to run TCS. If an online connection is available during the first run of Docker Compose, the images for TCS and the database can be downloaded automatically. As for the TCS image, which is located in our private repository, refer to this section.

Below is an example docker-compose.yaml file containing services necessary to run TCS, as well as the web UI for making exports. Please note that it serves as a demonstration of how both services can be run as Docker containers and is not meant as a production-ready solution.

[source,yaml] 1. services: transaction-counting-system: ![source]("registry.platform-staging.innovatrics.com/application-platform/docker/transaction-counting-system:1.8.2" container_name: transaction-counting-system hostname: transaction-counting-system ports: - "10600:10600" environment: INNOVATRICS_PLATFORM_TRANSACTIONS_RABBITMQ_ENABLED: false INNOVATRICS_PLATFORM_TRANSACTIONS_DATABASE_ENABLED: true SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/transaction-counting SPRING_DATASOURCE_USERNAME: postgres # Matches set POSTGRES_USER from postgres service SPRING_DATASOURCE_PASSWORD: postgres # Matches set POSTGRES_PASSWORD from postgres service SPRING_LIQUIBASE_ENABLED: true

depends_on:
  - postgres
networks:
  - tcs_network

postgres: image: postgres:18 container_name: postgres ports: - "5432:5432" environment: POSTGRES_DB: transaction-counting POSTGRES_USER: postgres # Change default user POSTGRES_PASSWORD: postgres # Change the password volumes: # Volume Mount for the actual PostgreSQL Data # This ensures your database files are persisted outside the container and data is not lost when the container is stopped or restarted. # Furthermore, IO performance is better when writing to host file system as opposed to container's writable layer - type: volume source: pgdata target: /var/lib/postgresql

  # Bind Mount for Backups (Host location: ./backups, Container location: /backups)
  # pg_dump files can be saved to /backups inside the container
  # and they will appear in the 'backups' folder relative to this docker-compose file on the host file system.
  - type: bind
    source: ./pg_backups
    target: /backups
networks:
  - tcs_network

offline-tcs-exporter: image: "registry.platform-staging.innovatrics.com/innovations/docker/ote:0.2.0-406cf43a" container_name: offline-tcs-exporter hostname: offline-tcs-exporter ports: - "3000:4000" environment: PORT: 4000 TCS_URL: http://transaction-counting-system/transaction-system/v1/transaction/export depends_on: - transaction-counting-system networks: - tcs_network

networks: tcs_network:

volumes: pgdata: 1. To start docker containers, run the following command:) 1. docker compose run -d 1. ### JAR If running Docker is not viable or desired, TCS can be run locally. The TCS bundle includes the application JAR file. Java Runtime Environment 21 is required to run the application and the database needs to be running and be reachable on the host machine running TCS.

Replace values for SPRING_DATASOURCE_URL, SPRING_DATASOURCE_USERNAME and SPRING_DATASOURCE_PASSWORD based on your database setup and run the following command to start TCS:

[source,bash] 1. INNOVATRICS_PLATFORM_TRANSACTIONS_DATABASE_ENABLED=true
INNOVATRICS_PLATFORM_TRANSACTIONS_RABBITMQ_ENABLED=false
SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/transaction-counting
SPRING_DATASOURCE_USERNAME=postgres
SPRING_DATASOURCE_PASSWORD=postgres
SPRING_LIQUIBASE_ENABLED=true
java -jar transaction-counting-system-1.8.2.jar 1. ### TCS Export UI In order to run the TCS export tool without docker, you will need to have Node installed (v24.9.0). Then, configure the port on which the server should start as well as the connection to the TCS in the .env file (adhere to .env.example). Then start the web server with the following command and visit the corresponding url:

[source,bash] 1. npm run start ....