A cookiecutter template for ChRIS plugin apps.
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.
pip(which is usually installed with Python)
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
Setup your virtual environments
Create a directory for your virtual environments e.g:
Open your .bashrc file:
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:
To deactivate chrisapp_env:
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.
The steps below show how to quickly create and setup a new ChRIS plugin app project.
Create a Python3 virtual environment for your plugin apps and activate it if you haven't created it yet (follow steps in Requirements).
Install the latest Cookiecutter in
chrisapp_envif you haven't installed it yet:
pip install -U cookiecutter
Generate a ChRIS plugin app project:
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.
- 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.
- 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.
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
Change the current working directory to the app project and initialize this local directory as a Git repository:
Add and commit the files in the local repository:
git add . git commit -m "First commit"
Add the URL for the remote Github repository created in
step 4where 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
Push the changes in your local repository to GitHub:
git push origin master
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. At the top of the page, enter a name for the dockerhub repository -- this name can be anything of course. We recommend using the same as the github repo. Then, click on the github icon towards the bottom (it also should say "Connected" under the icon). For the github organization choose, for example, FNNDSC, and then within that organization select the repository created above.
A default build rule will be provided which should be left intact. In addition to the default rule, it is extremely important that you tag your automatically built docker image with an appropriate version number based on your Github tags. Please create an additional new build rule by clicking the
BUILD RULES +button. A good rule good be Source type:
/^[0-9.]+$/and Docker Tag:
Create && Buildbutton to finish the setup and trigger the automated build.
For more information on Automated Builds, please visit https://docs.docker.com/docker-hub/builds/.
Dockerfileand the Python code with the proper versions of Python dependencies and libraries and push your changes to Github.
Once you've developed and properly tested your plugin app you can make a new release by running the provided
release.shscript with a version number for the release.
Finally please consult the wiki to learn how to register your containerized plugin app to ChRIS and the ChRIS store.