Smile CDR v2024.08.PRE
On this page:

2.1.1Platform Requirements


This page lists requirements for installing Smile CDR. This applies only to self-hosted versions of Smile CDR. If you are using a cloud-hosted version then this page does not apply.

Note that these are the requirements that are known to work with Smile CDR. If you have other requirements in mind, they may work as well. Please contact us to discuss other options.

2.1.2Server Requirements


The following list defines the minimum server requirements for a server hosting Smile CDR. Smile CDR may be configured in a 1-node cluster if high availability is not needed, but 2+ nodes are recommended for better reliability.

  • Environment: Smile CDR may be installed to physical or virtual servers, or to Docker containers.
  • CPU: A 2-core X86-64 CPU (required); 4-core X86-64 CPU (recommended).
  • Memory: At least 4 GB of available RAM is recommended.
  • Operating System: Deployment on GNU Linux is recommended. Ubuntu and RHEL/CentOS are both known to work, but other distributions are likely also fine. We do not currently support running Smile CDR on the Microsoft Windows operating system.
  • Disk Space: Smile CDR requires an environment with at least 10 GB of free disk space. Note that large installations may require significantly more.
  • Database: Smile CDR can be used with any of the database platforms listed below.

2.1.3Java Requirements


Smile CDR is a Java application and requires a Java Virtual Machine (JVM) or Java Development Kit (JDK) installed. This is not required when using the Docker distribution of Smile CDR, since that distribution includes a JDK.

Smile CDR is supported for use against one of the following distributions of Java:

  • OpenJDK 21.0.1+ (Supported)
  • OpenJDK 17.0.1+ (Supported)

Smile CDR will run against a simple JRE (compiler tools are not required in order to use Smile CDR) but the JDK comes with many tools which can be useful for troubleshooting issues (e.g. jstack, jmap, etc.) Distributions

There are many available distributions of the Java Virtual Machine (JVM) and Java Development Kit (JDK). These include AdoptOpenJDK, Azul Zulu, Amazon Corretto, and RedHat OpenJDK. These distributions are all based on the same core OpenJDK codebase, but each vendor may add additional patches and fixes.

We recommend the Amazon Corretto JDK. Distributions

Smile CDR may also work correctly against non-OpenJDK distributions of Java (e.g. IBM J9 JDK) but these are not well-tested and are not recommended. an Unsupported JDK

You can skip the Smile CDR minimum Java version check by adding the argument -Dskipjavaversioncheck=true to your setenv file. supported versions

Supported Java VersionsSmile Version
21.0.1+ / 17.0.1+2024.02 - Later
17.0.1+ / 11.0.1+2022.05 - 2023.11
17.0.1+ / 16.0.1+ / 11.0.1+ / 10.0.1+ / 1.8.0+2022.02
16.0.1+ / 11.0.1+ / 10.0.1+ / 1.8.0+2021.08 - 2021.11
11.0.1+ (recommended) / 10.0.1+ / 1.8.0+2019.05 - 2021.05
11.0.1+ (recommended) / 1.8.0 (supported)1 - 2019.02

2.1.4Database Requirements


Smile CDR requires a relational database to use as a store for system data, such as configuration. A relational database or non-relational database can be used to store FHIR resource information. Database

The following database platforms are currently performing well at scale at a number of large enterprise installations. Smile CDR recommends running production servers on one of these database platforms.

There are several levels of database support for Smile CDR:

These platforms are considered the recommended platform versions of Smile CDR and receive functional testing as a part of every Smile CDR release. Additional performance and regression testing is also performed.

v14Standard 201912c R2
AWS Aurora (v14)Enterprise 201919c
Azure SQL

These platforms are supported by Smile CDR and receive functional testing as a part of every Smile CDR release.

12.214 (2017) Standard/Enterprise18c
11.413 (2016) Standard/Enterprise
12 (2014) Standard/Enterprise
11 (2012) Standard/Enterprise Only

These platforms are useful for experimentation, configuration validation and testing on a local workstation. They are not recommended for server deployment or any kind of production use. Data loss can occur.


These platforms do not perform well at scale and are not recommended for use. Existing users are strongly encouraged to migrate to a supported database platform.

  • MySQL (All Versions)
  • MariaDB (All Versions)
  • Apache Derby (All Versions) Database

These platforms are considered the recommended platform versions of Smile CDR and receive functional testing as a part of every Smile CDR release. Additional performance and regression testing is also performed.

5.0.13 for Database Versions Not Listed Here

Listed recommended and supported database versions have been tested and certified to work with Smile CDR. We have every expectation that more recent versions, particularly point versions will work seamlessly with Smile CDR. We do encourage that non-listed RDBMs versions be tested in a non-production environment prior to going into production. As part of our standard professional services engagement we are happy to provide that testing or to suggest a testing methodology. Distributed Data Store

The following in-memory data grids work with Smile CDR:


2.1.5Database Testing Matrix


This grid shows which versions are tested internally as part of our manual testing process.

Postgres MSSQL Server Oracle H2 MongoDB
Migration Testing 16.2 2019 Developer 19c (docker) - N/A
Smoke Testing 16.2 2019 Developer 19c (docker) - 4.2.8
Performance Testing 12.18 mssql/server:2022-latest - - -

2.1.6Support for AWS Secrets Manager JDBC Connections


The following databases are currently supported for authentication via AWS Secrets Manager: MariaDB, MSSQL, MySql, Oracle, Postgres

To use the AWS Secrets driver set the following DB properties (Postgres use case shown):

  • module.clustermgr.config.db.driver=POSTGRES_9_4
  • module.clustermgr.config.db.secrets_manager=AWS
  • module.clustermgr.config.db.url=jdbc-secretsmanager:postgresql://<db-host>:<db-port>/<db-name>
  • module.clustermgr.config.db.username=<your-defined-secret-name>
  • module.clustermgr.config.db.password=<any-non-blank-string>

Also add the following environment variables:

  • AWS_ACCESS_KEY_ID = Yous AWS account access key ID
  • AWS_SECRET_ACCESS_KEY = Yous AWS secret account access key
  • AWS_REGION = The AWS region where your secret is defined

The following steps will help you replace a regular JDBC connection string with an AWS secrets manager JDBC connection string:

  1. Add the property: secrets_manager.
  2. Replace the jdbc segment of your UL with: jdbc-secretsmanager.
  3. Set the name of your defined AWS secret as your username.
  4. Set any non-blank string as the password (is not used, but can't be blank).
  5. Set the appropriate AWS-related environment variables.

2.1.7Network Infrastructure


Smile CDR is a full featured HTTP server and is capable of directly serving client HTTP requests. It is not necessary to pair it with other network infrastructure. However, there are several other network technologies that can be combined with Smile CDR in order to achieve specific architectural goals.

The following three examples list potential network infrastructure components that can be paired with Smile CDR. Note that these are not completely separate concepts: A single piece of software (or hardware) may actually perform any or all of these functions. Balancer

Smile CDR clustering (i.e. of FHIR/REST endpoints, Web UIs, etc.) can be set up in a horizontal fashion using a variety of topologies. These include Active/Active and Active/Passive setups.

When configured in a typical Active/Active configuration, incoming HTTP requests may be distributed in a completely arbitrary (e.g. round-robin) or a predictable way (e.g. sticky-session). Smile CDR clustering makes no assumptions that multiple requests belonging to the same user session or OAuth2 token will be delivered to the same physical endpoint, so clustering can be easy to set up.

Load Balancers may be a purely software solution such as NGINX or may be a hardware or cloud infrastructure device. Proxy

A common configuration option is to place a reverse proxy such as NGINX or Apache HTTPd (with mod_proxy). The use of a reverse proxy typically fulfills one or more of the following functions: Gateway

API Gateways are popular tools in modern RESTful architectures. An API gateway typically provides several functions. Some of these functions can be provided natively by Smile CDR, meaning that a separate gateway is not necessary. Other functions require the use of a dedicated gateway.

  • Centralized Service Security (e.g. a common authentication scheme such as OAuth2 or HTTP Basic is applied to all services provided by the gateway)

Smile CDR can handle authentication and authorization of users entirely within its own security layer. The security services, including the OAuth2/SMART services are designed to be aware of FHIR data and REST patterns, meaning that Smile CDR can provide a nuanced security implementation that would be difficult or impossible to design using a standard API Gateway alone.

Smile CDR can be paired with a Gateway product however. This pairing can involve the Gateway handling user the authentication and authorization. This pairing can also put authentication and authorization decisions in both layers (i.e. in both the Gateway and in Smile CDR) for a defense-in-depth strategy.

  • Monitoring

Smile CDR can also be configured to keep detailed metrics on service utilization and performance. There are advantages however in maintaining an external monitoring tool that can raise alarms when key performance metrics fall below predetermined thresholds.

  • API Key Management

Smile CDR does not currently have the ability to manage API keys.

2.1.8Event Streaming


We support the following message services for event streaming:

ActiveMQApache Kafka