Terminology Server releases are shared with customers through custom download URLs. The downloaded artifact is a Linux (tar.gz) archive that contains:

• an initial folder structure

• the configuration files for all services

• a docker-compose.yml file that brings together the entire technology stack to run and manage the service

• the credentials required to pull our proprietary docker images

As a best practice, it is advised to extract the content of the archive under /opt. So the deployment folder will be /opt/snow-owl. The docker-compose setup will rely on this path, however, if required it can be changed by editing the ./snow-owl/docker/.env file later on (see DEPLOYMENT_FOLDER environment variable).

When decompressing the archive it is important to use the --same-owner and --preserve-permissions options so the docker containers can access the files and folders appropriately.

tar --extract \
    --gzip \
    --verbose \
    --same-owner \
    --preserve-permissions \
    --file=/path/to/snow-owl-linux-x86_64.tar.gz \
    --directory=/opt/

The next page will describe the content of the release package in more detail.

Having secure HTTP in case the Terminology Server is a public-facing instance is definitely a must. For such cases, we are providing a pre-configured environment and a convenience script to acquire the necessary SSL certificate.

SSL certificate retrieval and renewal are managed by certbot, the official ACME client recommended by Let's Encrypt.

To be able to obtain an SSL certificate the following requirements must be met:

• docker and docker compose are installed

• the server instance has a public IP address

• a DNS A record is configured for the desired domain name routing to the server's IP address

For the sake of example let's say the target domain name is snow-owl.b2ihealthcare.com .

Go to the sub-folder called ./snow-owl/docker/configs/cert. Make sure the init-certificate.sh script has permission to be executable and get some details about its parameters:

[root@host]# pwd
/opt/snow-owl/docker/configs/cert

[root@host]# chmod +x init-certificate.sh
[root@host]# ./init-certificate.sh -h
  DESCRIPTION:

     Get certificate for the specified domain name using Let's Encrypt and certbot

  OPTIONS:
     -h
        Show this help
     -d domain
        Define the domain name to get the certificate for
     -e email (optional)
        The email address to use for the certificate registration

  EXAMPLES:

     ./init-certificate.sh -d mywebsite.com -e example@mail.com
     ./init-certificate.sh -d example.com

As you can see -d is used for specifying the domain name, and -e is used for specifying a contact email address (optional). Now execute the script with our example parameters:

./init-certificate.sh -d snow-owl.b2ihealthcare.com -e domain@b2ihealthcare.com

After successful execution, a new folder is created ./snow-owl/cert which contains all the certificate files required by NGINX. The docker-compose.yml file is also amended with a piece of code that guarantees automatic renewal of the certificate:

  nginx:
    image: nginx:stable
    container_name: nginx
    volumes:
      - ./configs/nginx/conf.d/:/etc/nginx/conf.d/
      - ./configs/nginx/nginx.conf:/etc/nginx/nginx.conf
      - ${CERT_FOLDER}/conf:/etc/letsencrypt
      - ${CERT_FOLDER}/www:/var/www/certbot
    depends_on:
      - snowowl
    ports:
      - "80:80"
      - "443:443"
    # Reload nginx config every 6 hours and restart
    command: "/bin/sh -c 'while :; do sleep 6h & wait $${!}; nginx -s reload; done & nginx -g \"daemon off;\"'"
    restart: unless-stopped
  certbot:
    image: certbot/certbot:latest
    container_name: certbot
    volumes:
      - ${CERT_FOLDER}/conf:/etc/letsencrypt
      - ${CERT_FOLDER}/www:/var/www/certbot
    # Check for SSL cert renewal every 12 hours
    entrypoint: "/bin/sh -c 'trap exit TERM; while :; do certbot renew; sleep 12h & wait $${!}; done;'"
    restart: unless-stopped

At this point everything is prepared for having secure HTTP, let's see what else needs to be configured before spinning up the service.

Here is the list of files and folders extracted from the release package and their role are described below.

snow-owl/
├── backup
├── docker
│   ├── configs
│   │   ├── cert
│   │   │   ├── conf.d
│   │   │   ├── docker-compose-cert.yml
│   │   │   ├── docker-compose.yml
│   │   │   ├── init-certificate.sh
│   │   │   └── nginx.conf
│   │   ├── elasticsearch
│   │   │   ├── elasticsearch.yml
│   │   │   └── synonym.txt
│   │   ├── ldap-bootstrap
│   │   │   ├── 100_groups.ldif
│   │   │   └── 200_users.ldif
│   │   ├── nginx
│   │   │   ├── conf.d
│   │   │   │   └── snowowl.conf
│   │   │   └── nginx.conf
│   │   └── snowowl
│   │       ├── snowowl.yml
│   │       └── users
│   ├── docker-compose.yml
│   ├── docker_login.txt
│   └── .env
├── ldap
├── logs
└── resources
    ├── attachments 
    └── indexes

/docker

Contains every configuration file used for the docker stack, including docker-compose.yml.

In Docker, this directory serves as the context, implying that when executing commands, one needs to either explicitly reference the configuration file or run docker compose commands directly within this directory.

E.g. to verify the status of the stack there are two approaches:

Execute the command inside ./snow-owl/docker:

[root@host docker]# docker compose ps -a

Execute the command from somewhere else then ./snow-owl/docker:

[root@host ~]# docker compose --file /opt/snow-owl/docker/docker-compose.yml ps -a

/docker/configs/cert

This folder contains the files necessary to acquire an SSL certificate. None of the files should be changed here ideally.

/docker/configs/elasticsearch

There is one important file here, elasticsearch.yml which can be used for fine-tuning the Elasticsearch cluster. However, this is not necessary by default, only if an advanced configuration is required.

/docker/configs/ldap-bootstrap

This folder contains the files used upon the first start of the OpenLDAP server. The files within describe a set of groups and users to set up an initial user access model. User credentials for the test users can be found in the file called 200_users.ldif.

/docker/configs/nginx

Location of all configuration files for NGINX. By default, a non-secure HTTP configuration is assumed. If there is no need for an SSL certificate, then the files here will be used. If an SSL certificate was acquired, then the main configuration file of NGINX (nginx.conf) will be overwritten with the one under /docker/cert/nginx.conf.

/docker/configs/snowowl

snowowl.yml: this file is the default configuration file of the Terminology Server. It does not need any changes by default either.

users: list of users for file-based authentication. There is one default user called snowowl for which the credentials can be found under ./docker/.env.

/docker/docker-compose.yml

The main configuration file for the docker stack. This file is replaced in case an SSL certificate was acquired (with file /docker/cert/docker-compose.yml). This is where volumes, ports, or environment variables can be configured.

/docker/docker_login.txt

The credentials to use for authenticating with the B2i private docker registry.

/docker/.env

The collection of environment variables for the docker-compose.yml file.

This is the file to configure most of the settings of the Terminology Server. Including java heap size, Snow Owl or Elasticsearch version, passwords, or folder structure.

/ldap

The location where the OpenLDAP server stores its data.

/logs

Log files of the Terminology Server

/resources

Location of Elasticsearch and Snow Owl resources.

/resources/indexes

This directory serves as the data folder for Elasticsearch, where datasets should be extracted.

/resources/attachments

Snow Owl's local file storage. Import and export artifacts are stored here.

/cert (optional)

In case an SSL certificate is acquired, all the files used by certbot and NGINX are stored here. This folder is automatically created by the certificate retrieval script.

/backup (optional)

This is the initial folder of all backup artifacts. This should be configured as a network mount to achieve data redundancy.

To configure the Terminology Server to work with a managed Elasticsearch cluster two settings require attention.

Configure Terminology Server

First, the local Elasticsearch container and all its configurations should be removed from the docker-compose.yml file. Once that is done, we have to tell the Terminology Server where to find the cluster. This can be set in the file ./snow-owl/docker/configs/snowowl/snowowl.yml:

Configure Elastic Cloud

The Snow Owl Terminology Server leverages Elasticssearch's synonym filters. To have this feature work properly with a managed Elasticsearch cluster our custom dictionary has to be uploaded and configured. The synonym file can be found in the release package under ./snow-owl/docker/configs/elasticsearch/synonym.txt. This file needs to be compressed as an zip archive by following this structure:

For the managed Elasticsearch instance this zip file needs to be configured as a bundle extension. The steps required are covered in in great detail.

Once the bundle is configured and the cluster is up we can (re)start the docker stack. In case there are any troubles the Terminology Server will refuse to initialize and let you know what the problem is in its log files.

Full list of steps to perform before spinning up the service:

1. Extract the Terminology Server release archive to a folder. E.g. /opt/snow-owl

2. (Optional) Obtain an SSL certificate

   1. Make sure a DNS A record is routed to the host's public IP address

   2. Go into the folder ./snow-owl/docker/cert

   3. Execute the ./init-certificate.sh script:

3. (Optional) Configure access for managed Elasticsearch Cluster (elastic.co)

4. (Optional) Extract dataset to ./snow-owl/resources where folder structure should look like ./snow-owl/resources/indexes/nodes/0 at the end.

5. Verify file ownership to be UID=1000 and GID=0:

6. Check any credentials or settings that need to be changed in ./snow-owl/docker/.env

7. Authenticate with our private docker registry while in the folder ./snow-owl/docker:

8. Issue a pull (in folder ./snow-owl/docker)

9. Spin up the service (in the folder ./snow-owl/docker)

10. Verify that the REST API of the Terminology Server is available at:

    1. With SSL: https://snow-owl.example.com/snowowl

    2. Without SSL: http://hostname:8080/snowowl

11. Verify that the server and cluster status is GREEN by querying the following REST API endpoint:

    1. With SSL:

    2. Without SSL:

12. Enjoy using the Snow Owl Terminology Server

Some settings may require attention before moving to production. While the steps below may not necessitate any action, there are cases where the host running both Snow Owl and Elasticsearch will require fine-tuning.

Configure your host for Elasticsearch requirements

Some system-level settings need to be checked before deploying your own Elasticsearch in production.

Following there is an extensive guide on what to verify, but usually, it comes down to these items:

Configure your host for Snow Owl requirements

Set permissions for folders and files appropriately

By default, Snow Owl runs inside the container as user snowowl using uid:gid 1000:1000.

• If you are bind-mounting a local directory or file:

  • ensure it is readable by the user mentioned above

  • ensure that settings, data and log directories are writable as well

A good strategy is to grant group access to gid 1000 or 0 for the local directory.

Bind-mount Snow Owl's temporary working folder

In case the file system of the docker service on the host is different from what the Snow Owl deployment uses, it could be worthwhile to bind-mount Snow Owl's temporary working folder to a path that has excellent I/O performance. E.g.:

• the root file system / is backed by a block storage that purposefully has lower I/O performance, this is the file system used by the docker service.

• the deployment folder /opt/snow-owl is backed by a fast local SSD

The definition of the snowowl service in the docker compose file should be amended like this:

In certain cases, a pre-built dataset is also shipped together with the Terminology Server. This is to ease the initial setup procedure and get going fast.

These datasets are the compressed form of the Elasticsearch data folder which follows the same structure. Except for having a top folder called indexes . This is the same folder as in ./snow-owl/resources/indexes . So to be able to load the dataset one should just extract the contents of the dataset archive to this path.