pf_build

https://github.com/fnndsc/pf_build

Repository

README.adoc

= pf_build: **P**lugin **F**ramework **Build**er

`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 https://github.com/FNNDSC/python-chrisapp-template[ChRIS plugin template] mechanism and providing a web-based access vector.

== Need

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.

== How To Run

Consult the link:HOWTORUN.adoc[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.

== Workflow
`pf_build` will:

- Instantiate a new instance of the https://github.com/FNNDSC/python-chrisapp-template[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 https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens[ relevant documentation].

- Clone the instantiated template
+
Once instantiated, `pf_build` will clone this instantiated repo.

- Edit the template `bootstrap.sh`
+
Based on the provided meta data, `pf_build` will edit the `boostrap.sh` in the cloned repo.

- Execute the template `bootstrap.sh`
+
Once edited, `pf_build` will execute the `boostrap.sh` in the cloned repo.

- Commit the changes
+
Finally, `pf_build` will 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.

== API documentation

See link:docs/API.adoc[here] for an overview of the API end point as well as a complete exemplar calling sequence.

== Features
- 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.)

== Contributing
We welcome contributions! Please see link:CONTRIBUTING.adoc[CONTRIBUTING] for guidelines. We adhere strictly to our link:CODE_OF_CONDUCT.adoc[CODE_OF_CONDUCT].

== License
This project is licensed under the MIT License.

== Acknowledgements
This project is developed and maintained by the FNNDSC at Boston Children's Hospital and contributors. It relies heavily on the https://github.com/FNNDSC/python-chrisapp-template[ChRIS plugin template] originally developed by Jennings Zhang at the FNNDSC.

Owner

Citation (CITATION.cff)

cff-version: 1.2.0
message: "If you use pf_build, please cite it as below."
authors:
  - family-names: "Pienaar"
    given-names: "Rudolph"
title: "pf_build: Web-based Holistic AI Manager"
version: "0.1.0"
date-released: "2024-12-05"

GitHub Events