{"id":19612448,"url":"https://github.com/fnndsc/cookiecutter-chrisapp","last_synced_at":"2025-04-27T22:34:05.160Z","repository":{"id":54571142,"uuid":"105697312","full_name":"FNNDSC/cookiecutter-chrisapp","owner":"FNNDSC","description":"A cookiecutter template for Chris app plugins","archived":false,"fork":false,"pushed_at":"2024-10-08T17:56:20.000Z","size":221,"stargazers_count":7,"open_issues_count":7,"forks_count":6,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-05T04:31:53.496Z","etag":null,"topics":["cookiecutter","docker","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FNNDSC.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-03T20:03:47.000Z","updated_at":"2024-10-08T17:56:24.000Z","dependencies_parsed_at":"2022-08-13T20:10:11.782Z","dependency_job_id":null,"html_url":"https://github.com/FNNDSC/cookiecutter-chrisapp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FNNDSC%2Fcookiecutter-chrisapp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FNNDSC%2Fcookiecutter-chrisapp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FNNDSC%2Fcookiecutter-chrisapp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FNNDSC%2Fcookiecutter-chrisapp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FNNDSC","download_url":"https://codeload.github.com/FNNDSC/cookiecutter-chrisapp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251219600,"owners_count":21554444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cookiecutter","docker","python3"],"created_at":"2024-11-11T10:46:49.361Z","updated_at":"2025-04-27T22:34:00.150Z","avatar_url":"https://github.com/FNNDSC.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"####\nNew!\n####\n\nIf you're creating a *ChRIS* plugin wrapper for an existing Python program, read:\n`HOW TO: Convert an existing Python app \u003chttps://github.com/FNNDSC/chris_plugin/wiki/HOW-TO:-Convert-an-existing-Python-app\u003e`_.\n\nIf you're trying to create a new program or a *ChRIS* plugin wrapper for a non-Python program,\ntry using https://github.com/FNNDSC/python-chrisapp-template\n\nThis repository, ``cookiecutter-chrisapp``, describes an older method for how to create *ChRIS* plugins.\nIt works and remains for historical purposes.\n\n############################\ncookiecutter-chrisapp |Logo| \n############################\n\n|License| |Last Commit| |CI|\n\n.. |Logo| image:: ../assets/logo_chris.png?raw=true\n  :alt: ChRIS Logo\n.. |License| image:: https://img.shields.io/github/license/fnndsc/cookiecutter-chrisapp.svg\n  :alt: License\n  :target: https://github.com/FNNDSC/cookiecutter-chrisapp/blob/master/LICENSE\n.. |Last Commit| image:: https://img.shields.io/github/last-commit/fnndsc/cookiecutter-chrisapp.svg\n  :alt: Last Commit\n  :target: https://github.com/FNNDSC/cookiecutter-chrisapp/commits\n.. |CI| image:: https://github.com/FNNDSC/cookiecutter-chrisapp/workflows/test/badge.svg\n  :alt: Github Actions\n  :target: https://github.com/FNNDSC/cookiecutter-chrisapp/actions\n\nThis repo provides a cookiecutter template for ChRIS plugin apps. Using this cookiecutter will allow you to *easily* create ChRIS plugins using a ``python`` template, with baked in support for easy containerization. Recommended additional steps guide you through setting up a github repo for your plugin, triggering automatic containerization of your plugin, and automatically publishing to ``dockerhub`` and a ``chrisstore``.\n\nNote that though the plugin skeleton itself is a ``python`` construct, your application itself *does not have to be python*. Support for non-python applications is a more advanced topic with help provided elsewhere. Using this ``cookiecutter`` will require at the very minimum some python boilerplate to wrap around your application if it is non-python.\n\nBackground\n==========\n\nBefore we begin, you should be familiar with these topics:\n\n* ``git``\n* ``docker``\n* ``python``\n\nFor new developers, we recommend the following reading (seasoned developers can skip this):\n\n* `What is a ChRIS plugin? \u003chttps://github.com/FNNDSC/cookiecutter-chrisapp/wiki/About-Plugins#what-is-a-chris-plugin\u003e`\n* `Introduction to Docker \u003chttps://github.com/FNNDSC/cookiecutter-chrisapp/wiki/Introduction-to-Docker\u003e`\n\nAlso, there is an *implicit* assumption in this documentation that you are on some OS that provides some flavour of a POSIX command line shell (``bash`` or ``zsh`` are recommended) on some UN*X env (typically some Linux distro or macOS). Please note that if you are on Windows, we have not tested these instructions on a default windows console (or PowerShell) and YMMV. We typically don't recommend using Windows for running/hosting a ChRIS system, but it could be used for developing plugins.\n\nWhat will this cookiecutter do?\n===============================\n\nIn a nutshell this cookiecutter, will at the very minimum:\n\n* create a fully formed, but *empty* ChRIS plugin on your local filesystem (created in the directory you run the ``cookiecutter``);\n* provide a Dockerfile that you can use to create containers of your plugin;\n* provide some testing, dependency checking, and documentation files for you;\n\nWe also provide additional \u003chttps://github.com/FNNDSC/cookiecutter-chrisapp/wiki/Quickstart\u003e and instructions (and encouragement) for you to\n\n* push your plugin code to ``github``;\n* setup some additional hooks to allow for automatic building of containers for various architectures (``x86_64``, ``PowerPC``, and ``ARM``);\n\n\nGetting Started\n===============\n\nBasic usage of this template requires the `cookiecutter \u003chttps://github.com/cookiecutter/cookiecutter\u003e` tool and the assumption of a Python virtual environment (see \u003chttps://github.com/FNNDSC/cookiecutter-chrisapp/wiki/Python-Woes#venv\u003e). \n\nIn a terminal, go to some directory that you want to contain the plugin code, and type\n\n.. code::\n\n    pip install -U cookiecutter\n    cookiecutter https://github.com/FNNDSC/cookiecutter-chrisapp.git\n\nWhen you run the above, you will be asked a series of questions. At the very least you should have a ``name`` in mind for your application, and provide this name when prompted. Note that other than the name, all the other questions can be simply skipped (by pressing ``enter``) if you so desire. Any entries you make (or don't make) can be easily modified after the ``cookiecutter`` has completed.\n\nOne final note of interset here concerns the ``Select app_type`` prompt of the ``cookiecutter``. Almost all plugins are of type ``ds`` (the default). Unless you have specific reason, you will most likely always be building ``ds`` type plugins (this is also the default). If you are doing this for the very first time, you will definitely want to code a ``ds`` plugin type. What are the plugin types? Take a look \u003chttps://github.com/FNNDSC/cookiecutter-chrisapp/wiki/About-Plugins\u003e.\n\nWhat do the questions in the ``cookiecutter`` mean? See `here \u003chttps://github.com/FNNDSC/cookiecutter-chrisapp/wiki/CookieCutter-Questions\u003e`\n\nFirst Steps\n===========\n\nOnce you've answered all the ``cookiecutter`` questions you'll be quietly returned to the prompt. In your current directory/folder will be a new subdirectory of the following structure (assuming here that you called your plugin ``pl-app`` -- the default):\n\n.. code::\n\n    pl-app/\n    ├── app\n    │   ├── app.py\n    │   ├── __init__.py\n    │   ├── __main__.py\n    │   └── tests\n    │       ├── __init__.py\n    │       └── test_app.py\n    ├── Dockerfile\n    ├── LICENSE\n    ├── README.rst\n    ├── requirements.txt\n    └── setup.py\n    \nYour tree might look slightly different. Don't worry about that. \n\nFrom your perspective, the most important file is the ``app.py`` (and again, your name here will be different). Nonetheless, this constitutes the main entry point to your plugin code, and in the absolute minimum case is the only file you need to edit. Good practice here would be to also construct tests (off ``test_app.py``) and flesh out dependencies (``requirements.txt``) and write good documentation (``README.rst``).\n\nYou might be tempted to just try and run the ``app.py`` directly! We discourage this, simply because **this is python module, not a python app**. It needs to be imported into an actual standalone runnable entity. The ``cookiecutter`` has provided a ``setup.py`` for you for this very purpose which will automatically create a fully formed app (see next paragraph). \n\nThus, at this juncture, you can in fact create and run that plugin *as is* without any additional coding on your part. It won't of course do much of anything useful, but it is a almost fully formed out-of-the-box and is just waiting to be given purpose. Note that *running* it is best performed by actually containerizing the plugin and running the docker image. That might sound complex, but the ``cookiecutter`` has already provided all the tools to enable this for you. You just need to follow the `steps \u003chttps://github.com/FNNDSC/cookiecutter-chrisapp/wiki/Developer-Guide\u003e`.\n\nThe Developer Guide provides instructions for two ways to run your plugin right now. Again, we recommend you taking the extra steps to construct a local docker image and run that, but you can also run your plugin *on the metal* so to speak by installing it to a python virtual environment (not really recommended).\n\nThe Developer Guide also provides some guidance on debugging.\n\nNext Step -- get on git\n=======================\n\nHaving created a plugin scaffolding and possibly created/run it as a test, you are now ready for the next recommended steps:\n\n\u003chttps://github.com/FNNDSC/cookiecutter-chrisapp/wiki/Quickstart\u003e:\n\n* Create a repository on github and check this scaffolding in.\n* Build a container image and manually push to Dockerhub\n\nAutomatic builds\n=================\n\nWhile optional, automatic builds are highly recommended. These can be setup so that whenever you `git push` changes to your source code, new container images will be automatically created for you and pushed to Dockerhub. These containers will by default be multi-arch.\n\n\u003chttps://github.com/FNNDSC/cookiecutter-chrisapp/wiki/Automatic-Builds\u003e\n\nNote that you need to do nothing more once you have setup automatic builds. Each time you push changes to your code, at some point after that you will get an email from Dockerhub concerning the results of that build. As part of this process, whatever tests you have created (in `app_test.py`) will be executed and the results also returned to you. Note that an image is built and pushed to Dockerhub irrespective of your test results status.\n\nPlease review our `best practices \u003chttps://github.com/FNNDSC/cookiecutter-chrisapp/wiki/Best-Practices\u003e` regarding publication of ChRIS plugins.\n\nFinally, the automatic build process is asynchronous from your perspective. Once you \n\n.. code::\n\n    git push \u0026\u0026 git tag \u003csomeTag\u003e \u0026\u0026 git push --tags\n    \nthere will be no inidcation in your terminal that anything has happened other than the the `git` operations. In order to check on your builds, go to the `Actions` tab on the github page of your repo to monitor the state of the build process.\n\nCODE\n====\n\nAt this point you are ready to really start coding. See our \u003chttps://github.com/FNNDSC/cookiecutter-chrisapp/wiki/Coding-Guide\u003e for some hints and strategies.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnndsc%2Fcookiecutter-chrisapp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffnndsc%2Fcookiecutter-chrisapp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffnndsc%2Fcookiecutter-chrisapp/lists"}