<!-- Header block for project -->
<hr>
<div align="center">
<h1 align="center">Unity Application Generator</h1>
<!-- ☝️ Replace with your repo name ☝️ -->
</div>
<pre align="center">Creates and registers a Unity OGC application package</pre>
<!-- Header block for project -->
[app-pack-generator](https://github.com/unity-sds/app-pack-generator) | [unity-example-application](https://github.com/unity-sds/unity-example-application)
## Features
* Uses [app-pack-generator](https://github.com/unity-sds/app-pack-generator) to create CWL, application descriptor and Docker image
* Can output Jupyter noteboook parameterization for debugging purposes
* Pushes generated Docker image to a Docker registry
* Pushes generated application package files to a Dockstore application registry
## Requirements
* [app-pack-generator](https://github.com/unity-sds/app-pack-generator)
* [Unity-py](https://pypi.org/project/unity-sds-client/)
## Setup Instructions
### Install from Github
```
pip install git+https://github.com/unity-sds/unity-app-generator.git
```
### Install Locally
```
git clone https://github.com/unity-sds/unity-app-generator.git
pip install unity-app-generator
```
## Usage
Unity application generation is accomplished by using the `build_ogc_app` program. It uses a stateful architecture such as in other programs such as ``git`` where actions on a repository can be done in a series of steps. These steps are listed when running `build_ogc_app --help`.
```
usage: build_ogc_app [-h] [--state_directory STATE_DIRECTORY] {init,build_docker,push_docker,parameters,build_cwl,push_app_registry} ...
Unity Application Package Generator
positional arguments:
{init,build_docker,push_docker,parameters,build_cwl,push_app_registry}
init Initialize a Git repository for use by this application. Creates a .unity_app_gen directory in the destination directory
build_docker Build a Docker image from the initialized application directory
push_docker Push a Docker image from the initialized application directory to a remote registry
parameters Display parsed notebook parameters
build_cwl Create OGC compliant CWL files from the repository and Docker image
push_app_registry Push CWL files to Dockstore application registry
options:
-h, --help show this help message and exit
--state_directory STATE_DIRECTORY
An alternative location to store the application state other than .unity_app_gen
```
By default a state directory name `.unity_app_gen` is created in the repository the tool is targeting. Usually this is within the repository directory itself unless the `--state_directory` argument is used. This directory contains metadata information and generated files created by steps and needed for subsequent steps.
### init
Before using the tool with a repository the state directory needs to be initialized:
```
usage: build_ogc_app init [-h] [-c CHECKOUT] source_repository [destination_directory]
positional arguments:
source_repository Directory or Git URL of application source files, default is current directory
destination_directory
Directory where to check out source repository, default is a directory under the current subdirectory with same basename as the
source_repository
options:
-h, --help show this help message and exit
-c CHECKOUT, --checkout CHECKOUT
Git hash, tag or branch to checkout from the source repository
```
This can be accomplished with an existing clone of a repository or the tool can clone the repository locally for you. If no directory is supplied the tool will assume you would like to initialize the current directory. When working interatively it is suggested to change to the directory you are working with and use the script from there. This simplifies program usage and does not require you to use the `--state_directory` argument on each call.
For example to initialize an repository and use it locally:
```
git clone https://github.com/unity-sds/unity-example-application.git
cd unity-example-application
build_ogc_app init
```
Or to have the tool clone and initialize the repository for you:
```
build_ogc_app init https://github.com/unity-sds/unity-example-application.git unity-example-application
cd unity-example-application
```
### build_docker
The `build_docker` command does not require any additional arguments. It will utilize [app-pack-generator](https://github.com/unity-sds/app-pack-generator) and [repo2docker](https://github.com/jupyterhub/repo2docker), please see the documentation there for how to set up your repository for a successful build. The built Docker image name will be stored into `app_state.json` file in the state directory. This command requires the `init` step to have already been run.
### push_docker
This command will push a Docker image built by the `build_docker` step to a remote Docker registry. It will then record the remote registry URL into the state directory for use by subsequent steps. The `push_docker` command has a required argument of either the URL of a remote Docker registry or a Dockerhub username. It is assumed you have already used `docker login` to initialze credentials. This command requires the `build_docker` step to have already been run.
### build_cwl
The `build_cwl` will use [app-pack-generator](https://github.com/unity-sds/app-pack-generator) to create OGC compliant CWL files based on the parameterization of the Jupyter notebook in the target repository. Currently the Jupyter notebook is required to be named `process.ipynb`. Please see the [app-pack-generator](https://github.com/unity-sds/app-pack-generator) documentation for how to properly parameterize a notebook. The generated CWL files and application descriptor will be placed in the state directory. If the `push_docker ` step has not yet been run the CWL files will refer to the local Docker image tag instead a remote URL.
### push_app_registry
The `push_app_registry` command pushes the generated CWL into a Dockstore application registry server. It requires the the URL to the Dockstore API as well as a token obtained through the Dockstore interface. The `build_cwl` step is required to have already been executed.
```
usage: build_ogc_app push_app_registry [-h] --api_url DOCKSTORE_API_URL --token DOCKSTORE_TOKEN
options:
-h, --help show this help message and exit
--api_url DOCKSTORE_API_URL
Dockstore API URL including the trailing api/ portion of the URL
--token DOCKSTORE_TOKEN
Dockstore API token obtained from the My Services / Account page
```
The API URL can be obtained from the Dockstore user interface by scrolling to the bottom and clicking the API link in the footer. It will be the portion of the URL up to the `/api` path. The API token is obtained by logging into the Dockstore, clocking on the username drop down in the top right corner then selecting the Account item. Copy the token from the Dockstore Account item.
## Changelog
See our [CHANGELOG.md](CHANGELOG.md) for a history of our changes.
See our [releases page](https://github.com/unity-sds/unity-app-generator/releases) for our key versioned releases.
## License
See our: [LICENSE](LICENSE.txt)
Raw data
{
"_id": null,
"home_page": null,
"name": "mdps-app-generator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "unity-sds, ogc, packaging, cwl, jupyter",
"author": "James McDuffie",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/87/11/c3f3f8ba25d8e518eb117a7e1f98cca8b0cb29a6e062ce9b385c5672dfde/mdps_app_generator-1.0.0.tar.gz",
"platform": null,
"description": "<!-- Header block for project -->\n<hr>\n\n<div align=\"center\">\n\n\n\n<h1 align=\"center\">Unity Application Generator</h1>\n<!-- \u261d\ufe0f Replace with your repo name \u261d\ufe0f -->\n\n</div>\n\n<pre align=\"center\">Creates and registers a Unity OGC application package</pre>\n\n<!-- Header block for project -->\n\n[app-pack-generator](https://github.com/unity-sds/app-pack-generator) | [unity-example-application](https://github.com/unity-sds/unity-example-application)\n\n## Features\n\n* Uses [app-pack-generator](https://github.com/unity-sds/app-pack-generator) to create CWL, application descriptor and Docker image\n* Can output Jupyter noteboook parameterization for debugging purposes\n* Pushes generated Docker image to a Docker registry\n* Pushes generated application package files to a Dockstore application registry\n\n\n## Requirements\n\n* [app-pack-generator](https://github.com/unity-sds/app-pack-generator)\n* [Unity-py](https://pypi.org/project/unity-sds-client/)\n\n## Setup Instructions\n\n### Install from Github\n\n```\npip install git+https://github.com/unity-sds/unity-app-generator.git \n```\n\n### Install Locally\n\n```\ngit clone https://github.com/unity-sds/unity-app-generator.git\npip install unity-app-generator\n```\n\n## Usage\n\nUnity application generation is accomplished by using the `build_ogc_app` program. It uses a stateful architecture such as in other programs such as ``git`` where actions on a repository can be done in a series of steps. These steps are listed when running `build_ogc_app --help`.\n\n```\nusage: build_ogc_app [-h] [--state_directory STATE_DIRECTORY] {init,build_docker,push_docker,parameters,build_cwl,push_app_registry} ...\n\nUnity Application Package Generator\n\npositional arguments:\n {init,build_docker,push_docker,parameters,build_cwl,push_app_registry}\n init Initialize a Git repository for use by this application. Creates a .unity_app_gen directory in the destination directory\n build_docker Build a Docker image from the initialized application directory\n push_docker Push a Docker image from the initialized application directory to a remote registry\n parameters Display parsed notebook parameters\n build_cwl Create OGC compliant CWL files from the repository and Docker image\n push_app_registry Push CWL files to Dockstore application registry\n\noptions:\n -h, --help show this help message and exit\n --state_directory STATE_DIRECTORY\n An alternative location to store the application state other than .unity_app_gen\n```\n\nBy default a state directory name `.unity_app_gen` is created in the repository the tool is targeting. Usually this is within the repository directory itself unless the `--state_directory` argument is used. This directory contains metadata information and generated files created by steps and needed for subsequent steps.\n\n### init\n\nBefore using the tool with a repository the state directory needs to be initialized:\n\n```\nusage: build_ogc_app init [-h] [-c CHECKOUT] source_repository [destination_directory]\n\npositional arguments:\n source_repository Directory or Git URL of application source files, default is current directory\n destination_directory\n Directory where to check out source repository, default is a directory under the current subdirectory with same basename as the\n source_repository\n\noptions:\n -h, --help show this help message and exit\n -c CHECKOUT, --checkout CHECKOUT\n Git hash, tag or branch to checkout from the source repository\n```\n\nThis can be accomplished with an existing clone of a repository or the tool can clone the repository locally for you. If no directory is supplied the tool will assume you would like to initialize the current directory. When working interatively it is suggested to change to the directory you are working with and use the script from there. This simplifies program usage and does not require you to use the `--state_directory` argument on each call. \n\nFor example to initialize an repository and use it locally:\n\n```\ngit clone https://github.com/unity-sds/unity-example-application.git\ncd unity-example-application\nbuild_ogc_app init\n```\n\nOr to have the tool clone and initialize the repository for you:\n\n```\nbuild_ogc_app init https://github.com/unity-sds/unity-example-application.git unity-example-application\ncd unity-example-application\n```\n\n### build_docker\n\nThe `build_docker` command does not require any additional arguments. It will utilize [app-pack-generator](https://github.com/unity-sds/app-pack-generator) and [repo2docker](https://github.com/jupyterhub/repo2docker), please see the documentation there for how to set up your repository for a successful build. The built Docker image name will be stored into `app_state.json` file in the state directory. This command requires the `init` step to have already been run.\n\n### push_docker\n\nThis command will push a Docker image built by the `build_docker` step to a remote Docker registry. It will then record the remote registry URL into the state directory for use by subsequent steps. The `push_docker` command has a required argument of either the URL of a remote Docker registry or a Dockerhub username. It is assumed you have already used `docker login` to initialze credentials. This command requires the `build_docker` step to have already been run.\n\n### build_cwl\n\nThe `build_cwl` will use [app-pack-generator](https://github.com/unity-sds/app-pack-generator) to create OGC compliant CWL files based on the parameterization of the Jupyter notebook in the target repository. Currently the Jupyter notebook is required to be named `process.ipynb`. Please see the [app-pack-generator](https://github.com/unity-sds/app-pack-generator) documentation for how to properly parameterize a notebook. The generated CWL files and application descriptor will be placed in the state directory. If the `push_docker ` step has not yet been run the CWL files will refer to the local Docker image tag instead a remote URL.\n\n### push_app_registry\n\nThe `push_app_registry` command pushes the generated CWL into a Dockstore application registry server. It requires the the URL to the Dockstore API as well as a token obtained through the Dockstore interface. The `build_cwl` step is required to have already been executed.\n\n```\nusage: build_ogc_app push_app_registry [-h] --api_url DOCKSTORE_API_URL --token DOCKSTORE_TOKEN\n\noptions:\n -h, --help show this help message and exit\n --api_url DOCKSTORE_API_URL\n Dockstore API URL including the trailing api/ portion of the URL\n --token DOCKSTORE_TOKEN\n Dockstore API token obtained from the My Services / Account page\n```\n\nThe API URL can be obtained from the Dockstore user interface by scrolling to the bottom and clicking the API link in the footer. It will be the portion of the URL up to the `/api` path. The API token is obtained by logging into the Dockstore, clocking on the username drop down in the top right corner then selecting the Account item. Copy the token from the Dockstore Account item.\n\n## Changelog\n\nSee our [CHANGELOG.md](CHANGELOG.md) for a history of our changes.\n\nSee our [releases page](https://github.com/unity-sds/unity-app-generator/releases) for our key versioned releases.\n\n## License\n\nSee our: [LICENSE](LICENSE.txt)\n",
"bugtrack_url": null,
"license": "Apache License",
"summary": "Generates an OGC compliant Unity application package using the Unity app-pack-generator.",
"version": "1.0.0",
"project_urls": null,
"split_keywords": [
"unity-sds",
" ogc",
" packaging",
" cwl",
" jupyter"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5e5cf0c8e7389aca6ad930a6e736d501bebe1b175c914a9e175ddc8679a8b003",
"md5": "13c00569d3c879592bbb804df02c4e4a",
"sha256": "63dfc417db19fab313b455a5e5c303012044a55fb78f982a45a0d957bb858725"
},
"downloads": -1,
"filename": "mdps_app_generator-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "13c00569d3c879592bbb804df02c4e4a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 14507,
"upload_time": "2025-02-20T19:05:29",
"upload_time_iso_8601": "2025-02-20T19:05:29.324058Z",
"url": "https://files.pythonhosted.org/packages/5e/5c/f0c8e7389aca6ad930a6e736d501bebe1b175c914a9e175ddc8679a8b003/mdps_app_generator-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8711c3f3f8ba25d8e518eb117a7e1f98cca8b0cb29a6e062ce9b385c5672dfde",
"md5": "703004cae502afdb1f4e432f56bc05fc",
"sha256": "989b89c5099f12ce8d75576dbb56e679a2ef029d6d087d632350fc985ea33311"
},
"downloads": -1,
"filename": "mdps_app_generator-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "703004cae502afdb1f4e432f56bc05fc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 12812,
"upload_time": "2025-02-20T19:05:30",
"upload_time_iso_8601": "2025-02-20T19:05:30.835011Z",
"url": "https://files.pythonhosted.org/packages/87/11/c3f3f8ba25d8e518eb117a7e1f98cca8b0cb29a6e062ce9b385c5672dfde/mdps_app_generator-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-20 19:05:30",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mdps-app-generator"
}
JSON