Quick Start

This guide shows you how to quickly set up a Snow Owl deployment using docker to store, search, and edit any healthcare terminology data. Start here if you are interested in evaluating its core features.

TL;DR

Here is how to deploy Snow Owl in less than a minute:

Deploy Snow Owl in less than a minute

Prerequisites

The open-source version of Snow Owl can be downloaded as a docker image. The list of all published tags and additional details about the image can be found in Snow Owl's public Docker Hub repository.

To initiate a Snow Owl deployment, the only requirements are:

• the Docker Engine (see install guide)

• a terminal

• git (optional, see install guide)

Supported architectures

Setting up a fully operational Snow Owl server depends on which architecture is supported by the Docker Engine. Thankfully it has a wide variety of platforms such as Linux, Windows, and Mac.

Start your deployment

There is a preassembled docker compose configuration in Snow Owl's GitHub repository. This set of files can be used to start up a Snow Owl terminology server and its corresponding data layer, an Elasticsearch instance.

To get ahold of the necessary files it is required to either download the repository content (see instructions here) or clone the git repository using the git command line tool:

git clone https://github.com/b2ihealthcare/snow-owl.git

Once the clone is finished find the directory containing the compose example:

cd ./snow-owl/docker/compose

While in this directory start the services using docker compose:

docker compose up -d

The example configuration will allocate 6 GB of memory for Elasticsearch and another 6 GB for Snow Owl. These settings are required if all features of Snow Owl are to be tested. To change these values see the instructions below.

The service snowowl listens on localhost:8080 while it talks to the elasticsearch service over an isolated Docker network.

To stop the application, type docker compose down. Data volumes/mounts will remain on disk, so it's possible to start the application again with the same data using docker compose up.

A default user is configured to experiment with features that would require authentication and authorization. The username is test and its password is the same.

Here is the full content of the compose file:

docker-compose.yml

services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.11.1
    container_name: elasticsearch
    environment:
      - "ES_JAVA_OPTS=-Xms6g -Xmx6g"
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65536
        hard: 65536
    volumes:
      - es-data:/usr/share/elasticsearch/data
      - ./config/elasticsearch/elasticsearch.yml:/usr/share/elasticsearch/config/elasticsearch.yml
      - ./config/elasticsearch/synonym.txt:/usr/share/elasticsearch/config/analysis/synonym.txt
    healthcheck:
      test: curl --fail http://localhost:9200/_cluster/health?wait_for_status=green || exit 1
      interval: 1s
      timeout: 1s
      retries: 60
    ports:
      - "127.0.0.1:9200:9200"
    restart: unless-stopped
  snowowl:
    image: b2ihealthcare/snow-owl-oss:latest
    container_name: snowowl
    environment:
      - "SO_JAVA_OPTS=-Xms6g -Xmx6g"
      - "ELASTICSEARCH_URL=http://elasticsearch:9200"
    depends_on:
      elasticsearch:
        condition: service_healthy
    volumes:
      - ./config/snowowl/snowowl.yml:/etc/snowowl/snowowl.yml
      - ./config/snowowl/users:/etc/snowowl/users # default username and password: test - test
      - es-data:/var/lib/snowowl/resources/indexes
    ports:
      - "8080:8080"
    restart: unless-stopped

volumes:
  es-data:
    driver: local

Change memory settings

Reducing the memory settings of the docker stack is feasible when Snow Owl is assessed with limited terminologies and basic operations such as term searches. An applicable minimum value should be no less than 2 GB for each service.

The memory settings of Elasticsearch can be changed by adapting the following line in the docker-compose.yml file to e.g.:

- "ES_JAVA_OPTS=-Xms2g -Xmx2g"

The memory settings of Snow Owl can be changed by adapting the following line in the docker-compose.yml file to e.g.:

- "SO_JAVA_OPTS=-Xms2g -Xmx2g"

Check the healthiness of the service

Snow Owl's status is exposed via a health REST API endpoint. To see if everything went well, run the following command:

curl http://localhost:8080/snowowl/info?pretty

The expected response is

{
  "version": "<version number>",
  "description": "You Know, for Terminologies",
  "repositories": {
    "items": [ {
      "id": "snomed",
      "health": "GREEN",
      "diagnosis": "",
      "indices" : [ {
        "index": "snomed-relationship",
        "status": "GREEN"
      }, {
        "index": "snomed-commit",
        "status": "GREEN"
      }, ...
    } ]
  }
}

The response contains the installed version along with a list of repositories, their overall health (eg. "snomed" with health "GREEN"), and their associated indices and status (eg. "snomed-relationship" with status "GREEN").