clone-the-example-application-code.md

Clone the Example Application Code

This is an optional section that will let you practice editing an application before registering it with the Unity system. If you wish to skip this step, you may simply use the example application in the next step.

In order to create a new Application Package for the Tutorial, you first need to create a copy of the Tutorial application, which we will do by forking the Example Application. Then we can build and register your Application using the Unity tools, and view it in the Application Catalog (Dockstore).

Here is a handy reference to Github commands, in case you are not familiar with it, or don’t use it often: https://education.github.com/git-cheat-sheet-education.pdf

1. Go to the Github repository for the example application: Unity-Example-Application (https://github.com/unity-sds/unity-example-application)
2. Select “Fork” on the top right of the screen as shown in the figure below:

3. Make sure to fill in the “Owner” dropdown, “Repository name” field, “Description” field and check the “Copy the main branch only” as shown in the figure below:\

4. Select “Create fork” as shown in the figure below:\

   

5. Select “Code” and copy the https link as shown in the figure below:

6. Go to your JupyterHub session.
7. Select the + symbol on the top left corner, which represents the “Launcher”, and select “Terminal” from the Launcher tab as shown below.

8. From the Terminal: Clone the git repository using the https URL you copied from the Github interface (Step 5 above) as shown in the figure below:

• Ex: git clone https://github.com/unity-sds/unity-example-application.git

NOTE: You should see the cloned files in the Jupyter file browser as shown in the figure below. You can also see these files by going into the folder and listing in the Terminal (cd unity-example-application; ls) as shown in the figure below:

NOTE: Information about the files that are in the unity-example-application folder:

• execute_app_pack_gen.ipynb: this is a Jupyter notebook that runs Unity commands to prepare the demo application to run at scale on the Unity platform. It will package the demo application into an OGC Application Package.
• process.ipynb: this is the example application that executes when the App Package is run.
• requirements.txt: this contains a list of the libraries needed to run the example application; these are packaged into the App Package so that it has all the necessary dependencies. Each application will have a similar file so that the runtime environment is properly set up when running at scale in the SPS (Airflow).
• test/ogc_app/unity-tutorial-app.test.yml: this is an example input file for the tutorial application.

Optional Steps: Modify the Example Application Package

If you would like to edit the example application to better understand how the system works, you will need to do the following. Otherwise, skip to the next section: Submit the example application for building.

Follow the steps below:

1. From the Jupyter terminal: set the environment needed to execute the application as shown in the figure below

• Run the following command: pip install --user -r requirements.txt

2. Open process.ipynb by double-clicking the file in the Jupyter file browser as shown in the figure below. This is where you can make changes to the core algorithm.

3. Once you have made some changes, Commit them to the Git repository with the commands below.

• Note that in order to authenticate a push to Github, you will need to use your github.com username and your Personal Access Token (classic)—not your github password. See the help on github.com for more information (Managing your personal access tokens - GitHub Docs)
• In the Jupyter Terminal:
  • cd </path/to/your/unity-tutorial-application directory>
  • git add .
  • git commit -m "your_commit_message"
  • git push -u -f origin main

Now your changes are pushed into the Github repo, and are ready to be built into an Application Package.