From 7519039765ae5807346ffd45c0cea4feebd57d40 Mon Sep 17 00:00:00 2001 From: Maximiliano Osorio Date: Tue, 28 May 2024 15:43:47 -0400 Subject: [PATCH] fix: improve readme --- README.md | 78 +++++++++++++++++++++++++++++++++++++++++++------------ run.sh | 6 ----- 2 files changed, 62 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 40ff2e6..1851e2a 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -This tutorial is the first in a [series of tutorials](#next-tutorials) that will guide you through the process of creating a cookbook and running it on TACC systems. From simple ones that run a command to more complex ones that run a Python using conda or a Jupyter Notebook. +This template is the first in a [series of tutorials](#next-tutorials) that will guide you through the process of creating a cookbook and running it on TACC systems. From simple ones that run a command to more complex ones that run a Python using conda or a Jupyter Notebook. ## Requirements @@ -8,11 +8,9 @@ This tutorial is the first in a [series of tutorials](#next-tutorials) that will - You can see your allocations [here](https://ptdatax.tacc.utexas.edu/workbench/allocations/approved) - If you don't have an allocation, you can request one [here](https://portal.tacc.utexas.edu/allocation-request) -## Tutorial +## Template Overview -In this tutorial, we will create a simple cookbook that will be used to demonstrate how to run a cookbook a TACC cluster and obtain the output using a UI. - -This cookbook will run the job using two parameters/arguments `Greeting` and `Target` and save the output to a file named `out.txt`. +This template creates a simple cookbook that will run a job on a TACC cluster using two parameters/arguments, Greeting and Target, and obtain the output via a UI, saving it to a file named out.txt. ![alt text](images/parameters.png) @@ -20,16 +18,62 @@ This cookbook will run the job using two parameters/arguments `Greeting` and `Ta ### How does it work? -1. The [`app.json`](app.json) file contains the definition of the Tapis application, including the application's name, description, Docker image, parameters and advanced options. -2. The Docker image defines the runtime environment for the application. Also, it includes `run.sh` file that contains the commands that will be executed by the Tapis job. A Docker Image is built from the [`Dockerfile` file](./Dockerfile). -3. The file [`run.sh`](run.sh) contains all the commands that will be executed by the Tapis job. +1. [`app.json`](app.json) file: contains the definition of the Tapis application, including the application's name, description, Docker image, input files, and advanced options. +2. [`Dockerfile`](Dockerfile): a Docker image is built from the [`Dockerfile`](./Dockerfile). The Docker image defines the runtime environment for the application and the files that will be used by the application. +3. [`run.sh`](run.sh): contains all the commands that will be executed on the TACC cluster. + +### Job run script + +The `run.sh` file is used to run the commands. + +```bash +#!/bin/bash + +Greeting=$1 +Target=$2 + +FULL_GREETING="${Greeting} ${Target}. My name is ${_tapisJobOwner}" +echo "$FULL_GREETING" + +echo $FULL_GREETING > $_tapisExecSystemOutputDir/out.txt +``` + +The `run.sh` script receives two parameters, `Greeting` and `Target`, and uses them to create a message that will be saved to a file named `out.txt`. + +Also, the script uses the `_tapisExecSystemOutputDir` variable, which contains the path where the application writes the output files. + +## Create your Cookbook + +### Create a new repository + +1. Click on the "Use this template" button to create a new repository +2. Fill in the form with the information for your new repository + +### Build the Docker image + +You can skip this step if you don't want to build the Docker image yourself. You can use the Docker image from the [Docker Hub](https://hub.docker.com/r/taccaci/cookbook-python). + +1. Clone the repository +2. Build the Docker image using the command below + +```bash +docker build -t cookbook-python . +``` + +3. Push the Docker image to a container registry + +```bash +docker tag cookbook-python /cookbook-python +docker push /cookbook-python +``` -### 1. Update the Cookbook Definition `app.json` File +### Modify the `app.json` file Each app has a unique `id` and `description`. So, you should change these fields to match your app's name and description. 1. Download the `app.json` file 2. Change the values `id` and `description` fields with the name and description as you wish. +3. If you built the Docker image, change the `containerImage` field with the image name you used. ### Create a New Application on the Cookbook UI @@ -39,11 +83,12 @@ Each app has a unique `id` and `description`. So, you should change these fields 4. Click "Create Application" 5. A new application will be created, and you will be redirected to the application's page -### Run Your Cookbook +### Run your Cookbook -1. Click on the "Run" button on the right side of the page. This will open the Portal UI -2. Fill in the form with the necessary parameters -3. Click "Run" +1. Go to the application's page on the Cookbook UI, if you are not already there +2. Click on the "Run" button on the right side of the page. This will open the Portal UI +3. Select the parameters for your job + ![Select the parameters](images/parameters.png) ### Check the Output @@ -54,10 +99,11 @@ Each app has a unique `id` and `description`. So, you should change these fields 3. Click on a file to see its content. In this case, the file is named `out.txt` ![Show the output content ](images/output-content.png) -## Next Tutorials +## Next templates -- [Running a Python script] -- [Running a Jupyter Notebook] +- [Running a command](https://github.com/In-For-Disaster-Analytics/Cookbook-Docker-Template) +- [Running a Python script using conda](https://github.com/In-For-Disaster-Analytics/Cookbook-Conda-Template) +- [Running a Jupyter Notebook](https://github.com/In-For-Disaster-Analytics/Cookbook-Jupyter-Template) ## Authors diff --git a/run.sh b/run.sh index 36e9f07..8d69981 100644 --- a/run.sh +++ b/run.sh @@ -1,15 +1,9 @@ #!/bin/bash -echo "Your command line args (appArgs) are: $@" - Greeting=$1 Target=$2 FULL_GREETING="${Greeting} ${Target}. My name is ${_tapisJobOwner}" echo "$FULL_GREETING" -echo `pwd` -echo ${_tapisJobWorkingDir} - -fileToModify=$_tapisExecSystemInputDir/in.txt echo $FULL_GREETING > $_tapisExecSystemOutputDir/out.txt \ No newline at end of file