Demo#

ScanHub is deployed using Docker and Docker Compose. Make sure they are installed. The following instructions will guide you through the process of an all-in-one deployment of ScanHub, i.e. all the services and the device connector will run on the same device.

1. Building ScanHub#

The microservices within ScanHub are all built on the same base image, to ensure that critical dependencies match and identical data models are used.

Note that the .github/workflows/deploy-containers.yml workflow deploys the latest scanhub-base image from the main branch to the GitHub Container Registry (GHCR). By default, this image is used when building ScanHub with Docker Compose.

The following steps build the scanhub-base image from the local code repository instead.

docker build -t scanhub-base -f services/base/Dockerfile .

To build ScanHub with the base image which was just created, use the following command.

Note: You don’t need to run docker compose build separately if you want to use the default setup — docker compose up -d creates all the required images if they are not already available.

docker compose build --build-arg SCANHUB_BASE_IMAGE=scanhub-base:latest

Alternatively, you can use the default image ghcr.io/brain-link/scanhub/scanhub-base:latest by running

docker compose build

Note: The repository contains an .env file which allows you to change the default image.

2. Starting ScanHub#

To start all the containers, run the docker compose command.

docker compose up -d

To access the user interface, open your browser and navigate to localhost. By default, ScanHub uses a self-signed HTTPS certificate, which will cause the browser to show a security warning. You may ignore this warning for localhost during development. If you run ScanHub for the first time, you are asked to create the first user when visiting localhost.

3. Register the Demo Device#

Devices communicating with ScanHub need to authenticate, which is done using a token-based approach.

  1. Log in and navigate to the library.

  2. Create a new device: enter a device name and description.

  3. After clicking ‘Create’, you can download a credentials file for the new device.

  4. Save the credentials file as device_credentials.json next to the example device in device-sdk/example.

4. Install and Run the Demo Device#

The demo device is built on the ScanHub device SDK, located in device-sdk. Dependencies are managed with uv, which creates and manages the virtual environment for you, so no separate environment setup is required.

Navigate to device-sdk and install the device-sdk package together with its example dependency group.

cd device-sdk
uv sync --group example

Last but not least, run the example script.

uv run example/example_usage.py

The following terminal output is expected:

Device ID: d5b8bacd-1f52-4aaf-a3af-c8ee4e5352ee
INFO:WebSockerHandler:WebSocket connection established.
INFO:DeviceStateMachine:[STATE] Transitioned to ONLINE
INFO:DeviceClient:Device registration sent.
Client started and waiting for commands from the server.
Server Feedback: Device ONLINE acknowledged.
Server Feedback: Device registered successfully

5. Setup a Demo Protocol#

To perform an acquisition with the demo device, first a protocol needs to be set up in ScanHub. In the user interface, navigate to Library and click on Create Sequence to upload the provided test sequence available in the example folder. After setting name, description and type, you need to upload device-sdk/example/test-sequence.seq as the sequence and device-sdk/example/header_test-sequence.xml as the ISMRMRD header file.

Once the sequence is uploaded, click on Create Protocol and fill in the form to create a demo protocol. Once the protocol is created, select it and click on Create Task. Thereby, a new acquisition task is created and assigned to the previously created protocol. Within the task creation form, you need to select the demo device created and the sequence created in the previous step. Calibration and field of view settings can be ignored for this demo.

6. Trigger the Demo Device#

In the ScanHub UI, navigate to Patients, click on the “+” button and fill the form to create a new patient for the demo. Open the patient by clicking the button to the left of the newly created patient.

Now, you should see the acquisition view for a patient within the ScanHub UI. Click the “+” button in the protocols section to create an instance from the protocol template we created in the previous step.

Before starting the demo acquisition, make sure the demo device is online. This is indicated by a green circle in the right section of the navigation bar.

Open the protocol, select the acquisition and click the play button to start the demo acquisition. You should see how the progress bar fills up. Once the acquisition is done, the ISMRMRD raw data file is uploaded and should appear in the drop down menu underneath the acquisition task. As soon as the raw data is uploaded, the workflow orchestration engine gets notified and automatically performs the image reconstruction using MRpro. The reconstruction result is uploaded in DICOM format and can be selected from the file drop down menu underneath the task, as soon as it is available.

Found a bug or ran into an issue? We’d love to hear about it! Please open an issue and we’ll take a look.