Snow Owl is provided in the following package formats:
Package
Description
zip/tar.gz
The zip
and tar.gz
packages are suitable for installation on any system and are the easiest choice for getting started with Snow Owl on most systems.
Install Snow Owl with tar.gz
or zip
rpm
The rpm
package is suitable for installation on Red Hat, Centos, SLES, OpenSuSE and other RPM-based systems. RPMs may be downloaded from the Downloads section.
Install Snow Owl with RPM
deb
The deb
package is suitable for Debian, Ubuntu, and other Debian-based systems. Debian packages may be downloaded from the Downloads section.
Install Snow Owl with Debian Package
docker
Images are available for running Snow Owl as Docker containers. They may be downloaded from the official Docker Hub Registry. Install 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.
Obtaining Snow Owl for Docker is as simple as issuing a docker pull
command against the Docker Hub registry.
Snow Owl can be quickly started for development or testing use with the following command:
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
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`.
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:
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:
You could then build and try the image with something like:
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:
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
:
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 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.
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.
Snow Owl requires Java 11 or newer version. Use the official Oracle distribution or an open-source distribution such as OpenJDK.
zip
packageThe .zip
archive for Snow Owl can be downloaded and installed as follows:
.tar.gz
packageThe .tar.gz
archive for Snow Owl can be downloaded and installed as follows:
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.
All scripts packaged with Snow Owl assume that Bash is available at /bin/bash. As such, Bash should be available at this path either directly or via a symbolic link.
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:
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:
.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.
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.
RPM install is not supported on distributions with old versions of RPM, such as SLES 11 and CentOS 5. Please see Install Snow Owl with .zip or .tar.gz instead.
On systemd-based distributions, the installation scripts will attempt to set kernel parameters (e.g., vm.max_map_count
); you can skip this by masking the systemd-sysctl.service unit.
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/
.
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/
.
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:
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.
The RPM places config files, logs, and the data directory in the appropriate locations for an RPM-based system:
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 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.
Use the update-rc.d 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/
.
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/
.
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:
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.
NOTE: Distributions that use systemd
require that system resource limits be configured via systemd
rather than via the /etc/sysconfig/snowowl
file.
The Debian package places config files, logs, and the data directory in the appropriate locations for a Debian-based system:
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 loads its configuration from the /etc/snowowl/snowowl.yml
file by default. The format of this config file is explained in .
Learn how to .
Configure .
Configure .
Type
Description
Default Location
Setting
home
Snow Owl home directory or $SO_HOME
Directory created by unpacking the archive
bin
Binary scripts including startup/shutdown to start/stop the instance
$SO_HOME/bin
conf
Configuration files including snowowl.yml
$SO_HOME/configuration
data
The location of the data files and resources.
$SO_HOME/resources
path.data
logs
Log files location.
$SO_HOME/serviceability/logs
Type
Description
Default Location
Setting
home
Snow Owl home directory or $SO_HOME
/usr/share/snowowl
bin
Binary scripts including startup/shutdown to start/stop the instance
/usr/share/snowowl/bin
conf
Configuration files including snowowl.yml
/etc/snowowl
data
The location of the data files and resources.
/var/lib/snowowl
path.data
logs
Log files location.
/var/log/snowowl
Type | Description | Default Location | Setting |
home | Snow Owl home directory or |
|
bin | Binary scripts including startup/shutdown to start/stop the instance |
|
conf | Configuration files including |
|
data | The location of the data files and resources. | /var/lib/snowowl | path.data |
logs | Log files location. | /var/log/snowowl |