pf_build is a FastAPI-based web application that greatly simplifies/accelerates the construction of ChRIS plugins. ChRIS plugins are applications that run on the ChRIS platform. Importantly, ChRIS plugins are also fully independent dockerized applications that can also run directly on Linux, macOS, and Windows without needing ChRIS. This service, pf_build, streamlines the process of creating a basic ChRIS plugin by automating the use of the ChRIS plugin template mechanism and providing a web-based access vector.
ChRIS plugins are mostly developed by ChRIS developers, and anecdotal evidence suggests that many developers simply find the "getting started" problem too complex. Observing this, our hypothesis is that simplifying this process could help many developers by lowering this "activation energy".
pf_build was developed as part of the philosophy of "reducing barrier to entry" for researchers and developers to get started with ChRIS applications. It attempts to reduce the task of plugin/application construction to simply entering a few details about the author and appliction, after which pf_build automates all the steps to create a fully fledged, albeit mostly dummy, application.
Regardless of ChRIS per se, the artifacts created by this service are useful as python applications in their own right, with bundled Dockerfile, requirements.txt and setup.py for "free", allowing one stop turn key creation of a fully fledged generic python project, albeit with a slight ChRIS-opiniation.
Consult the HOWTORUN document for complete details on how to start an instance of the pf_build server. An important thing to keep in mind is that the service needs to access github on behalf of some user. This identity is passed to pf_build on startup via a github token stored in an environment variable. By default, all activity that pf_build will perform on github will be associated with that Personal Access Token (PAT).
Each call to the service API endpoint, however, offers the option to pass an override token for that call. In this way the service can be instantiated with a default identity, but still offer users the ability to use their own PATs.
pf_build will:
-
Instantiate a new instance of the ChRIS plugin template.
Note that the github repo and activity will be associated with the user whose PAT was used to startup the service. Instructions for creating a PAT is out of scope of this document, but interested readers can consult the relevant documentation.
-
Clone the instantiated template
Once instantiated,
pf_buildwill clone this instantiated repo. -
Edit the template
bootstrap.shBased on the provided meta data,
pf_buildwill edit theboostrap.shin the cloned repo. -
Execute the template
bootstrap.shOnce edited,
pf_buildwill execute theboostrap.shin the cloned repo. -
Commit the changes
Finally,
pf_buildwill commit these changes back to github, resulting in a fully instantiated ChRIS plugin/application suitable for immediate checkout and further development.
Providing an explicit PAT in the call to pf_build is not required but might become the default in future.
See here for an overview of the API end point as well as a complete exemplar calling sequence.
-
Simple/single API POST endpoint
-
RESTful APIs with versioning
-
MongoDB integration using pfmongo
-
Dockerized deployment
(Note mongoDB integration is not currently complete and pf_build does store state information in a per-instantiated container! This will be changed in a future update.)
We welcome contributions! Please see CONTRIBUTING for guidelines. We adhere strictly to our CODE_OF_CONDUCT.
This project is developed and maintained by the FNNDSC at Boston Children’s Hospital and contributors. It relies heavily on the ChRIS plugin template originally developed by Jennings Zhang at the FNNDSC.