Snow Owl is also available as Docker images. The images use centos:7 as the base image.

A list of all published Docker images and tags is available at Docker Hub.

These images are free to use under the Apache 2.0 license. They contain open source features only.

Pulling the image

Obtaining Snow Owl for Docker is as simple as issuing a docker pull command against the Docker Hub registry.

docker pull snow-owl-oss:latest

Running Snow Owl from the command line

Development mode

Snow Owl can be quickly started for development or testing use with the following command:

docker run -p 8080:8080 snow-owl-oss:latest

Production mode

The following example brings up Snow Owl instance with its dedicated Elasticsearch node. To bring up the cluster, use the docker-compose.yml and just type:

docker-compose up

The node snowowl listens on localhost:8080 while it talks to the elasticsearch node over a Docker network.

To stop the cluster, type docker-compose down. Data volumes/mounts will persist, so it's possible to start the stack again with the same data using docker-compose up`.

Configuring Snow Owl with Docker

Snow Owl loads its configuration from files under /usr/share/snowowl/config/. These configuration files are documented in the Configure Snow Owl pages.

The image offers several methods for configuring Snow Owl settings with the conventional approach being to provide customized files, that is to say, snowowl.yml. It's also possible to use environment variables to set options:

• A. Bind-mounted configuration

  Create your custom config file and mount this over the image's corresponding file.

  For example, bind-mounting a custom_snowowl.yml with docker run can be

  accomplished with the parameter:

-v full_path_to/custom_snowowl.yml:/usr/share/snowowl/configuration/snowowl.yml

• B. Customized image

  In some environments, it may make more sense to prepare a custom image containing

  your configuration. A Dockerfile to achieve this may be as simple as:

FROM snow-owl-oss:{version}
COPY --chown=snowowl:snowowl snowowl.yml /usr/share/snowowl/configuration/

You could then build and try the image with something like:

docker build --tag=snow-owl-oss-custom .
docker run -ti -v /usr/share/snowowl/resources snow-owl-oss-custom

Notes for production use and defaults

We have collected a number of best practices for production use. Any Docker parameters mentioned below assume the use of docker run.

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

  this user, while the <> additionally require

  write access. A good strategy is to grant group access to gid 1000 or 0 for

  the local directory. As an example, to prepare a local directory for storing

  data through a bind-mount:

  mkdir sodatadir
  chmod g+rwx sodatadir
  chgrp 1000 sodatadir

• It is important to ensure increased ulimits for nofile

  and nproc are available for the Snow Owl containers.

  Verify the init system

  for the Docker daemon is already setting those to acceptable values and, if

  needed, adjust them in the Daemon, or override them per container, for example

  using docker run:

  --ulimit nofile=65535:65535

NOTE: One way of checking the Docker daemon defaults for the aforementioned ulimits is by running:

  docker run --rm centos:7 /bin/bash -c 'ulimit -Hn && ulimit -Sn && ulimit -Hu && ulimit -Su'

• Swapping needs to be disabled for performance and stability. This can be achieved through any of the methods mentioned in the system settings.

• The image exposes TCP ports 8080 and 2036.

• Use the SO_JAVA_OPTS environment variable to set heap size. For example, to use 16GB use SO_JAVA_OPTS="-Xms16g -Xmx16g" with docker run.

• Pin your deployments to a specific version of the Snow Owl OSS Docker image. For example, snow-owl-oss:7.2.0.

• Consider centralizing your logs by using a different https://docs.docker.com/engine/admin/logging/overview/[logging driver]. Also note that the default json-file logging driver is not ideally suited for production use.

The Debian package for Snow Owl can be downloaded from the Downloads section. It can be used to install Snow Owl on any Debian-based system such as Debian and Ubuntu.

Download and install

wget https://github.com/b2ihealthcare/snow-owl/releases/download/<version>/snow-owl-oss-<version>.deb
wget https://github.com/b2ihealthcare/snow-owl/releases/download/<version>/snow-owl-oss-<version>.deb.sha512
shasum -a 512 -c snow-owl-oss-<version>.deb.sha512 # Compares the SHA of the downloaded Debian package and the published checksum, which should output `snow-owl-oss-<version>.deb: OK`.
sudo dpkg -i snow-owl-oss-<version>.deb

Running Snow Owl with SysV init

Use the update-rc.d command to configure Snow Owl to start automatically when the system boots up:

sudo update-rc.d snowowl defaults 95 10

Snow Owl can be started and stopped using the service command:

sudo -i service snowowl start
sudo -i service snowowl stop

If Snow Owl fails to start for any reason, it will print the reason for failure to STDOUT. Log files can be found in /var/log/snowowl/.

Running Snow Owl with systemd

To configure Snow Owl to start automatically when the system boots up, run the following commands:

sudo /bin/systemctl daemon-reload
sudo /bin/systemctl enable snowowl.service

Snow Owl can be started and stopped as follows:

sudo systemctl start snowowl.service
sudo systemctl stop snowowl.service

These commands provide no feedback as to whether Snow Owl was started successfully or not. Instead, this information will be written in the log files located in /var/log/snowowl/.

Checking that Snow Owl is running

You can test that your Snow Owl instance is running by sending an HTTP request to:

curl http://localhost:8080/snowowl/admin/info

which should give you a response something like this:

{
  "version": "7.2.0",
  "description": "You Know, for Terminologies",
  "repositories": {
    "items": [
      {
        "id": "snomedStore",
        "health": "GREEN"
      }
    ]
  }
}

Configuring Snow Owl

Snow Owl defaults to using /etc/snowowl for runtime configuration. The ownership of this directory and all files in this directory are set to root:snowowl on package installation and the directory has the setgid flag set so that any files and subdirectories created under /etc/snowowl are created with this ownership as well (e.g., if a keystore is created using the keystore tool). It is expected that this be maintained so that the Snow Owl process can read the files under this directory via the group permissions.

Snow Owl loads its configuration from the /etc/snowowl/snowowl.yml file by default. The format of this config file is explained in Configuring Snow Owl.

Directory layout of Debian package

The Debian package places config files, logs, and the data directory in the appropriate locations for a Debian-based system:

Next steps

You now have a test Snow Owl environment set up. Before you start serious development or go into production with Snow Owl, you must do some additional setup:

• Learn how to configure Snow Owl.

• Configure important Snow Owl settings.

• Configure important system settings.

Snow Owl is provided as a .zip and as a .tar.gz package. These packages can be used to install Snow Owl on any system and are the easiest package format to use when trying out Snow Owl.

The latest stable version of Snow Owl can be found on the Snow Owl Releases page.

Download and install the zip package

The .zip archive for Snow Owl can be downloaded and installed as follows:

wget https://github.com/b2ihealthcare/snow-owl/releases/download/<version>/snow-owl-oss-<version>.zip
wget https://github.com/b2ihealthcare/snow-owl/releases/download/<version>/snow-owl-oss-<version>.zip.sha512
shasum -a 512 -c snowowl-oss-<version>.zip.sha512 # compares the SHA of the downloaded archive, should output: `snowowl-oss-<version>.zip: OK.`
unzip snowowl-oss-<version>.zip
cd snowowl-oss-<version>/ # This directory is known as `$SO_HOME`

Download and install the .tar.gz package

The .tar.gz archive for Snow Owl can be downloaded and installed as follows:

wget https://github.com/b2ihealthcare/snow-owl/releases/download/<version>/snow-owl-oss-<version>.tar.gz
wget https://github.com/b2ihealthcare/snow-owl/releases/download/<version>/snow-owl-oss-<version>.tar.gz.sha512
shasum -a 512 -c snowowl-oss-<version>.tar.gz.sha512 # compares the SHA of the downloaded archive, should output: `snowowl-oss-<version>.tar.gz: OK.` 
tar -xzf snowowl-oss-<version>.tar.gz
cd snowowl-oss-<version>/ # This directory is known as `$SO_HOME`

Running Snow Owl from the command line

Snow Owl can be started from the command line as follows:

./bin/startup

By default, Snow Owl runs in the foreground, prints its logs to the standard output (stdout), and can be stopped by pressing Ctrl-C.

Checking that Snow Owl is running

You can test that your instance is running by sending an HTTP request to Snow Owl's status endpoint:

curl http://localhost:8080/snowowl/admin/info

which should give you a response like this:

{
  "version": "7.0.0",
  "description": "You Know, for Terminologies",
  "repositories": {
    "items": [
      {
        "id": "snomedStore",
        "health": "GREEN"
      }
    ]
  }
}

Running in the background

You can send the Snow Owl process to the background using the combination of nohup and the & character:

nohup ./bin/startup > /dev/null &

Log messages can be found in the $SO_HOME/serviceability/logs/ directory.

To shut down Snow Owl, you can kill the process ID directly:

kill <pid>

or using the provided shutdown script:

./bin/shutdown

Directory layout of .zip and .tar.gz archives:

The .zip and .tar.gz packages are entirely self-contained. All files and directories are, by default, contained within $SO_HOME — the directory created when unpacking the archive.

This is very convenient because you don’t have to create any directories to start using Snow Owl, and uninstalling Snow Owl is as easy as removing the $SO_HOME directory. However, it is advisable to change the default locations of the config directory, the data directory, and the logs directory so that you do not delete important data later on.

Next steps

You now have a test Snow Owl environment set up. Before you start serious development or go into production with Snow Owl, you must do some additional setup:

• Learn how to configure Snow Owl.

• Configure important Snow Owl settings.

• Configure important system settings.

The RPM for Snow Owl can be downloaded from the Downloads section. It can be used to install Snow Owl on any RPM-based system such as OpenSuSE, SLES, Centos, Red Hat, and Oracle Enterprise.

Download and install

Running Snow Owl with SysV init

Use the chkconfig command to configure Snow Owl to start automatically when the system boots up:

Snow Owl can be started and stopped using the service command:

If Snow Owl fails to start for any reason, it will print the reason for failure to STDOUT. Log files can be found in /var/log/snowowl/.

Running Snow Owl with systemd

To configure Snow Owl to start automatically when the system boots up, run the following commands:

Snow Owl can be started and stopped as follows:

These commands provide no feedback as to whether Snow Owl was started successfully or not. Instead, this information will be written in the log files located in /var/log/snowowl/.

Checking that Snow Owl is running

You can test that your Snow Owl instance is running by sending an HTTP request to:

which should give you a response something like this:

Configuring Snow Owl

Snow Owl defaults to using /etc/snowowl for runtime configuration. The ownership of this directory and all files in this directory are set to root:snowowl on package installation and the directory has the setgid flag set so that any files and subdirectories created under /etc/snowowl are created with this ownership as well (e.g., if a keystore is created using the keystore tool). It is expected that this be maintained so that the Snow Owl process can read the files under this directory via the group permissions.

Directory layout of RPM

The RPM places config files, logs, and the data directory in the appropriate locations for an RPM-based system:

Next steps

You now have a test Snow Owl environment set up. Before you start serious development or go into production with Snow Owl, you must do some additional setup:

Snow Owl is provided in the following package formats: