Initial commit

.dockerignore

@@ -0,0 +1,18 @@
+.git/
+.github/
+.dockerignore
+Dockerfile
+
+*~
+*.DS_Store
+*.egg-info/
+__pycache__/
+
+.docker
+
+.idea/
+.vscode/
+
+examples/
+
+venv/

.github/workflows/ci.yml

@@ -0,0 +1,156 @@
+# Continuous integration testing for ChRIS Plugin.
+# https://github.com/FNNDSC/python-chrisapp-template/wiki/Continuous-Integration
+#
+# - on push, release, and PR: run pytest
+# - on push to main: build and push container images as ":latest"
+# - on release: build and push container image with tag and
+#               upload plugin description to https://chrisstore.co
+
+name: build
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  release:
+    types: [ published ]
+
+jobs:
+  test:
+    name: Unit tests
+    if: false  # CI disabled by default, delete this line to enable CI
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v3
+      - uses: docker/setup-buildx-action@v2
+      - name: Cache Docker layers
+        uses: actions/cache@v2
+        with:
+          path: /tmp/.buildx-cache
+          key: ${{ runner.os }}-buildx-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-buildx-
+      - name: Build
+        uses: docker/build-push-action@v3
+        with:
+          build-args: extras_require=dev
+          context: .
+          load: true
+          push: false
+          tags: "localhost/local/app:dev"
+          cache-from: type=local,src=/tmp/.buildx-cache
+          cache-to: type=local,dest=/tmp/.buildx-cache
+      - name: Run pytest
+        run: |
+          docker run -v "$GITHUB_WORKSPACE:/app:ro" -w /app localhost/local/app:dev \
+            pytest -o cache_dir=/tmp/pytest
+
+  build:
+    name: Build
+    needs: [ test ]  # tests must pass before build
+    if: github.event_name == 'push' || github.event_name == 'release'
+    runs-on: ubuntu-22.04
+
+    # A local registry helps us reuse the built image between steps
+    services:
+      registry:
+        image: registry:2
+        ports:
+          - 5000:5000
+
+    steps:
+      - name: Get git tag
+        id: git_info
+        if: startsWith(github.ref, 'refs/tags/')
+        run: echo "::set-output name=tag::${GITHUB_REF##*/}"
+      - name: Get project info
+        id: determine
+        env:
+          git_tag: ${{ steps.git_info.outputs.tag }}
+        run: |
+          repo="${GITHUB_REPOSITORY,,}"  # to lower case
+          # if build triggered by tag, use tag name
+          tag="${git_tag:-latest}"
+
+          # if tag is a version number prefixed by 'v', remove the 'v'
+          if [[ "$tag" =~ ^v[0-9].* ]]; then
+            tag="${tag:1}"
+          fi
+
+          dock_image=$repo:$tag
+          echo $dock_image
+          echo "::set-output name=dock_image::$dock_image"
+          echo "::set-output name=repo::$repo"
+
+      - uses: actions/checkout@v3
+        # QEMU is used for non-x86_64 builds
+      - uses: docker/setup-qemu-action@v2
+        # buildx adds additional features to docker build
+      - uses: docker/setup-buildx-action@v2
+        with:
+          driver-opts: network=host
+        # cache slightly improves rebuild time
+      - name: Cache Docker layers
+        uses: actions/cache@v2
+        with:
+          path: /tmp/.buildx-cache
+          key: ${{ runner.os }}-buildx-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-buildx-
+
+      - name: Login to DockerHub
+        id: dockerhub_login
+        uses: docker/login-action@v2
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v2
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v3
+        id: docker_build
+        with:
+          context: .
+          file: ./Dockerfile
+          tags: |
+            localhost:5000/${{ steps.determine.outputs.dock_image }}
+            docker.io/${{ steps.determine.outputs.dock_image }}
+            ghcr.io/${{ steps.determine.outputs.dock_image }}
+          # if non-x86_84 architectures are supported, add them here
+          platforms: linux/amd64  #,linux/arm64,linux/ppc64le
+          push: true
+          cache-from: type=local,src=/tmp/.buildx-cache
+          cache-to: type=local,dest=/tmp/.buildx-cache
+
+      - name: Get plugin meta
+        id: pluginmeta
+        run: |
+          repo=${{ steps.determine.outputs.repo }}
+          dock_image=${{ steps.determine.outputs.dock_image }}
+          docker run --rm localhost:5000/$dock_image chris_plugin_info > /tmp/description.json
+          jq < /tmp/description.json  # pretty print in log
+          echo "::set-output name=title::$(jq -r '.title' < /tmp/description.json)"
+
+      - name: Update DockerHub description
+        uses: peter-evans/dockerhub-description@v2
+        continue-on-error: true  # it is not crucial that this works
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
+          short-description: ${{ steps.pluginmeta.outputs.title }}
+          readme-filepath: ./README.md
+          repository: ${{ steps.determine.outputs.repo }}
+
+      - name: Upload to ChRIS Store
+        if: github.event_name == 'release'
+        uses: FNNDSC/chrisstore-action@master
+        with:
+          descriptor_file: /tmp/description.json
+          auth: ${{ secrets.CHRIS_STORE_USER }}

.gitignore

@@ -0,0 +1,11 @@
+*~
+*.DS_Store
+*.egg-info/
+__pycache__/
+
+.docker
+
+.idea/
+.vscode/
+
+venv/

Dockerfile

@@ -0,0 +1,19 @@
+# Python version can be changed, e.g.
+# FROM python:3.8
+# FROM docker.io/fnndsc/conda:python3.10.2-cuda11.6.0
+FROM docker.io/python:3.10.6-slim-bullseye
+
+LABEL org.opencontainers.image.authors="FNNDSC <dev@babyMRI.org>" \
+      org.opencontainers.image.title="ChRIS Plugin Title" \
+      org.opencontainers.image.description="A ChRIS plugin that..."
+
+WORKDIR /usr/local/src/app
+
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+
+COPY . .
+ARG extras_require=none
+RUN pip install ".[${extras_require}]"
+
+CMD ["commandname", "--help"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 FNNDSC / BCH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,159 @@
+# _ChRIS_ Plugin Template
+
+This is a minimal template repository for _ChRIS_ plugin applications in Python.
+
+## About _ChRIS_ Plugins
+
+A _ChRIS_ plugin is a scientific data-processing software which can run anywhere all-the-same:
+in the cloud via a [web app](https://github.com/FNNDSC/ChRIS_ui/), or on your own laptop
+from the terminal. They are easy to build and easy to understand: most simply, a
+_ChRIS_ plugin is a command-line program which processes data from an input directory
+and creates data to an output directory with the usage
+`commandname [options...] inputdir/ outputdir/`.
+
+For more information, visit our website https://chrisproject.org
+
+## How to Use This Template
+
+Go to https://github.com/FNNDSC/python-chrisapp-template and click "Use this template".
+The newly created repository is ready to use right away.
+
+A script `bootstrap.sh` is provided to help fill in and rename values for your new project.
+It is optional to use.
+
+1. Edit the variables in `bootstrap.sh`
+2. Run `./bootstrap.sh`
+3. Follow the instructions it will print out
+
+## Example Plugins
+
+Here are some good, complete examples of _ChRIS_ plugins created from this template.
+
+- https://github.com/FNNDSC/pl-dcm2niix (basic command example)
+- https://github.com/FNNDSC/pl-mri-preview (uses [NiBabel](https://nipy.org/nibabel/))
+- https://github.com/FNNDSC/pl-fetal-cp-surface-extract (example using Python package project structure)
+
+## What's Inside
+
+| Path                       | Purpose                                                                                                                                                                                                  |
+|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `app.py`                   | Main script: start editing here!                                                                                                                                                                         |
+| `tests/`                   | Unit tests                                                                                                                                                                                               |
+| `setup.py`                 | [Python project metadata and installation script](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#setup-py)                                                        |
+| `requirements.txt`         | List of Python dependencies                                                                                                                                                                              |
+| `Dockerfile`               | [Container image build recipe](https://docs.docker.com/engine/reference/builder/)                                                                                                                        |
+| `.github/workflows/ci.yml` | "continuous integration" using [Github Actions](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions): automatic testing, building, and uploads to https://chrisstore.co |
+
+
+<!-- BEGIN README TEMPLATE
+
+# ChRIS Plugin Title
+
+[![Version](https://img.shields.io/docker/v/fnndsc/pl-appname?sort=semver)](https://hub.docker.com/r/fnndsc/pl-appname)
+[![MIT License](https://img.shields.io/github/license/fnndsc/pl-appname)](https://github.com/FNNDSC/pl-appname/blob/main/LICENSE)
+[![ci](https://github.com/FNNDSC/pl-appname/actions/workflows/ci.yml/badge.svg)](https://github.com/FNNDSC/pl-appname/actions/workflows/ci.yml)
+
+`pl-appname` is a [_ChRIS_](https://chrisproject.org/)
+_ds_ plugin which takes in ...  as input files and
+creates ... as output files.
+
+## Abstract
+
+...
+
+## Installation
+
+`pl-appname` is a _[ChRIS](https://chrisproject.org/) plugin_, meaning it can
+run from either within _ChRIS_ or the command-line.
+
+[![Get it from chrisstore.co](https://ipfs.babymri.org/ipfs/QmaQM9dUAYFjLVn3PpNTrpbKVavvSTxNLE5BocRCW1UoXG/light.png)](https://chrisstore.co/plugin/pl-appname)
+
+## Local Usage
+
+To get started with local command-line usage, use [Apptainer](https://apptainer.org/)
+(a.k.a. Singularity) to run `pl-appname` as a container:
+
+```shell
+singularity exec docker://fnndsc/pl-appname commandname [--args values...] input/ output/
+```
+
+To print its available options, run:
+
+```shell
+singularity exec docker://fnndsc/pl-appname commandname --help
+```
+
+## Examples
+
+`commandname` requires two positional arguments: a directory containing
+input data, and a directory where to create output data.
+First, create the input directory and move input data into it.
+
+```shell
+mkdir incoming/ outgoing/
+mv some.dat other.dat incoming/
+singularity exec docker://fnndsc/pl-appname:latest commandname [--args] incoming/ outgoing/
+```
+
+## Development
+
+Instructions for developers.
+
+### Building
+
+Build a local container image:
+
+```shell
+docker build -t localhost/fnndsc/pl-appname .
+```
+
+### Running
+
+Mount the source code `app.py` into a container to try out changes without rebuild.
+
+```shell
+docker run --rm -it --userns=host -u $(id -u):$(id -g) \
+    -v $PWD/app.py:/usr/local/lib/python3.10/site-packages/app.py:ro \
+    -v $PWD/in:/incoming:ro -v $PWD/out:/outgoing:rw -w /outgoing \
+    localhost/fnndsc/pl-appname commandname /incoming /outgoing
+```
+
+### Testing
+
+Run unit tests using `pytest`.
+It's recommended to rebuild the image to ensure that sources are up-to-date.
+Use the option `--build-arg extras_require=dev` to install extra dependencies for testing.
+
+```shell
+docker build -t localhost/fnndsc/pl-appname:dev --build-arg extras_require=dev .
+docker run --rm -it localhost/fnndsc/pl-appname:dev pytest
+```
+
+## Release
+
+Steps for release can be automated by [Github Actions](.github/workflows/ci.yml).
+This section is about how to do those steps manually.
+
+### Increase Version Number
+
+Increase the version number in `setup.py` and commit this file.
+
+### Push Container Image
+
+Build and push an image tagged by the version. For example, for version `1.2.3`:
+
+```
+docker build -t docker.io/fnndsc/pl-appname:1.2.3 .
+docker push docker.io/fnndsc/pl-appname:1.2.3
+```
+
+### Get JSON Representation
+
+Run [`chris_plugin_info`](https://github.com/FNNDSC/chris_plugin#usage)
+to produce a JSON description of this plugin, which can be uploaded to a _ChRIS Store_.
+
+```shell
+docker run --rm localhost/fnndsc/pl-appname:dev chris_plugin_info > chris_plugin_info.json
+```
+
+END README TEMPLATE -->