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)
ChRIS store backend (ChRIS_store)
ChRIS store frontend (ChRIS_store_ui)
chrisomatic (chrisomatic)
Orthanc server https://www.orthanc-server.com/
pfdcm (pfdcm)

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.

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

Usage

A default superuser chris:chris1234 is created.

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

Default Logins

website	username	password
ChRIS	chris	chris1234
ChRIS Store	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

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 provides a no-nonsense collection of scripts which use Docker Compose to run a minimal and complete ChRIS system.

v.s. `make.sh`

The conventional way to run a ChRIS system is ChRIS_ultron_backEnd/make.sh.

miniChRIS does not replace make.sh. However, for most users looking for how to run ChRIS and have it "just work," miniChRIS is right for you.

miniChRIS has 109 lines of shell code --- ChRIS_ultron_backEnd has 3,200
miniChRIS does not create files on host outside of named docker volumes
make.sh runs arbitrary chmod 755 and chmod -R 777 on the host filesystem.
miniChRIS is fully containerized.
make.sh has unlisted dependencies, does not work cross-platform (e.g. default bash on Mac not supported, no support for Windows)
minichris.sh does not have any command-line arguments. Usage: ./minichris.sh
The recommended way to run ./make.sh is: docker swarm leave --force && docker swarm init --advertise-addr 127.0.0.1 && ./unmake.sh && sudo rm -fr CHRIS_REMOTE_FS && rm -fr CHRIS_REMOTE_FS && ./make.sh -U -I -i
make.sh runs backend automatic tests.
minichris.sh provides a complete docker-compose.yml
make.sh uses docker stack deploy; docker-compose_dev.yml depends on .env and other variables set by make.sh

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. It is strongly recommended that you use an SSD!

How It Works

Traditionally, to bring up CUBE+pfcon+pman on a single-machine on-the-metal requires a few extra steps on the host.

CUBE setup typically involves:

waiting for web server to come online
creating a superuser
adding host as a compute environment
registering some plugins: pl-dircopy and pl-topologicalcopy are required

pman

pman setup involves:

joining a docker swarm
figuring out the STOREBASE environment variable

pman is special because it itself is a container which spawns other containers on its host.

It needs /var/run/docker.sock to be mounted inside the container. We can resolve the two setup requirements by connecting to the host's dockerd.

docker swarm

workarounds/swarm.sh manages single-machine swarm cluster state. When the service swarm-status is brought up, it tells the local docker daemon to create and join a swarm.

`STOREBASE`

STOREBASE is a space for files created by plugin instances. ./workarounds/storebase.sh derives the path of a docker volume and provides it to pman.

About: https://github.com/FNNDSC/ChRIS_ultron_backEnd/blob/78670f6abf0b6ebac7aeef75989893b4502d4823/docker-compose_dev.yml#L208-L222

elsie-dev/miniChRIS-docker