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. |
| 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:
Property | Description |
|---|---|
innovatrics.dot.dis.persistence.cache | |
The time in seconds to persist all data created and used by Onboarding API. Example value: 1800 | |
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
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.