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

<div data-full-width="false"><figure><img src="https://3541456109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKhQVHx0grsgAobntKXZs%2Fuploads%2FmBD8794LrB6VyjA2DmYQ%2Fsnow-owl-docker-deploy.gif?alt=media&#x26;token=be95d7bf-f013-4964-b217-fef8aa98118e" alt=""><figcaption><p>Deploy Snow Owl in less than a minute</p></figcaption></figure></div>

## 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](https://hub.docker.com/r/b2ihealthcare/snow-owl-oss).

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

* the [Docker Engine](https://docs.docker.com/engine/) (see [install guide](https://docs.docker.com/engine/install/))
* a terminal
* [git](https://git-scm.com/) (optional, see [install guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git))

### 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](https://docs.docker.com/engine/install/#supported-platforms) such as Linux, Windows, and Mac.

## Start your deployment

There is a preassembled [docker compose configuration](https://github.com/b2ihealthcare/snow-owl/tree/HEAD/docker/compose) 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](https://docs.github.com/en/repositories/working-with-files/using-files/downloading-source-code-archives)) or clone the git repository using the `git` command line tool:

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

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

```sh
cd ./snow-owl/docker/compose
```

While in this directory start the services using `docker compose`:

```sh
docker compose up -d
```

{% hint style="info" %}
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](#change-memory-settings).
{% endhint %}

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:

{% code title="docker-compose.yml" lineNumbers="true" %}

```yaml
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
```

{% endcode %}

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

```yaml
- "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.:

```yaml
- "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:

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

The expected response is

```json
{
  "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"`).