README
Introduction
Snow Owl® is a terminology server and a collaborative terminology authoring platform. The authoring platform maintains terminology artifacts developed by a team and supported by business workflows that are driven by external task management systems like Bugzilla and JIRA. With its modular design, the server can maintain multiple terminologies where new terminologies can be plugged-in to the platform. The functionality of Snow Owl is exposed via a REST API.
Getting Started
These instructions will get Snow Owl up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy Snow Owl on a live system.
Prerequisites
From version 5.1.0, Snow Owl requires Java 8 update 102 or later.
Snow Owl is an Equinox-OSGi based server (using either Virgo or standalone OSGi). To develop plug-ins for Snow Owl you need to use Eclipse as IDE:
Use latest Eclipse IDE for Eclipse Committers package: http://www.eclipse.org/downloads/eclipse-packages/
Required Eclipse plug-ins (install the listed features):
Note: you may have to untick the Show only the latest versions of the available software
checkbox to get older versions of a feature. Please use the exact version specified below, not the latest point release.
Xtext/Xtend (http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/)
MWE 2 language SDK 2.9.0 (MWE)
Xtend IDE 2.11.0 (Xtext)
Xtext Complete SDK 2.11.0 (Xtext)
Optional: Maven integration (http://download.eclipse.org/technology/m2e/releases)
Eclipse Preferences
Make sure you have the following preferences enabled/disabled.
Plug-in development API baseline errors is set to Ignored (Preferences > Plug-in Development > API Baselines)
The Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-clean-plugin:2.5:clean type of errors can be ignored or changed to Warnings in Preferences->Maven->Errors/Warnings.
Set the workspace encoding to UTF-8 (Preferences->General->Workspace)
Set the line endings to Unix style (Preferences->General->Workspace)
Git configuration
Make sure the Git line endings are set to input (Preferences->Team->Git->Configuration - add key if missing core.autocrlf = input)
Target platform
Create a prefetched target platform and copy the contents of the
target_platform_<version>
directory under<eclipse_home>/target_platform
.(Re)Open Eclipse and find the
com.b2international.snowowl.server.target.update
projectOpen the file:
com.b2international.snowowl.server.local.target
Click on
Set as Target platform
Run from development environment
Find
com.b2international.snowowl.server.update
projectOpen
so_server.product
file, click onLaunch an Eclipse application
and terminate itOpen Run Configurations and find the launch config
so_server.product
Open Arguments tab
Add
-Djetty.home.bundle=org.eclipse.jetty.osgi.boot
to the end of VM arguments
Open Plug-ins tab
Add
org.eclipse.jetty.osgi.boot
bundle (set Auto-Start totrue
, and Start Level to5
)Click on Add required bundles
Remove
org.eclipse.equinox.http.jetty
,org.eclipse.jetty.annotations
, all*jsp*
and*jasper*
bundlesSet the API bundles to start automatically (
com.b2international.snowowl.api.rest
,com.b2international.snowowl.snomed.api.rest
) by setting Auto-Start totrue
, and Start Level to5
.Add the
com.sun.el
bundle and remove theorg.apache.el
bundle if necessary
Run and point your browser to
http://localhost:8080/snowowl/snomed-ct/v2/
By default Snow Owl will use an empty embedded
H2
database. To useMySQL
, you have to configure the database in thesnowowl_config.yml
configuration file (or copy an existingMySQL
orH2
configuration file located in thereleng/com.b2international.snowowl.server.update/assembly/mysql or h2
directory to<eclipse_home>/target_platform
).
Build
Snow Owl uses Maven for its build system.
In order to create a distribution, simply run the mvn clean package -Pdependencies -Psite -Pdist
command in the cloned directory.
To run the test cases, simply run:
The distribution package can be found in the releng/distribution/target
folder, when the build completes.
Additional Build Improvements
Here are few tips to improve the quality of the default build process.
Nexus
We highly recommend to install a local artifact repository (Nexus OSS
is supported), so the build can deploy and reuse (in downstream projects) Maven
and p2
artifacts.
Download and install Nexus OSS or Professional (http://www.sonatype.org/nexus/go/).
Install
Nexus Unzip Plugin
to easily reference p2 repositories deployed as zip: https://wiki.eclipse.org/Tycho/Nexus_Unzip_PluginDefine the
nexus.url
parameter in thesettings.xml
file under.m2
folder on your build server (use thesettings.xml
in the root of this repository as template).Define a deployment user in Nexus, and reference it in the
.m2/settings.xml
file.Use
mvn clean deploy
instead ofmvn clean verify
when you execute the process.Optional: deploy only if build succeeds (requires a
Jenkins CI
job with post build step to deploy artifacts toNexus
Prefetched target platform
The -Pdependencies
profile includes all required third party repositories and modules as part of the build process using Tycho's p2 and Maven dependency resolution capabilities. While this should be enough to run the process, in production builds we recommend using a prefetched target platform, as it will ensure consistent third party versions and reduces the execution time significantly.
Create the target platform update site, run
mvn clean verify -Pdependencies -Ptarget_site
from the releng folderNavigate to
com.b2international.snowowl.server.target.update/target
folderCopy the
target_platform_<version>
folder to a webserver, or useNexus
to serve the site as unzipped p2 (requires Nexus OSS with Unzip Plugin installed, see previous section)Define an
http
URL astarget.platform.url
parameter in the global Maven.m2/settings.xml
fileRun Snow Owl maven process with
mvn clean verify -Ptp_dependencies -Psite -Pdist
(NOTE: the tp_dependencies profile will use the prefetched local p2 repository instead of querying all remote sites)
Deployment
Please refer to the installation guide. Prerequisites are detailed in the software requirements document. Then see the configuration guide to configure for your particular installation.
The SNOMED CT extension management guide provides details for managing multiple SNOMED extensions on a single terminology server.
Administration
See the administration guide. You may find the quick references for console commands and the administration REST API helpful.
Contributing
Please see CONTRIBUTING.md for details.
Versioning
Our releases use semantic versioning. You can find a chronologically ordered list of notable changes in CHANGELOG.md.
License
This project is licensed under the Apache 2.0 License. See LICENSE for details and refer to NOTICE for additional licencing notes and uses of third-party components.
Acknowledgements
In March 2015, SNOMED International generously licensed the Snow Owl Terminology Server components supporting SNOMED CT. They subsequently made the licensed code available to their members and the global community under an open-source license.
Last updated