8.x

Installing Snow Owl with Docker

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 vm.max_map_count kernel setting needs to be set to at least 262144 permanently in /etc/sysctl.conf for production use. To apply the setting on a live system type: sysctl -w vm.max_map_count=262144

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

docker-compose is not pre-installed with Docker on Linux. Instructions for installing it can be found on the Docker Compose webpage.

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

The container runs Snow Owl as user snowowl using uid:gid 1000:1000. Bind mounted host directories and files, such as custom_snowowl.yml above, need to be accessible by this user. For the mounted data and log dirs, such as /usr/share/snowowl/resources, write access is required as well.

  • 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 <<path-settings,data and log dirs>> 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.

Last updated