On this page:

3.0Installing Smile CDR

 

Smile CDR can be deployed to a server as an application by extracting the Smile CDR application archive file or as a Docker service by importing the Smile CDR Docker image. Once deployed, the initial installation of Smile CDR should be as simple as editing the configuration file and starting the software. We believe that software should be easy to configure, and should come with sane configuration out-of-the-box.

The following sections will provide a general overview of the basic installation process along with details for deploying Smile CDR as an application. Additional details about deploying Smile CDR as a Docker service are available at this page.

3.0.1Installing to Linux / OSX

 

The following instructions will focus on deploying the software in a Linux/OSX environment.

  1. Create a service account that the Smile CDR application will run under

    sudo adduser --system --no-create-home --disabled-login --group smile
    
  2. Extract the archive

    # Navigate to the directory you wish to install to
    cd /opt/
    
    # Extract the Downloaded Archive
    sudo tar xf /path/to/smilecdr-2020.02.PRE
    
    # Reassign the install directory to the smile user
    sudo chown -R smile:smile smilecdr
    
  3. Navigate to the smilecdr directory

    $ cd smilecdr
    

You will now see the following directories in your target folder:

  • bin/ – contains the script used to start and stop Smile CDR's server process
  • classes/ – contains configuration files
  • lib/ – contains the application itself (you should not need to interact with this directory)

3.0.2Basic Configuration

 

Before starting Smile CDR for the first time, there are two files you will want to examine for settings.

  • Environment Settings

In the bin/ directory you will find a file called setenv. This file may be used to change the amount of RAM available to Smile CDR, as well as number of other low level settings. It is a good idea to glance over it and ensure that the default settings make sense for your installation.

  • Application Configuration

In the classes/ directory, you will find a file called cdr-config-Master.properties. This file contains all of the configuration for the modules which will be created the first time the system is started. A description of these files is found below.

3.0.3Quick Start

 

With the files unpacked, you can try starting the server by executing the bin/smilecdr start command as shown below.

This will start the server using the default configuration, which is not suitable for production use but is a great first test. If you are not installing Smile CDR for the first time, you can skip this section since it will be throwaway work.

$ bin/smilecdr start
2016-11-27 22:13:06.394 INFO  Smile CDR 2017-05-R01 / master / build 1de9be72
2016-11-27 22:13:06.404 INFO  Starting Smile CDR with configuration[Master]
2016-11-27 22:13:07.420 INFO  Starting module clustermgr
2016-11-27 22:13:16.948 INFO  Starting module local_security
2016-11-27 22:13:19.658 INFO  Starting module admin_web
2016-11-27 22:13:22.984 INFO  Starting module persistence
2016-11-27 22:13:37.863 INFO  Starting module fhir_endpoint
2016-11-27 22:13:38.854 INFO  Starting module admin_json
2016-11-27 22:13:40.591 INFO  CDR has fully started in 34192ms

Assuming you see the phrase CDR has fully started, you have now started the software.

With the software started, you can try a few things (replace localhost in the URLs below with the host name of your server if you are installing to a remote server):

  • Log into the Web Admin Console at http://localhost:9100.
    • This is the administration UI for configuring the system.
    • Username: admin (by default a single user with full privileges is created)
    • Password: password
  • Log into the FHIRWeb Console at http://localhost:8001.
    • This is a FHIR testing tool which lets you explore the FHIR API.
  • Make FHIR requests against the endpoint at http://localhost:8000
    • This is an actual FHIR endpoint, so it is best to use a REST utility such as Postman to work with this endpoint. Note that by default the endpoint is secured with HTTP Basic auth, and will not accept anonymous requests.
  • Explore the JSON Admin API at http://localhost:9000.
    • This API may be used to configure the system via REST calls.

Clean Up

When you are finished with this initial test, you can delete the tempoarary database files and logs by removing the following directories:

  • [install root]/h2_database
  • [install root]/log

3.0.4The Initial Configuration

 

Before proceeding with the setup of the system, let's look at the default configuration.

The following diagram shows the modules in a default installation of Smile CDR. Of course, the first thing you will probably want to do is reconfigure/add/change/remove these modules. For now, let's look at what comes out-of-the-box.

Default Installation

This diagram shows the following modules in a one-node cluster. Note that the addresses below (e.g. http://localhost:9100/) are placeholders. If you have installed Smile CDR on a server other than your own workstation the hostname will not be localhost, and the port numbers given are simply the initial default configuration (you may change any of them as you see fit by using Smile CDR's Web Admin Console).

  • Web Admin Console (HTTP Port 9100): This module is the web-based administration UI that is used to control and configure Smile CDR. You can access this console at http://localhost:9100/. Note that by default you will have an admin user named admin with a password of password.
  • Cluster Manager: This module supplies configuration to the rest of the system and persists it in a database. By default this configuration is stored in an H2 Database on the local filesystem. Note that this is not a production strength database. It's great for getting the system up and running so you can try it out – but you will need to reconfigure the cluster manager to talk to a real database (e.g. PostgreSQL or Oracle) before doing anything serious with Smile CDR.
  • FHIR Listener (HTTP port 8000): This module is the FHIR endpoint that listens for FHIR REST client requests and responds to them. You can try this out by pointing your browser at http://localhost:8000/_history. By default you will simply get a security exception when you do this – but we will configure this later.
  • FHIR Storage (Relational): This module handles storing FHIR resources in a relational database.
  • JSON Admin API (HTTP port 9000): This module is an HTTP server serving up non-FHIR REST services for administering Smile CDR. These services can be used to perform health checks, start and stop modules, etc. These services have a Swagger documentation set you can access at http://localhost:9000/
  • Local Security: This module provides authentication for other modules (the FHIR Listener, the JSON Admin API, and the Web Admin Console). It does this by storing user accounts and salted password hashes in the Smile CDR database. In a more advanced configuration, different/separate security modules can be used for different parts of your configuration. Again, this is simply a good place to start.

3.0.5The Node Configuration Properties File

 

Every module has a set of configuration properties that can be set. For example, the FHIR Listener module is configured with a port and default encoding, whereas the Local Security module is configured with settings for case-sensitivity.

When Smile CDR starts up, it uses a configuration file to configure itself. By default this file is called cdr-config-Master.properties, and it is located in the classes directory.

This file contains several key pieces of configuration. First, it contains a section which will look like this:

################################################################################
# Node Configuration
################################################################################
node.id=Master
node.control.port=7001

Note the following properties:

  • node.id – This property identifies the ID for the node to start. In the default file that is shipped with Smile CDR, this node is called Master. You might choose to rename this if you are building a multi-node cluster but for a single node the default name is fine. In a multi-node cluster, each node must have a different ID so it is important to change this to something more appropriate. Note that node IDs must consist only of the following characters: US ASCII letters, numbers, underscore (_) and dot (.).
  • node.control.port – This property supplies a port which will be opened by the CDR process to accept connections from the startup/shutdown process. Typically, you do not need to change this unless the default port is not free on your target system.

Additional Node Configuration

Several other node configuration properties may also be placed in this file.

  • node.server_port_offset – This property specifies an offset that will be applied to all opened server ports on this node. See Server Port Offset for more information.
  • node.propertysource – This property specifies where to look for module configuration. See Module Property Source for more information.

Cluster Manager Configuration

In the configuration file, you will also see a section that looks like the following:

################################################################################
# Cluster Manager Configuration
################################################################################
module.clustermgr.config.db.driver                         =H2_EMBEDDED
module.clustermgr.config.db.url                            =jdbc:h2:file:./database/h2_clustermgr
module.clustermgr.config.db.hibernate.showsql              =false
module.clustermgr.config.db.username                       =SA
module.clustermgr.config.db.password                       =SA

This section contains the configuration properties for the cluster manager (which is given the module ID of clustermgr). The configuration for this module is read at startup, and provides the configuration for the database where the cluster manager will store settings. The default installation uses an embedded H2 Database. This should be changed before you use Smile CDR for anything beyond quick prototyping.

3.0.6Module Property Source

 

The property file may also contain definitions for modules other than the Cluster Manager. The default file that is shipped with Smile CDR contains definitions for all of the other modules listed above.

By default, these definitions are used to seed the system with a set of modules the first time it starts up. However, after the first time the CDR has been started, the configuration for these modules will be read from the configuration database instead of from this property file. In other words, if you want to modify the database configuration for the cluster manager, you must always do this in the property file. If you want to modify the configuration for any other modules after the CDR has been started for the first time then you will need to modify it in the Web Admin Console.

If you wish to override this behavior you can use the node.propertysource key in the property file to specify where to source module config. This property may have any of the following values:

  • DATABASE(this is the default if this property is not specified) Load the cluster manager configuration from the property file. Load all other modules from the database, unless no other modules are specified in the database (typically meaning that this is the first startup).
  • PROPERTIES – Load module configuration from the property file even if modules have previously been loaded. In other words, give priority to the property file even if this is not the first time the application has started.

3.0.7Variable Substitution

 

Within the property file, it is possible to put placeholders that will be evaluated. This can be used for example to pass database passwords or other runtime properties in from the underlying system environment.

There are two strategies for passing in data from the system environment:

Java System Property Substitution

System properties may be accessed from the configuration property file via the following syntax:

module.clustermgr.config.db.password=#{systemProperties['dbpassword']}

There are several standard methods for adding additional system properties:

Using the bin/setenv File:

Within the bin/setenv file, you may add system properties using the format -Dname=value. For example, the following line adds a database password to the setenv file.

JVMARGS="$JVMARGS -Ddbpassword=somepassword"

Using External File Property Sources

Within the configuration properties file, you may add references to external properties files that will be loaded into the system properties.

This is done by adding an entry (or multiple entries) in the configuration file such as the following:

node.system_properties.source.0=classpath:externalprops.properties

This example uses a file called externalprops.properties found in the classes/ directory as an additional source of system properties.

Note:

  • You may define multiple sources of external properties by adding a suffix of .0, .1, etc., to the name of the entry in the configuration file.
  • The value prefixes of classpath: (for files in the classes/ directory) and file: (for files elsewhere in the filesystem).

System Environment Variable Substitution

The underlying system environment variables are also available using the following syntax. Using this syntax means that you do not need to explicitly specify anything in the setenv file, and may be useful for some configurations (e.g. Docker Containers).

module.clustermgr.config.db.password=#{env['dbpassword']}

3.0.8Fetching Configuration Using Scripts

 

In some cases it can be useful to pull configuration values from external sources. For example, if a system such as CyberArk is being used to store database credentials, Smile CDR will need to request these credentials from CyberArk any time that it is starting relevant modules. This type of setup can be achieved using JavaScript functions that are executed when the property value is needed.

In order to define a script to fetch a property value, a file should be placed in [Smile CDR root]/classes called config-source-scripts.js. This file should have one or more functions with the following characteristics:

  • The function should take no arguments
  • The function should return a string value

In order to invoke the function, any property in Smile CDR configuration may take a value with the form {{javascript:functionName()}}.

For example, the following snippet shows a script that can be used to fetch a database credential:

function fetchPasswordFromRestService() {
	var get = Http.get('https://myauth.example.com/AIMWebService/api/Accounts?AppID=SmileCDR&Query=Safe=DB;Object=DB');
	get.execute();
	if (!get.isSuccess()) {
		throw get.getFailureMessage();
	}

	// In this example, the service returns a simple JSON document with an element
	// called "DatabaseCredential". We will use the value of that element as
	// the password to return
	var responseJson = get.parseResponseAsJson();
	var password = responseJson.DatabaseCredential;
	return password;
}

A corresponding entry in the Smile CDR configuration properties file is shown below:

module.clustermgr.config.db.driver = {{javascript:fetchPasswordFromRestService()}}

3.0.9Configuring Your Database

 

A default installation of Smile CDR has two database configuration settings. The first is for the cluster manager database, and contains configuration settings, audit trails, performance information, etc. The second is for the persistence module, which is where FHIR resources are stored.

These are defined separately for several reasons:

  • Separation allows each database to have different characteristics, or even to be hosted in separate database installations
  • Separation also allows a single cluster to host multiple FHIR repositories

However, in a basic setup it is fine for these two databases to share a single physical database schema and instance, as the tables names will not conflict. This is the default configuration of Smile CDR.

Before starting the CDR for the first time, you may want to adjust the clustermgr and persistence modules to use a database platform other than H2 (a non-production/testing database).

Postgres

The following example shows a postgres configuration:

################################################################################
# Cluster Manager Configuration
################################################################################
module.clustermgr.type                                      =CLUSTER_MGR
module.clustermgr.config.db.driver                          =POSTGRES_9_4
module.clustermgr.config.db.url                             =jdbc:postgresql://localhost/cdr
module.clustermgr.config.db.username                        =cdr
module.clustermgr.config.db.password                        =cdrpassword

################################################################################
# Database Configuration
################################################################################
module.persistence.type                                     =PERSISTENCE_DSTU3
module.persistence.requires.CLUSTERMGR                      =clustermgr
module.persistence.config.db.driver                         =POSTGRES_9_4
module.persistence.config.db.url                            =jdbc:postgresql://localhost/cdr
module.persistence.config.db.username                       =cdr
module.persistence.config.db.password                       =cdrpassword
module.persistence.config.db.hibernate_search.directory                                     =lucene/lucene_fhir_persistence

MySQL

The following example shows a MySQL configuration:

################################################################################
# Cluster Manager Configuration
################################################################################
module.clustermgr.type                                      =CLUSTER_MGR
module.clustermgr.config.db.driver                          =MYSQL_5_7
module.clustermgr.config.db.url                             =jdbc:mysql://localhost:3306/cdr?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT
module.clustermgr.config.db.username                        =cdr
module.clustermgr.config.db.password                        =cdrpassword

################################################################################
# Database Configuration
################################################################################
module.persistence.type                                     =PERSISTENCE_DSTU3
module.persistence.requires.CLUSTERMGR                      =clustermgr
module.persistence.config.db.driver                         =MYSQL_5_7
module.persistence.config.db.url                            =jdbc:mysql://localhost:3306/cdr?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT
module.persistence.config.db.username                       =cdr
module.persistence.config.db.password                       =cdrpassword
module.persistence.config.db.hibernate_search.directory                                     =lucene/lucene_fhir_persistence

3.0.10Starting the CDR

 

Once you have prepared your configuration

To start the server, simply execute the command smilecdr start as follows:

$ bin/smilecdr start
2016-11-27 22:13:06.394 INFO  Smile CDR 2017-05-R01 / master / build 1de9be72
2016-11-27 22:13:06.404 INFO  Starting Smile CDR with configuration[Master]
2016-11-27 22:13:07.420 INFO  Starting module clustermgr
2016-11-27 22:13:16.948 INFO  Starting module local_security
2016-11-27 22:13:19.658 INFO  Starting module admin_web
2016-11-27 22:13:22.984 INFO  Starting module persistence
2016-11-27 22:13:37.863 INFO  Starting module fhir_endpoint
2016-11-27 22:13:38.854 INFO  Starting module admin_json
2016-11-27 22:13:40.591 INFO  CDR has fully started in 34192ms

Assuming you see the phrase CDR has fully started, you have now started the software.