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:

Download and install the .tar.gz package

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

Running Snow Owl from the command line

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

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:

which should give you a response like this:

Running in the background

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

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

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

or using the provided shutdown script:

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 .

• Configure .

Snow Owl is provided in the following package formats:

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.

Running Snow Owl from the command line

Development mode

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

Production mode

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

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 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:

• 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:

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

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:

• It is important to ensure increased ulimits for nofile and nproc are available for the Snow Owl containers. Verify the 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:

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

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

• The image 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

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

Running Snow Owl with SysV init

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.