miniChRIS

Run a demo of ChRIS. https://chrisproject.org/

Abstract

ChRIS is an open-source platform facilitating cloud-based medical compute. This repository, miniChRIS-docker, provides a docker-compose based distribution of the ChRIS system including:

ChRIS backend (ChRIS_ultron_backEnd a.k.a. CUBE)
ChRIS frontend (ChRIS_ui)
compute controller (pfcon)
process manager (pman)
chrisomatic (chrisomatic)
Orthanc server https://www.orthanc-server.com/
pfdcm (pfdcm)
oxidicom (oxidicom)
hasura (Hasura)

Image tags are pinned to stable versions, so miniChRIS might be out-of-date with development versions of ChRIS components. Please visit the repositories linked above for instructions on how to run development environments for the latest versions.

Which ChRIS???

miniChRIS-docker is the easiest, fastest, and most portable way to run ChRIS.
miniChRIS-podman uses rootless Podman to run ChRIS.
ChRIS_ultron_backEnd/make.sh runs the ChRIS backend in development mode with pman on Docker swarm and optionally runs integration tests.

System Requirements

miniChRIS requires docker-compose version v2.6 or above.

Quick Start

git clone https://github.com/FNNDSC/miniChRIS-docker.git
cd miniChRIS-docker
./minichris.sh

By default, only some of ChRIS is enabled. Optional components can be started afterwards using Docker Compose Profiles. e.g.

# start PACS query and retrieve services
docker compose --profile pacs up -d

# start the Hasura GraphQL engine and database event triggers
docker compose --profile hasura up -d

Usage

A default superuser chris:chris1234 is created.

website	URL
ChRIS_ui	http://localhost:8020/
ChRIS admin	http://localhost:8000/chris-admin/
Orthanc	http://localhost:8042/

Default Logins

website	username	password
ChRIS	chris	chris1234
Orthanc	orthanc	orthanc

Start

./minichris.sh

Stop

./unmake.sh

Not Working?

Make sure you have docker and docker-compose both installed and working properly.
Stop all running containers.
No process should be bound to ports 5005, 5010, 5055, 8000, 8010, 8020, 8021

Still Not Working?

Try docker compose down -v --remove-orphans.

Network Configuration

To run miniChRIS remotely it is necessary to replace occurrences of localhost with your machine's hostname or IP address in docker-compose.yml.

sed -i -e 's/localhost/my_machines_hostname/' docker-compose.yml
docker compose up -d

Add Plugins to CUBE

Plugins are added to ChRIS via the Django admin dashboard.

https://github.com/FNNDSC/ChRIS_ultron_backEnd/wiki/%5BHOW-TO%5D-Register-a-plugin-via-Django-dashboard

Alternatively, plugins can be added declaratively. A common use case would be to run locally built Python chris_plugin-based ChRIS plugins. These can be added using chrisomatic by listing their (docker) image tags. For example, if your local image was built with the tag localhost/myself/pl-workinprogress by running

docker build -t localhost/myself/pl-workinprogress .

The bottom of your chrisomatic.yml file should look like

  plugins:
    - name: pl-dircopy
      version: 2.1.1
    - name: pl-tsdircopy
      version: 1.2.1
    - name: pl-topologicalcopy
      version: 0.2
    - name: pl-simpledsapp
      version: 2.1.0
    - localhost/myself/pl-workinprogress

After modifying chrisomatic.yml, apply the changes by rerunning ./minichris.sh

For details, see https://github.com/FNNDSC/chrisomatic#plugins-and-pipelines

Github Actions

miniChRIS can be used as a step in Github Actions workflows to spin up an ephermeral instance of the ChRIS backend and its ancillary services for the purpose of end-to-end testing.

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: Do nothing useful
    steps:
    - name: setup CUBE
      id: cube
      uses: FNNDSC/miniChRIS-docker@master
    - name: make a request
      run: curl -u chris:chris1234 http://localhost:8000/api/v1/

Adding Plugins

plugins should be a whitespace-separated list of plugin identifiers. Lines starting with # are treated as comments and ignored. Plugin identifiers are interpreted by chrisomatic as described here: https://github.com/fnndsc/chrisomatic#plugins-and-pipelines

Example

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: Do nothing useful
    steps:
    - name: setup CUBE
      id: cube
      uses: FNNDSC/miniChRIS-docker@master
      with:
        plugins: |
          https://chrisstore.co/api/v1/plugins/157/
          pl-lung_cnp
          ghcr.io/fnndsc/pl-re-sub:1.1.1

Optimization

Suppose you want to run a test which needs the CUBE server, database, and oxidicom, but you don't need to be able to run plugins. You can omit the workers and pfcon from startup, which can improve startup speeds and reduce memory usage.

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: Do nothing useful
    steps:
    - name: setup CUBE
      id: cube
      uses: FNNDSC/miniChRIS-docker@master
      with:
        services: chris oxidicom

Examples

FNNDSC/ChRIS_ui/.github/workflows/tests.yml uses miniChRIS for testing using Cypress
FNNDSC/cookicutter-chrisapp/.github/workflows/test.yml uses mihiChRIS for end-to-end testing.
FNNDSC/cni-store-proxy/package.json uses miniChRIS as a git submodule for a local dev environment.

About miniChRIS

Goals

fast and minimal
practical for E2E testing

Non-Goals

production use
back-end development environment

Performance

./minichris.sh takes 30-60 seconds on a decent laptop (quad-core, 16 GB, SSD) and takes 2-3 minutes in Github Actions' Ubuntu VMs.

Development

You can use hasura-cli on the metal like this:

env HASURA_GRAPHQL_ENDPOINT=http://localhost:8090 hasura --help