Brandon Harper
Oct 24, 2023

Getting Started with Sonador

Sonador is an open source cloud platform for medical imaging visualization and research. This article shows you how to get started using the Sonador Development Environment.

What is Sonador?

Sonador is an open source cloud platform for medical imaging visualization and research. It provides a foundation for AI application development and for building systems that solve difficult clinical problems.

The platform is composed of tools to:

Sonador UI: Bone model visualization in JupyterLab
Client libraries and ready to use Docker images for JupyterLab and other Data Science tools enable the creation of analytic applications which use medical imaging data.
Sonador UI: CT Scan and DICOM-SR document
Sonador provides integration with tools such as OHIF and 3D Slicer for building workflows to support segmentation, procedure planning, and three-dimensional printing.
Sonador UI: Multi-planar reconstruction in OHIF

Container Development Environment

To enable people to get up and running quickly with Sonador, Oak-Tree maintains a container based development environment. To simplify deployment , we provide container images and a set of manifests for Docker Compose along with a reference configuration for the system. Manifests showing the configuration for a production deployment to Kubernetes are located in the same repository.

In this tutorial, we will deploy a basic Sonador environment that can be used to test-drive the platform and become familiar with its components. This will involve:

  • Installing Docker Desktop and the other dependencies in order to run Sonador.
  • Cloning the development environment repository to a local machine and using Docker Compose to create a basic deployment.
  • Using the Sonador command line tools to interface with the Sonador web application and ensure that the environment is correctly configured.
  • Clone the Sonador Examples repository and load the "Getting Started" notebook, which shows how to interface with the Sonador server and database (Orthanc image server), upload DICOM files, and fetch pixel data in a variety of formats.

This tutorial assumes that you are familiar with containers, Docker, and Docker Compose. For additional information about using Docker for software development, please refer to Docker for Software Developers or Continuous Integration with Docker (a self-paced video course available from Udemy).

Architecture and Components

Sonador is designed as a cloud native application that provides microservices for medical images, file storage, ETL, and data streaming. It uses the following open source components:

  • MinIO: a highly scalable S3 compatible storage that is used for storing the binary data for the medical images and associated files
  • PostgreSQL: a performant database that provides a cache for imaging metadata
  • Sonador Web Application: system which is used to integrate and secure medical imaging resources, also hosts the OHIF viewer instance for the platform
    • OHIF: extensible DICOM viewer written in JavaScript
  • Orthanc: light-weight and extensible PACS server which provides a REST and DICOMweb interface for medical image management.
    • S3 Storage Plugin: plugin for the Orthanc that allows for it to use MinIO or Amazon S3 for storing medical image pixel data, attachments, and other associated files
    • PostgreSQL Plugin: plugin for Orthanc that allows for it to use PostgreSQL as a metadata cache
    • Advanced Authentication Plugin: used by Orthanc to communicate with the Sonador web application and authorize access to medical imaging resources
    • Sonador Python Plugin: used for synchronizing the imaging server configuration with Sonador and integrating Orthanc with Kafka
  • Kafka: a distributed streaming platform that can be used for building reactive data processing applications
  • RabbitMQ: AMQP messaging broker and the management console
  • etcd: distributed key-value store used by cluster computing systems to manage and coordinate state, required by Kafka
  • AirFlow: open source ETL platform for data processing

System Requirements and Prerequisites

Local machine requirements:

  • Admin privileges
  • 120GB+ of available storage
  • 8GB+ RAM recommended


  • and docker-compose installed. We recommend that you use the Docker provided by your Linux distribution rather than Docker CE if you are using Linux.
  • Git


Windows 10:

Sonador Quickstart

Step 1. Clone the repository

From your BASH command line, clone the Oak-Tree Imaging Development Environment repository to your machine.

$ git clone
$ cd imaging-development-env/

Step 2. Configure DNS

The following lines need to be added to the /etc/hosts file of the development machine to allow for traffic to resolve to the correct containers:

$ sudo vim /etc/hosts
::1     object-storage orthanc imaging kafka
::1     imaging.local object-storage orthanc imaging imaging.local

Windows only

On Windows, the /etc/hosts file is located at C:\Windows\System32\drivers\etc\hosts. If this path does not exist, create the \etc\ directory and create a next text file called hosts inside of it.

Open Notepad as an Administrator (this can be done by right clicking on the program and choosing "Open as Administrator") and edit C:\Windows\System32\drivers\etc\hosts to include the following lines:

# Sonador DNS for ipv4 & ipv6
::1 object-storage orthanc imaging
::1 imaging.local object-storage orthanc imaging imaging.local

Save the file and proceed to the next step for deploying the containers.

Step 3. Deploy Docker Compose

Inside the imaging environment folder which you cloned in the previous step, run the following command:

$ docker-compose -f compose/core.yaml -f compose/pacs-secure.yaml -f compose/sonador.yaml up -d

The following output should be displayed:

Creating network "compose_default" with the default driver
Creating compose_object-storage_1 ... done
Creating compose_kafka_1          ... done
Creating compose_sonador-db_1     ... done
Creating compose_nginx_1          ... done
Creating compose_zookeeper_1      ... done
Creating compose_orthanc_1        ... done
Creating compose_orthanc-db_1     ... done
Creating compose_imaging_1        ... done

Step 4. Access Web UI and Configure Internal Port

Test to see if you can access the OHIF viewer in your browser.

The Sonador web application can be accessed via http://imaging.local:8070. The username/password for the environment are:

url: "http://imaging.local:8070"
username: "dev01"
password: "sonador@development-env"

Once authenticated, you should have a similar interface to the image below:

Sonador QuickStart: Patient List
The Sonador environment includes an embedded OHIF viewer that can be accessed at http://imaging.local:8070.
Troubleshoot: If the page refuses to load the UI and only a black screen is shown, restart the nginx container.
Configure the Internal Port

Go to http://imaging.local:8070/admin/visionaire/pacsimagingserver/ and click on dev01.

At the bottom where it says Internal Port: input 8042 as the value and click SAVE.

Step 5. Deploy and Configure Analytics Environment

From another bash terminal, run the following command inside the imaging folder to deploy a JupyterLab instance that can be used to interact with Sonador:

$ docker-compose -f compose/analytics.yaml up

Important: The JupyterLab container image includes a set of Python tools and libraries for working with medical imaging data. It is large (over 11GB) and may take some time to download from Docker Hub and deploy.

Once the image has finished deploying you should see output similar to that below in your terminal. Pay special attention to the "token" value in the URL, as this will be required for you to access the JupyterLab interface.

Sonador Quickstart: JupyterLab Startup
The token is unique to your deployment, make sure to copy this string to configure API access.

Copy the full token string at token=<TOKEN> and go to in your browser to configure a password. At the bottom of the page, paste in the token and define a password for authentication. Defining a password makes it easier to authenticate to JupyterLab in the future.

Upon entering the JuptyerLab interface, your view should be similar to the image below:

Sonador Quickstart: JupyterLab Launcher

Step 6. Install the Sonador CLI

In the JupyterLab interface, open up a new terminal and clone the Sonador CLI repository:

$ git clone

$ cd sonador-cli/

The Sonador command line client uses environment variables to make it easier to provide connection and authentication parameters. The development environment includes a sample configuration.

Copy the environment variables to the terminal environment by "sourcing" the file:

$ source ../env/sonador.env

Use the Sonador CLI to ensure that the environment is properly configure by listing the imaging servers (Orthanc instances) associated with Sonador:

$ python pacs list

If everything is working, you should see the following output verifying that the services are connected:

ID     Imaging Server Name    Default Server    Hostname      Port  Description
-----  ---------------------  ----------------  ----------  ------  -----------------------------------------------------------------------------------
dev01  Orthanc-Dev            True              orthanc       8842  Default Orthanc instance configured for the Oak-Tree Sonador reference environment.

You now have a working local Sonador imaging environment!

Example Notebooks

Within the JuptyerLab terminal, clone the Sonador Examples repository to learn how to interact with the platform and manage medical images.

$ git clone

Use the JuptyerLab file browser to locate sonador-examples and load sonador-client01.image-io.ipynb. Follow the instructions in the notebook to upload a sample CT dataset to Sonador.

Sonador Quickstart: JupyterLab Example Notebook
The Sonador examples repository provides notebooks that show how to upload data to Sonador, retrieve study instances, and fetch the meta and pixel data.

Once you have completed all instructions in the notebook, you can view the example CT study by opening http://imaging.local:8070 in your browser (or refreshing the page if you already have it open) and clicking on the C3N ... row in the "Study List."

Next Steps

Once you have completed the steps in this tutorial, you will have a fully functional Sonador development environment that you can explore. From here, you might consider:

Brandon Harper Oct 24, 2023
More Articles by Brandon Harper


Unable to find related content


Unable to retrieve data due to an error
No results found
Back to All Comments