2 min read

Setting up a SNOMED CT Terminology Server using Hermes

How to run a SNOMED CT microservice using Hermes - written in Clojure.
Setting up a SNOMED CT Terminology Server using Hermes
Credits: All of the heavy lifting is done by Hermes, an open-source Clojure library for exploring SNOMED CT terminologies. Big shout out to Mark Wardle for the great work! You can check out his blog on clinical informatics here. Lot’s of cool stuff!


  1. Get the SNOMED CT files from your National Release Center or MLDS
  2. Download and install docker and docker-compose. (Or you can use Java with the jar, but I strongly recommend docker.)


First, Clone my fork of Hermes into a folder called hermes. Technically, you only need the Caddyfile, docker-compose.yml, and index.sh.

Now, extract the SNOMED CT release files into a folder called snomed inside the hermes directory.

Your hermes directory should look something like this:

├── snomed
│   ├── SnomedCT_IndiaDrugExtensionRF2_PRODUCTION_IN1000189_20200828T120000Z
│   │   ├── Delta
│   │   ├── Full
│   │   ├── Readme_en_20200828.txt
│   │   └── Snapshot
│   └── SnomedCT_InternationalRF2_PRODUCTION_20200731T120000Z
│       ├── Delta
│       ├── Full
│       ├── Readme_en_20200731.txt
│       ├── Snapshot
│       └── release_package_information.json
├── Caddyfile
├── Dockerfile
├── README.md
├── deps.edn
├── docker-compose.yml
├── index.sh
├── resources
├── src
└── test

Index your SNOMED CT files. This step requires a lot of compute and will take some time (20 mins - 1 hour). Make sure your system has enough memory.

chmod +x ./index.sh

For some reason, if you’re unable to use the script, execute these commands in order:

docker-compose run hermes java -jar target/hermes-full-v0.1.0.jar -d /db/snomed.db import /db/snomed
docker-compose run hermes java -jar target/hermes-full-v0.1.0.jar -d /db/snomed.db index
docker-compose run hermes java -jar target/hermes-full-v0.1.0.jar -d /db/snomed.db compact

The indexed files are now in the snomed.db folder. The good news is, you can just send this folder to another system and the next command will still work. The reason I had to write all the above instructions is due to the SNOMED Licensing policy. Once you have your snomed.db, you can send it (compress before sending) to another server or even include it in a docker container for setting up things in the cloud faster.

Start the server with docker-compose up.

You should now have a terminology server running at http://localhost:8080.

Let’s test the server by searching. You can change the s (search term), constraint (ECL constraint) and maxHits values.

curl "http://localhost:8080/v1/snomed/search?s=Head&constraint=<64572001&maxHits=3" -H "Accept: application/json"

You should get a JSON response like:

        "id": 140467011,
        "conceptId": 84727000,
        "term": "Big head",
        "preferredTerm": "Osteitis fibrosa cystica"
        "id": 200997013,
        "conceptId": 82272006,
        "term": "Head cold",
        "preferredTerm": "Common cold"
        "id": 504583010,
        "conceptId": 81000006,
        "term": "Head lice",
        "preferredTerm": "Pediculosis capitis"

Sign up for the YouTube channel and newsletter for more. If you require more assistance, take a look at our consulting services.