logo logo

Deployment Recommendations

Overview

This document describes the Digital Identity Service deployment best practices. For detailed information on Digital Identity Service configuration, installation and features, please refer to our main technical documentation.

System requirements

While the following requirements are minimal (e.g.: we require some disk space for the app itself, logging and configuration), please refer to the 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 Digital Identity Service 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 Digital Identity Service below and above version 1.20.0 of the project. To access additional information, please refer to our technical documentation for detailed license information.

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.

Monitoring

To ensure the optimal performance and stability of Digital Identity Service and cache infrastructure, we strongly recommend to use a monitoring tool.

We have good experience with Prometheus for monitoring purposes and Apache JMeter, that we employed for our performance testing. However, the choice of monitoring and testing tools is ultimately up to you, based on your project’s specific requirements and preferences.

Digital Identity Service version upgrading

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

Scaling

The Digital Identity Service 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.

We strongly recommend using compute-optimized instances (eg. AWS C6a.xlarge) for scaling.
We suggest deploying at least two instances of the Digital Identity Service and cache to enhance availability.
Maintain software version and configuration consistency across all Digital Identity Service within cluster. Different versions and configurations of Digital Identity Service instances within cluster might cause compatibility issues and unexpected behavior.
Architecture diagram
Figure 1. Horizontal scaling of Digital Identity Service with a cache cluster
To minimize network latency and improve the overall performance of your application, we recommend hosting Digital Identity Service instances and Cache in the same (or nearest) region as middleware when using a cloud-based hosting solution like AWS.

Cache

The Digital Identity Service 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 Digital Identity Service 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.

We recommend to use at least two cache instances to achieve higher availability.
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.
To maintain independence and optimize resource utilization, you should deploy different cache options on a separate cluster. Cache infrastructure and Digital Identity Service 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:

Table 1. Cache record expiration configuration properties

Property

Description

innovatrics.dot.dis.persistence.cache

  • customer-expiration

The time in seconds to persist all data created and used by Onboarding API.

Example value: 1800

  • face-expiration

The time in seconds to persist face records created and used by Face API.

Redis

The Digital Identity Service 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.

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.

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 Redis cache configuration properties.

Memcached

Minimal Memcached requirements

We recommend two nodes with the following configuration:

  • CPU: 2 vCPU

  • RAM: 3 GB

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 Memcached cache configuration properties.

EhCache

This cache option intended for development and test purposes only. Each instance of Digital Identity Service runs its own embedded EhCache, which is not shared between other instances. This means that running multiple Digital Identity Service 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 Digital Identity Service, this performance difference is expected to be negligible.

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 EhCache configuration properties.

Docker

The Digital Identity Service 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:

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

To access additional information, please refer to 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 Digital Identity Service 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 Digital Identity Service instances to improve availability.

  • Software version and configuration of Digital Identity Service instances within a cluster should be consistent.

  • To ensure the optimal performance and stability of Digital Identity Service 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 Digital Identity Service 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.

services:
  transaction-counting-system:
    image: "registry.platform-staging.innovatrics.com/application-platform/docker/transaction-counting-system:1.7.0"
    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:

To start docker containers, run the following command:

docker compose run -d

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:

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.7.0.jar

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:

npm run start
← DOT iOS NFC library
DOT Digital Identity Service →