Skip to content

Commit

Permalink
Updates from bootstrap.sh
Browse files Browse the repository at this point in the history
  • Loading branch information
matthew.hu committed Jul 26, 2024
1 parent 70e59d4 commit 3ee8d0a
Show file tree
Hide file tree
Showing 7 changed files with 41 additions and 370 deletions.
4 changes: 1 addition & 3 deletions .github/workflows/ci.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@ on:
jobs:
test:
name: Unit tests
if: false # delete this line to enable automatic testing
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v4
Expand All @@ -41,8 +40,7 @@ jobs:
build:
name: Build
if: false # delete this line and uncomment the line below to enable automatic builds
# if: github.event_name == 'push' || github.event_name == 'release'
if: github.event_name == 'push' || github.event_name == 'release'
# needs: [ test ] # uncomment to require passing tests
runs-on: ubuntu-22.04

Expand Down
8 changes: 4 additions & 4 deletions Dockerfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@
FROM docker.io/python:3.12.1-slim-bookworm

LABEL org.opencontainers.image.authors="FNNDSC <[email protected]>" \
org.opencontainers.image.title="ChRIS Plugin Title" \
org.opencontainers.image.description="A ChRIS plugin that..."
org.opencontainers.image.title="Metadata Harvester" \
org.opencontainers.image.description="A ChRIS plugin to do collect DICOM meta data"

ARG SRCDIR=/usr/local/src/app
ARG SRCDIR=/usr/local/src/pl-mdharvest
WORKDIR ${SRCDIR}

COPY requirements.txt .
Expand All @@ -19,4 +19,4 @@ RUN pip install ".[${extras_require}]" \
&& cd / && rm -rf ${SRCDIR}
WORKDIR /

CMD ["commandname"]
CMD ["mdharvester"]
107 changes: 20 additions & 87 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,76 +1,10 @@
# _ChRIS_ Plugin Template
# Metadata Harvester

[![test status](https://github.com/FNNDSC/python-chrisapp-template/actions/workflows/src.yml/badge.svg)](https://github.com/FNNDSC/python-chrisapp-template/actions/workflows/src.yml)
[![MIT License](https://img.shields.io/github/license/FNNDSC/python-chrisapp-template)](LICENSE)
[![Version](https://img.shields.io/docker/v/fnndsc/pl-mdharvest?sort=semver)](https://hub.docker.com/r/fnndsc/pl-mdharvest)
[![MIT License](https://img.shields.io/github/license/fnndsc/pl-mdharvest)](https://github.com/FNNDSC/pl-mdharvest/blob/main/LICENSE)
[![ci](https://github.com/FNNDSC/pl-mdharvest/actions/workflows/ci.yml/badge.svg)](https://github.com/FNNDSC/pl-mdharvest/actions/workflows/ci.yml)

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 wrapper example)
- <https://github.com/FNNDSC/pl-adapt_object_mesh> (parallelizes a command)
- https://github.com/FNNDSC/pl-mri-preview (uses [NiBabel](https://nipy.org/nibabel/))
- https://github.com/FNNDSC/pl-pyvista-volume (example using Python package project structure and pytest)
- https://github.com/FNNDSC/pl-fetal-cp-surface-extract (has a good README.md)

## 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 |

## Contributing

The source code for the `main` branch of this repository is on the
[src](https://github.com/fnndsc/python-chrisapp-template/tree/src)
branch, which has an additional file
[`.github/workflows/src.yml`](https://github.com/FNNDSC/python-chrisapp-template/blob/src/.github/workflows/src.yml)
When tests pass, changes are automatically merged into `main`.
Developers should commit to or make pull requests targeting `src`.
Do not push directly to `main`.

This is a workaround in order to do automatic testing of this template
without including the `.github/workflows/src.yml` file in the template itself.

<!-- 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/)
`pl-mdharvest` is a [_ChRIS_](https://chrisproject.org/)
_ds_ plugin which takes in ... as input files and
creates ... as output files.

Expand All @@ -80,34 +14,34 @@ creates ... as output files.

## Installation

`pl-appname` is a _[ChRIS](https://chrisproject.org/) plugin_, meaning it can
`pl-mdharvest` is a _[ChRIS](https://chrisproject.org/) plugin_, meaning it can
run from either within _ChRIS_ or the command-line.

## 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:
(a.k.a. Singularity) to run `pl-mdharvest` as a container:

```shell
apptainer exec docker://fnndsc/pl-appname commandname [--args values...] input/ output/
apptainer exec docker://fnndsc/pl-mdharvest mdharvester [--args values...] input/ output/
```

To print its available options, run:

```shell
apptainer exec docker://fnndsc/pl-appname commandname --help
apptainer exec docker://fnndsc/pl-mdharvest mdharvester --help
```

## Examples

`commandname` requires two positional arguments: a directory containing
`mdharvester` 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/
apptainer exec docker://fnndsc/pl-appname:latest commandname [--args] incoming/ outgoing/
apptainer exec docker://fnndsc/pl-mdharvest:latest mdharvester [--args] incoming/ outgoing/
```

## Development
Expand All @@ -119,18 +53,18 @@ Instructions for developers.
Build a local container image:

```shell
docker build -t localhost/fnndsc/pl-appname .
docker build -t localhost/fnndsc/pl-mdharvest .
```

### Running

Mount the source code `app.py` into a container to try out changes without rebuild.
Mount the source code `mdharvester.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.12/site-packages/app.py:ro \
-v $PWD/mdharvester.py:/usr/local/lib/python3.12/site-packages/mdharvester.py:ro \
-v $PWD/in:/incoming:ro -v $PWD/out:/outgoing:rw -w /outgoing \
localhost/fnndsc/pl-appname commandname /incoming /outgoing
localhost/fnndsc/pl-mdharvest mdharvester /incoming /outgoing
```

### Testing
Expand All @@ -140,8 +74,8 @@ 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
docker build -t localhost/fnndsc/pl-mdharvest:dev --build-arg extras_require=dev .
docker run --rm -it localhost/fnndsc/pl-mdharvest:dev pytest
```

## Release
Expand All @@ -158,8 +92,8 @@ Increase the version number in `setup.py` and commit this file.
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
docker build -t docker.io/fnndsc/pl-mdharvest:1.2.3 .
docker push docker.io/fnndsc/pl-mdharvest:1.2.3
```

### Get JSON Representation
Expand All @@ -168,10 +102,9 @@ Run [`chris_plugin_info`](https://github.com/FNNDSC/chris_plugin#usage)
to produce a JSON description of this plugin, which can be uploaded to _ChRIS_.

```shell
docker run --rm docker.io/fnndsc/pl-appname:1.2.3 chris_plugin_info -d docker.io/fnndsc/pl-appname:1.2.3 > chris_plugin_info.json
docker run --rm docker.io/fnndsc/pl-mdharvest:1.2.3 chris_plugin_info -d docker.io/fnndsc/pl-mdharvest:1.2.3 > chris_plugin_info.json
```

Intructions on how to upload the plugin to _ChRIS_ can be found here:
https://chrisproject.org/docs/tutorials/upload_plugin

END README TEMPLATE -->
Loading

0 comments on commit 3ee8d0a

Please sign in to comment.