Preparing a Linux Host - Smile CDR Documentation

Preparing a new Linux Host

If you are preparing a new Linux server that will be used to host Smile CDR, this page shows the steps you should follow to set it up. This page also lists recipes for a few common scenarios.

Ubuntu Host with PostgreSQL / NGINX / Letsencrypt

The following recipe is appropriate for a cloud hosted Ubuntu Linux host, such as an Amazon EC2 instance using the Ubuntu image.

This recipe uses PostreSQL as an RDBMS and NGINX as a reverse proxy to serve HTTPS secured endpoints via Letsencrypt.

Install OpenJDK 21 (recommended) or OpenJDK 17

$ sudo apt update
$ sudo apt install openjdk-21-jdk

Copy

Log out and log back in to apply the default Java
Verify that you now have a supported OpenJDK version (21 or 17) by default.

$ java -version

openjdk version "21.0.1" 2023-10-17
OpenJDK Runtime Environment (build 21.0.1+12-Ubuntu-222.04)
OpenJDK 64-Bit Server VM (build 21.0.1+12-Ubuntu-222.04, mixed mode, sharing)

Copy

Install PostgreSQL.

$ sudo apt install postgresql

Copy

Start the PostgreSQL command line client.

$ sudo -i -u postgres
postgres-$ psql

Copy

Create a CDR database user with a CDR database. Note that in this example we're creating a single database called cdr, which is accessible by a user, also called cdr. In a high-volume deployment, you might want to use several separate databases – but this is the simple case.

postgres=# CREATE ROLE cdr LOGIN password '[SOME PASSWORD]';
> CREATE ROLE
postgres=# CREATE DATABASE cdr ENCODING 'UTF8' OWNER cdr;
> CREATE DATABASE
postgres=# GRANT ALL PRIVILEGES ON DATABASE cdr TO cdr;
> GRANT

Copy

Hit (ctrl-d) to exit the PostgreSQL command line client then exit to return to your shell.

Install letsencrypt and obtain Certs (optional)

If you want to use TLS/SSL encryption, letsencrypt can be a simple way of setting that up.

Install letsencrypt.

$ sudo add-apt-repository ppa:certbot/certbot
$ sudo apt-get update
$ sudo apt-get install python-certbot-nginx

Copy

Ask letsencrypt to generate a key and certificate for your server.

$ sudo certbot --nginx certonly

Copy

Request a certificate from Letsencrypt.

Saving debug log to /var/log/letsencrypt/letsencrypt.log

Plugins selected: Authenticator nginx, Installer nginx

Enter email address (used for urgent renewal and security notices) (Enter 'c' to cancel): (your email address)

Please read the Terms of Service

(A)gree/(C)ancel: A

Would you be willing to share your email address with the Electronic Frontier Foundation, a founding partner of the Let's Encrypt project and the non-profit organization that develops Certbot? We'd like to send you email about our work encrypting the web, EFF news, campaigns, and ways to support digital freedom.

(Y)es/(N)o: (Y/N)

No names were found in your configuration files. Please enter in your domain name(s) (comma and/or space separated) (Enter 'c' to cancel): somehost.smiledigitalhealth.com

Install nginx And Configure it to Front the Server

Install the nginx server as a reverse proxy to your Smile CDR installation, providing TLS encryption.

Install nginx.

$ sudo apt install nginx

Copy

Generage a Diffie-Hellman group.

$ sudo mkdir -p /etc/nginx/ssl/
$ sudo openssl dhparam -out /etc/nginx/ssl/dhparams.pem 2048

Copy

Create common settings for reverse proxy ports.

$ sudo vi /etc/nginx/proxy.conf

Copy

Place the following contents in proxy.conf (replace [hostname] with your actual host name):

server_name [hostname];

ssl_certificate /etc/letsencrypt/live/[hostname]/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/[hostname]/privkey.pem;

ssl_stapling on;
ssl_stapling_verify on;

ssl_dhparam /etc/nginx/ssl/dhparams.pem;
ssl_ciphers 'kEECDH+ECDSA+AES128 kEECDH+ECDSA+AES256 kEECDH+AES128 kEECDH+AES256 kEDH+AES128 kEDH+AES256 DES-CBC3-SHA +SHA !aNULL !eNULL !LOW !kECDH !DSS !MD5 !EXP !PSK !SRP !CAMELLIA !SEED !3DES';

access_log  /var/log/nginx/access.log;

Copy

Create a site file for nginx to reverse proxy the various Smile CDR ports (replace [hostname] with your actual host name).

$ sudo vi /etc/nginx/sites-enabled/[hostname]

Copy

Place the contents below in the new file. Note that the sample below makes a few assumptions:
- That Smile CDR is deployed on the same host as NGINX.
- That Smile CDR has been configured with port numbers prefixed with 1, for example, 18000 for the fhir_endpoint module and 19100 for the admin_web module. This is done to distinguish the ports that NGINX will be listening on from the ports that Smile CDR will be using.
- That NGINX will implement https protocol and redirect to endpoints in Smile CDR that are using http protocol (i.e. TLS has not been enabled on any of the endpoints in Smile CDR).

#######################################
# Redirect http to https
#######################################
server {
    listen 80;
     include proxy.conf;
    return 301 https://$host$request_uri;
}

#######################################
# FHIR Endpoint
#######################################
server {
    listen 8000 ssl default_server;
    include proxy.conf;
    location / {
        proxy_set_header    Host                        $host;
        proxy_set_header    X-Real-IP                   $remote_addr;
        proxy_set_header    X-Forwarded-For             $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Host   $host:8000;
        proxy_set_header    X-Forwarded-Server $host;
        proxy_set_header    X-Forwarded-Port   8000;
        proxy_set_header    X-Forwarded-Proto  https;
        proxy_pass          http://localhost:18000/;
    }
}

#######################################
# FHIRWeb Console
#######################################
server {
    listen 8001 ssl default_server;
    include proxy.conf;
    location / {
        proxy_set_header    Host                        $host;
        proxy_set_header    X-Real-IP                   $remote_addr;
        proxy_set_header    X-Forwarded-For             $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Host   $host:8001;
        proxy_set_header    X-Forwarded-Server $host;
        proxy_set_header    X-Forwarded-Port   8001;
        proxy_set_header    X-Forwarded-Proto  https;
        proxy_pass          http://localhost:18001/;
    }
}

#######################################
# Web Admin Console
#######################################
server {
    listen 443 ssl default_server;
    include proxy.conf;
    location / {
        proxy_set_header    Host                        $host;
        proxy_set_header    X-Real-IP                   $remote_addr;
        proxy_set_header    X-Forwarded-For             $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Host   $host:443;
        proxy_set_header    X-Forwarded-Server $host;
        proxy_set_header    X-Forwarded-Port   443;
        proxy_set_header    X-Forwarded-Proto  https;
        proxy_pass          http://localhost:19100/;
    }
}
server {
    listen 9100 ssl default_server;
    include proxy.conf;
    location / {
        proxy_set_header    Host                        $host;
        proxy_set_header    X-Real-IP                   $remote_addr;
        proxy_set_header    X-Forwarded-For             $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Host   $host:9100;
        proxy_set_header    X-Forwarded-Server $host;
        proxy_set_header    X-Forwarded-Port   9100;
        proxy_set_header    X-Forwarded-Proto  https;
        proxy_pass          http://localhost:19100/;
    }
}

#######################################
# JSON Admin API
#######################################
server {
    listen 9000 ssl default_server;
    include proxy.conf;
    location / {
        proxy_set_header    Host                        $host;
        proxy_set_header    X-Real-IP                   $remote_addr;
        proxy_set_header    X-Forwarded-For             $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Host   $host:9000;
        proxy_set_header    X-Forwarded-Server $host;
        proxy_set_header    X-Forwarded-Port   9000;
        proxy_set_header    X-Forwarded-Proto  https;
        proxy_pass          http://localhost:19000/;
    }
}

#######################################
# SMART OAuth2 / OpenID Connect Server
#######################################
server {
    listen 9200 ssl default_server;
    include proxy.conf;
    location / {
        proxy_set_header    Host                        $host;
        proxy_set_header    X-Real-IP                   $remote_addr;
        proxy_set_header    X-Forwarded-For             $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Host   $host:9200;
        proxy_set_header    X-Forwarded-Server $host;
        proxy_set_header    X-Forwarded-Port   9200;
        proxy_set_header    X-Forwarded-Proto  https;
        proxy_pass          http://localhost:19200/;
    }
}

#######################################
# Package Registry
#######################################
server {
    listen 8002 ssl default_server;
    include proxy.conf;
    location / {
        proxy_set_header    Host                        $host;
        proxy_set_header    X-Real-IP                   $remote_addr;
        proxy_set_header    X-Forwarded-For             $proxy_add_x_forwarded_for;
        proxy_set_header    X-Forwarded-Host   $host:8002;
        proxy_set_header    X-Forwarded-Server $host;
        proxy_set_header    X-Forwarded-Port   8002;
        proxy_set_header    X-Forwarded-Proto  https;
        proxy_pass          http://localhost:18002/;
    }
}

Copy

Note that Respect Forward Headers should be enabled in the module config for any modules which are being proxied by nginx in order to ensure that Smile CDR is aware of the correct source IP for incoming requests.

Set up letsencrypt to auto-renew.

$ sudo touch /etc/cron.daily/renew-letsencrypt
$ sudo chmod u+x /etc/cron.daily/renew-letsencrypt
$ sudo vi /etc/cron.daily/renew-letsencrypt

Copy

Place the following contents in this file:

#!/bin/sh

certbot renew
/etc/init.d/nginx stop
/etc/init.d/nginx start

Copy

Test that the script works.

letsencrypt won't actually update your cert since it was only just created but this verifies that the script at least runs the updater.

sudo /etc/cron.daily/renew-letsencrypt
Processing /etc/letsencrypt/renewal/FOO.conf

The following certs are not due for renewal yet:
  /etc/letsencrypt/live/FOO/fullchain.pem (skipped)
No renewals were attempted.

Copy

Create a Smile CDR User

Create a user named smile with a home directory at /opt/smile (these are simply suggestions, Smile CDR does not need to run in this location or with this user).

sudo useradd -m -b /opt/ smile

Copy

Install Smile CDR

You may now want to proceed to this page for instructions on how to actually install Smile CDR.

Red Hat Enterprise Linux (RHEL) or CentOS

The following recipe demonstrates how to prepare a Red Hat server for Smile CDR installation.

Install OpenJDK

Install a supported version of OpenJDK (21 or 17). See platform requirements for information on supported versions of Java.

For example, to install OpenJDK 21 on RHEL 9:

sudo dnf install java-21-openjdk-devel

Copy

Create a Smile CDR User

sudo useradd -m -b /opt/ smile

Copy

Install Smile CDR

Platform Requirements

Preparing a Linux Host

Installing

Platform Requirements Preparing a Linux Host Installing Smile CDR, NGINX and PostgreSQL in a Docker Stack Deploying a Kubernetes Managed Cluster Docker Container Installation Configuring Smile CDR Unix Service Installation Tuning your Installation Designing a Cluster Message Brokers Message Broker Failure Management Message Broker: Kafka Message Broker: ActiveMQ Message Broker: Pulsar Pre-Seeding Configuration and Data Production Checklist Module Licensing

Installing Smile CDR, NGINX and PostgreSQL in a Docker Stack