cookiecutter-chrisapp

A cookiecutter template for ChRIS plugin apps.

Abstract

This page describes how to get started with creating a ChRIS plugin. The first-time steps typically involve:

• Installing a python virtual environment for development.
• Creating (if not already done) github and dockerhub accounts.
• Checking out this repo and running the script and then associating the app you are creating with both github and dockerhub.

Requirements

• Python and pip (which is usually installed with Python)
• Latest Docker (17.04.0+) if you want to test your plugin's docker image and containers in your local machine. Visit https://docs.docker.com/install/ for installation directions

Install virtualenv and virtualenvwrapper

pip install virtualenv virtualenvwrapper

note: anaconda users on macOS should use the conda environment tools directly instead. See this thread and the linked discussion on the anaconda mailing list. A working set of commands is noted here.

Setup your virtual environments

Create a directory for your virtual environments e.g:

mkdir ~/python_envs

Open your .bashrc file:

vim ~/.bashrc

Add these two lines to your .bashrc file:

export WORKON_HOME=~/python_envs
source $(which virtualenvwrapper.sh | head -n 1)

Create a new Python3 virtual environment:

mkvirtualenv --python=python3 chrisapp_env

To activate chrisapp_env:

workon chrisapp_env

To deactivate chrisapp_env:

deactivate

GitHub Account

Create a GitHub account on https://github.com/ if you don't already have one.

Docker Hub Account

Create a Docker Hub account on https://hub.docker.com/ if you don't already have one.

Quickstart

The steps below show how to quickly create and setup a new ChRIS plugin app project.

1. Create a Python3 virtual environment for your plugin apps and activate it if you haven't created it yet (follow steps in Requirements).

2. Install the latest Cookiecutter in chrisapp_env if you haven't installed it yet:

   pip install -U cookiecutter
   

3. Generate a ChRIS plugin app project:

cookiecutter https://github.com/FNNDSC/cookiecutter-chrisapp.git

In running the above command, you will be prompted for an app project name. The app project name should be a valid python module name as described here https://www.python.org/dev/peps/pep-0008/#package-and-module-names.

The interactive script will ask you to choose between two types of ChRIS plugins.

1. FS (or Feed Synthesis) plugin app. These create (synthesize) a new top level Feed -- typically from some event (a user drags and drops files into a box; a user queries a database for data; etc). These plugins only enforce a single positional argument -- an output directory where the results of the synthesis event are stored. FS plugins create a new feed (data container) in the ChRIS system. Thus, FS plugins are always the single root of a pipeline or tree of plugin executions. If one considers a processing chain or pipeline as an abstracted linked list, an FS plugin corresponds to the head node of the list.
2. DS (or Data Synthesis) plugin app. These are by far the most common plugins and enforce two positional arguments: an input directory (typically the result of a previous plugin's output) and an output directory.

The first plugin of a pipeline would always be a single FS plugin followed by a (possibly branched) chain of DS plugins creating files in the same single feed that was created by the root FS plugin. Most of the time you will be creating a DS plugin when integrating your software application in ChRIS.

4. Create a new repository on https://github.com/your_github_username with the same name as the app project directory generated by the previous cookiecutter command. Make sure that the repository is public. Don’t initialize the repository with a README, a license or a .gitignore file.

5. Change the current working directory to the app project and initialize this local directory as a Git repository:

   git init
   

6. Add and commit the files in the local repository:

   git add .
   git commit -m "First commit"
   

7. Add the URL for the remote Github repository created in step 4 where your local repository will be pushed:

   git remote add origin **remote_Github_repository_URL** (eg. https://github.com/FNNDSC/pl-neuproseg.git)
   git remote -v
   

8. Push the changes in your local repository to GitHub:

   git push origin master
   

9. Create a new repository with automated build on your Docker Hub account (https://hub.docker.com).

   Once you log in, click the Create Repository + button. The website page will walk you through setting up the automated build. When prompted for the GitHub repository that you’d like to use for the automated build select the repository that you just created.

   It is extremely important that you tag your automatically built docker image with an appropriate version number based on your Github tags. So please create a new build rule by clicking the BUILD RULES + button. A good rule good be Source type: Tag, Source: /^[0-9.]+$/ and Docker Tag: version-{sourceref}.

   Click Create && Build button to finish the setup and trigger the automated build. For more information on Automated Builds, please visit https://docs.docker.com/docker-hub/builds/.

10. Modify requirements.txt, setup.py, Dockerfile and the Python code with the proper versions of Python dependencies and libraries and push your changes to Github.

    Look at https://github.com/FNNDSC/pl-simplefsapp (a simple fs plugin) and https://github.com/FNNDSC/pl-simpledsapp (a simple ds plugin) for guidance on getting started with your ChRIS plugin!

11. Once you've developed and properly tested your plugin app you can make a new release by running the provided release.sh script with a version number for the release.

12. Finally please consult the wiki to learn how to register your containerized plugin app to ChRIS and the ChRIS store.