Installation Guide

Get all the information you need to set up und run sublimd.

Prerequisites

Server instance with at least 2 x 2 GHz CPU (Dual Core) and 4 GB RAM
Installation of Docker Engine with ability to run Linux containers
Password manager to create and store credentials
Certificates for SSL (Secure Sockets Layer), see below for more details about the required format

Basic Installation

Open a terminal, navigate to /usr and create a new directory /usr/sublimd
Navigate to the directory /usr/sublimd and create a new directory /usr/sublimd/sublimd-uploads and another one for the current version of sublimd /usr/sublimd/X.X.X (e.g. /usr/sublimd/5.0.0)
Navigate to the created directory /usr/sublimd/X.X.X (e.g. /usr/sublimd/5.0.0) and extract the files of ch-smart-hospital-X.X.X.zip. Afterwards, you can remove the file ch-smart-hospital-X.X.X.zip.
Open the file .env with a text editor and modify the following properties according to your preferences:

MYSQL_ROOT_PASSWORD: The password of the MySQL root user
MYSQL_USER: The name of the MySQL user (it is recommended to keep the default: user)
MYSQL_PASSWORD: The password of the MySQL user
JWT_SECRET_KEY: Secret key to sign JSON Web Tokens (JWT). These tokens are used to authenticate users in sublimd. Use a random key for this.
⚠️ Caution If this key is changed, all tokens (including tokens used by api users) become invalid and users have to log in again.
HTTP_PROXY / HTTPS_PROXY: Proxy server for outgoing HTTP requests from the sublimd application server (only necessary if sublimd needs to connect to an external server, e.g. a research database, and direct HTTP traffic is blocked)
NO_PROXY: URLs that should be excluded from using the proxy server (one or more comma-separated IP addresses or hosts)

Open the file docker-compose.yml and modify the following variables:

services
- sublimd
  - build
    - args: Set HTTP_PROXY and HTTPS_PROXY to the corresponding proxy servers for outgoing HTTP requests (leave this empty if no proxy server is required for outgoing HTTP requests)
  - environment: Set VIRTUAL_HOST to the virtual host or IP address of sublimd, e.g. sublimd.krankenhaus.ch

Build the Docker images

Run docker-compose build

Info If your system is behind an HTTP or HTTPS proxy server, a configuration in the Docker systemd service file is required to pull images from the Docker Hub: Control Docker with systemd: HTTP/HTTPS proxy daemon options
Run the Docker containers

Run docker-compose up -d
Open a browser and go to the sublimd url http://localhost/app (or http://<ip-address-of-machine>/app)
Log in with the default credentials admin : admin123
The url of the patient application (for the check-in) can be found by opening the menu and then navigating to Einstellungen → Organisation → Check-in URL

Change default password of users

Log in with the the default credentials admin : admin123
Open the menu and go to Benutzerkonto
Change the password of the admin user
Open the menu and go to Benutzerkonten
Change the passwords of all other users

Set up SSL (Secure Sockets Layer)

Copy the SSL certificate and key to a new folder /usr/sublimd/certificates. The certificate and key must have the name of the virtual host (the same as the value of VIRTUAL_HOST defined in the chapter Basic Installation), followed by .crt and .key. For example, a container with a virtual host of sublimd.krankenhaus.ch must have a sublimd.krankenhaus.ch.crt and sublimd.krankenhaus.ch.key file in the certificates directory.
⚠️ Important There must not be a passphrase in the cerficate and key file.
Build the Docker images

Run docker-compose build
Run the Docker containers

Run docker-compose up -d

Set up Active Directory

Open the file .env and modify the following properties:

ACTIVE_DIRECTORY_URL: The url of Active Directory
ACTIVE_DIRECTORY_BASE_DN: The Active Directory Base DN, e.g. ou=users,dc=xyz,dc=ch
ACTIVE_DIRECTORY_USERNAME: The name of the Active Directory service user
ACTIVE_DIRECTORY_PASSWORD: The password of the Active Directory service user
ACTIVE_DIRECTORY_USERNAME_QUERY: The query that is used to find a specific user, e.g.: (sAMAccountName={userName}) The placeholder {userName} is replaced with the actual user name that was entered in the sublimd login mask.

Build the Docker images

Run docker-compose build
Run the Docker containers

Run docker-compose up -d

Set up Multi-factor Authentication (MFA)

Make sure that UDP port 123 is open (inbound and outbound) to ensure accurate time synchronization via the Network Time Protocol (NTP).
Run the following commands to set up NTP

Debian / Ubuntu

sudo apt install ntp
sudo systemctl start ntpd
sudo systemctl enable ntpd

Red Hat / CentOS

sudo yum install ntp
sudo systemctl start ntpd
sudo systemctl enable ntpd

Check the status

sudo systemctl status ntpd

Run with multiple instances (replicas)

This step is needed to make use of multiple CPU cores and increase performance.

Open the file docker-compose.yml and make the following changes:

Create a copy of the service sublimd with the name sublimd-replica and remove any volumes that are not needed
In the service sublimd-replica set the environment variable IS_REPLICA_INSTANCE=true
Consider setting the maximum pool size per instance via environment variable MYSQL_MAX_POOL_SIZE which should be a fraction of the connection limit of the database

Run docker-compose up --scale sublimd-replica=2 to start the application with two (or any other number) replicas of the sublimd container

Set up sublimd Analytics CLASSIC

If you install sublimd with docker-compose for the first time, no action is needed. If, however, you use an existing MySQL container, the sublimd MySQL user must be granted access to the database sublimd_pre_aggregations. Please execute the following command in your MySQL console:

GRANT ALL PRIVILEGES ON sublimd_pre_aggregations.* TO 'user'@'%';

Set up sublimd API

Open a browser and go to the sublimd URL http://localhost/app (or http://<ip-address-of-machine>/app)
Log in with the credentials api : api123 (or the new password if you have changed it)
Open the menu and go to Benutzerkonto
Copy the content of Request Headers - Authorization to get a valid authorization token for the sublimd API

Bearer eyJhb...

You can now send messages to the sublimd API with the following specification:

HTTP
Request URL: http://<ip-address-of-machine>/api/endpoint
Request Method: POST

Request Headers:
• "Authorization": "Bearer eyJhb..."
• "Content-Type": "application/json"

Request Body (JSON):
{
  "xyz": "12345"
}

Successful Response
HTTP Status: 200 OK

Set up HL7 ADT interface

Set up HL7 ADT interface (sublimd API)

After having set up the sublimd API (see above), you can send HL7 messages according to the following specification:

HTTP
Request URL: http://<ip-address-of-machine>/api/v1/hl7
Request Method: POST

Request Headers:
• "Authorization": "Bearer eyJhb..."
• "Content-Type": "application/json"

Request Body (JSON):
{
  "hl7Message": "MSH|^~\&|0011|SAPHL7..."
}

Successful Response
HTTP Status: 200 OK

Set up HL7 ADT interface (MLLP)

Alternatively, you can send HL7 messages via socket (MLLP):

Open the file .env with a text editor and add the following properties:

HL7_TCP_GATEWAY_PORT: The TCP port to receive HL7 messages (e.g. 2100)
HL7_TCP_GATEWAY_ORGANIZATION_ID: The id of your organization
HL7_TCP_GATEWAY_API_USER_ID: The id of your api user

Open the file docker-compose.yml
In the service sublimd, add the definition to open the TCP port to receive HL7 messages (must be the same as HL7_TCP_GATEWAY_PORT), e.g.

ports:
  - 2100:2100

Make sure the environment variable VIRTUAL_PORT is set to 8888 in the service sublimd
⚠️ Important If multiple nodes of sublimd are running (see Run with multiple nodes), you cannot expose the port 2100 as it would be exposed multiple times. In that case you have to define a separate sublimd service exposing port 2100.

Set up an Internet-facing public zone with restricted access to the sublimd API

Open the file docker-compose.yml and create a duplicate of the service nginx-proxy
Rename the duplicate service from nginx-proxy to nginx-public-proxy
In the service nginx-public-proxy, define the ports that should receive traffic from the public zone, e.g.

- 1080:80
- 10443:443

Add the following volumes to nginx-public-proxy to restrict access to the sublimd API:

./assets/files/nginx-configuration/public-zone-default-location.conf:/etc/nginx/vhost.d/default_location
./assets/files/nginx-configuration/public-zone-header.conf:/etc/nginx/conf.d/header.conf

Update NEW

Optional Login to Docker Hub

Run docker login -u sublimd <INSERT ACCESS TOKEN>
Open the file .env with a text editor and modify the following properties according to the instructions:

SUBLIMD_CONFIGURATION_VERSION: The version of the sublimd customer configuration
SUBLIMD_VERSION: The version of the sublimd application

Run the Docker containers with one of the following commands

docker-compose up -d

or

docker-compose up -d --no-deps sublimd sublimd-configuration

This only restarts the sublimd containers, resulting in a shorter downtime.

⚠️ Caution Do not use this command if the schema of Cube.js has changed.

or

docker-compose up -d --no-deps sublimd-configuration sublimd-private sublimd-public

This only restarts the sublimd containers, resulting in a shorter downtime.

⚠️ Caution Do not use this command if the schema of Cube.js has changed.

Update CLASSIC

Extract the contents of the file ch-smart-hospital-X.X.X.zip to a new directory named after the new version, e.g. /usr/sublimd/5.1.0.
Override the files .env and docker-compose.yml of the new version with the ones from the previous version. If necessary, modify the contents of these two files according to the instructions of the sublimd team.
Open a terminal and navigate to the directory with the new version.
Build the Docker images

Run docker-compose build
Run the Docker containers with one of the following commands

docker-compose up -d

or

docker-compose up -d --no-deps sublimd

This only restarts the sublimd container, resulting in a shorter downtime.

⚠️ Caution Do not use this command if the schema of Cube.js has changed.

Perform a database migration CLASSIC

Run the following command to access the bash of the MySQL container (replace sublimd-production_mysql_1 with the actual name of the MySQL container)

docker exec -it sublimd-production_mysql_1 bash -l
Run the following command with the desired MySQL query (any backticks ` inside the query must be removed)

mysql -u root -p -e "USE sublimd; <INSERT QUERY>"
Enter the MySQL root password and confirm

Resources

Docker

Tools

Portainer

Build and manage your Docker environments with ease: portainer.io

Commands

Logs

Show logs of all Docker containers from the last 24 hours

docker compose logs --since 24h

Parameters of docker compose logs

-f: Follow log output
-n: Number of lines to show from the end of the logs for each container
--no-log-prefix: Don’t print prefix in logs
--since: Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)
--until: Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)

Search logs of all Docker container from the last 24 hours for “search-term” (show 10 lines before and after the search term)

docker compose logs --since 24h | grep -a -F -i 'search-term' -B 10 -A 10

Show logs of a specific Docker container from the last 24 hours

docker logs --since 24h <CONTAINER ID> | grep -a -F -i 'search-term' -B 10 -A 10

Parameters of grep

-a: Process a binary file as if it were text
-F: Interpret pattern as fixed string, not regular expression
-i: Ignore case