add: basic example

.github/workflows/.docker.yaml

@@ -4,15 +4,15 @@ name: Create and publish a Docker image
 # Configures this workflow to run every time a change is pushed to the branch called `release`.
 on:
   push:
-    branches: "*"
+    branches: main
     tags:
       - "*"
   pull_request:
 
 # Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
 env:
   REGISTRY: ghcr.io
-  IMAGE_NAME: in-for-disaster-analytics/tap_{Template}repository-docker #change {Template}
+  IMAGE_NAME: in-for-disaster-analytics/cookbook-template-simple #change {Template}
 
 # There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
 jobs:
@@ -34,10 +34,11 @@ jobs:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
+
       # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
       - name: Extract metadata (tags, labels) for Docker
         id: meta
-        uses: docker/metadata-action@9ec57ed1fcdbf14dcef7dfbe97b2010124a938b7
+        uses: docker/metadata-action@v4
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
@@ -46,6 +47,7 @@ jobs:
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
             type=sha
+
       # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
       # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository.
       # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.

CITATION.cff

@@ -2,7 +2,7 @@
 # Visit https://bit.ly/cffinit to generate yours today!
 
 cff-version: 1.2.0
-title: Cookbook Template repository for Conda environments
+title: Cookbook-Tutorial-Template
 message: >-
   If you use this software, please cite it using the
   metadata from this file.
@@ -24,5 +24,5 @@ authors:
     affiliation: Texas Advanced Computing Center
     orcid: 'https://orcid.org/0000-0002-3050-1987'
 repository-code: >-
-  https://github.com/In-For-Disaster-Analytics/Cookbook-Docker-Template
+  https://github.com/In-For-Disaster-Analytics/Cookbook-Tutorial-Template
 license: Apache-1.0

Dockerfile

@@ -1,72 +1,7 @@
-FROM nvidia/cuda:12.3.0-runtime-ubuntu22.04
+FROM debian:bullseye-slim
 
-LABEL maintainer="TACC-ACI-WMA <[email protected]>"
+COPY run.sh /bin/run.sh
 
-USER root
+RUN chmod +x /bin/run.sh
 
-EXPOSE 8888
-
-ENV DEBIAN_FRONTEND noninteractive
-
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    ca-certificates \
-    curl \
-    fonts-liberation \
-    git \
-    locales \
-    pandoc \
-    python3 \
-    python3-pip \
-    ssh \
-    wget \
-    unzip \
-    vim \
-    rsync \
-    && apt-get clean && rm -rf /var/lib/apt/lists/* && \
-    echo "en_US.UTF-8 UTF-8" > /etc/locale.gen && \
-    locale-gen
-
-RUN pip install --upgrade --no-cache-dir \
-    pip \
-    setuptools \
-    wheel
-
-# Install jupyterlab and ML packages using host cache
-RUN pip install --no-cache-dir\
-    jupyterlab \
-    tensorflow[and-cuda] \
-    torch
-
-# Add container user and group
-ARG NB_USER=jovyan
-ARG NB_UID=1000
-ARG NB_GID=100
-
-# Configure environment
-ENV SHELL=/bin/bash \
-    NB_USER="${NB_USER}" \
-    NB_UID=${NB_UID} \
-    NB_GID=${NB_GID} \
-    NB_HOME="/home/${NB_USER}" \
-    LC_ALL=en_US.UTF-8 \
-    LANG=en_US.UTF-8 \
-    LANGUAGE=en_US.UTF-8
-
-# Enable prompt color in the skeleton .bashrc before creating the default NB_USER
-RUN sed -i 's/^#force_color_prompt=yes/force_color_prompt=yes/' /etc/skel/.bashrc
-
-# Create NB_USER with UID=NB_UID and GID=NB_GID
-RUN useradd --no-log-init --create-home --shell /bin/bash --uid "${NB_UID}" --gid "${NB_GID}" "${NB_USER}"
-
-COPY run.sh /tapis/run.sh
-
-RUN chmod +x /tapis/run.sh
-
-USER ${NB_UID}
-
-# Setup work directory
-RUN mkdir "${NB_HOME}/work"
-
-WORKDIR "${NB_HOME}"
-
-ENTRYPOINT [ "/tapis/run.sh" ]
+ENTRYPOINT [ "run.sh" ]

README.md

@@ -1,55 +1,37 @@
-# Cookbook repository for Conda environments
+This is the template for a cookbooks' tutorial. The goal is to provide an environment that can be reproducible and stood up on TACC Systems.
 
-This repository contains the files needed to build a Docker image with a Conda environment for running the Tapis apps.
+## Tutorial
 
-This Docker image is specifically configured to install a singular Conda environment, based on the contents of a Git repository. The repository must contain a `./binder/environment.yml` file with the Conda environment definition, and optionally a `./binder/requirements.txt` file with additional Python dependencies.
+In this tutorial, we will create a cookbook that will be used to demonstrate how run a command on TACC cluster and obtain the output.
 
-## Installation process
+### Create a new Github Repository
 
-When the job is submitted, the Tapis platform will pull the Docker image and run the container. The container will run the `run.sh` script, which will activate the Conda environment and run the app.
+1. Go to [Cookbook-Tutorial-Template](https://github.com/In-For-Disaster-Analytics/Cookbook-Tutorial-Template)
+2. Click on the "Use this template" button
+3. Name your repository and click "Create repository"
 
-## Important Variables
+### Update the Cookbook definition `app.json` file
 
-- `GIT_REPO_URL`: URL of the cookbook repository to use.
-- `GIT_BRANCH`: Branch of the cookbook repository to use.
-- `COOKBOOK_NAME`: Name of the cookbook, used for naming the directory
-- `COOKBOOK_WORKSPACE_DIR`: This is the designated directory for cloning the cookbook repository. If the directory already exists, the script does not perform an update. This directory serves as the active working directory during the Jupyter session, allowing direct interaction with the contents.
-- `COOKBOOK_REPOSITORY_DIR`: This directory is also used for cloning the cookbook repository. However, in contrast to `COOKBOOK_WORKSPACE_DIR`, if it already exists, the script updates the repository to ensure it contains the most recent changes. This directory is maintained as a hidden area, primarily utilized for update checks and not intended for direct user interaction.
-- `COOKBOOK_CONDA_ENV`: Name of the Conda environment to use.
+A Tapis application represents all the information required to run a Tapis job on a Tapis system. The `app.json` file is the definition of the Tapis application such as application's name, description, and the environment that the application will run in.
 
-## Execution
+1. Open the `app.json` file in the root of your repository
+2. Update the `id` and `description` fields with the name and description of your cookbook
 
-1. `install_conda`: Checks if Miniconda is installed in a specified directory (`$WORK/miniconda3`). If not installed, it downloads and installs Miniconda, configures the `PATH`, and sets Conda to not automatically activate the base environment on startup.
-2. `load_cuda`: Loads the CUDA module, version 12.0
-3. `export_repo_variables`: Sets and exports various environment variables related to a Git repository, its environment. Set up the repository and branch to use, and the environment name.
-4. `clone_repository`:
-   6.1 Clones the Git repository specified in `GIT_REPO` and `GIT_BRANCH` into the directory specified in `COOKBOOK_WORKSPACE_DIR`. If the directory exists, it doesn't clone the repository or update it.
-   6.2. Clone the Git repository specified in `GIT_REPO` and `GIT_BRANCH` into the directory specified in `COOKBOOK_REPOSITORY_DIR`. If the directory exists, it updates the repository.
-5. `load_tap_functions`: Loads TACC's specific functions for job management.
-6. `get_tap_certificate`: Ensures a TLS certificate exists for a secure session.
-7. `get_tap_token`: Generates a token for a Jupyter session and retrieves a port for login.
-8. `create_jupyter_configuration`: Creates a configuration file for a JupyterLab session, including SSL options and kernel settings.
-9. `run_jupyter`: Starts JupyterLab and logs its output. It retries once if the first attempt fails.
-10. `port_fowarding`: Sets up SSH tunneling for port forwarding, allowing external access to the JupyterLab session.
-11. `send_url_to_webhook`: Sends the JupyterLab session URL to a webhook, presumably to notify users that the session is ready.
-12. `session_cleanup`: Monitors a file (`delete_me_to_end_session`) and ends the Jupyter session when this file is deleted.
-13. `install_dependencies`: Creates or activates a Conda environment specified in the Git repository and installs necessary Python dependencies.
+### Create a new application on the Cookbook UI
 
-## Auxiliary Functions
+1. Go to [Cookbook UI](https://in-for-disaster-analytics.github.io/cookbooks-ui/#/apps)
+2. Click on the "Create Application" button
+3. Fill in the form with the information from your `app.json` file
+4. Click "Create Application"
 
-1. `detect_update_available`: Checks if there's an update available for the Git branch specified in `GIT_BRANCH`. If there is, it creates or updates a file indicating this.
-2. `remove_update_available_file`: Deletes a `UPDATE_AVAILABLE.txt` which indicates an available update if it exists.
+### Test your Cookbook
 
-## Files
+1. Go to the [Cookbook UI](https://in-for-disaster-analytics.github.io/cookbooks-ui/#/apps)
+2. Click on your cookbook
+3. Click on the "Run" button on the right side of the page. This will open the Portal UI
+4. Fill in the form with the necessary parameters
+5. Click "Run"
 
-Production files:
+## Authors
 
-- `app.json` Tapis app definition file.
-- `Dockerfile`: Dockerfile for building the image prepared to use GPUs.
-- `run.sh` Script to run in the container.
-
-Development files:
-
-- `cpu/Dockerfile.cpu`: Dockerfile for building the image prepared to use CPUs.
-- `run.sh` Script to run in the container.
-- `app-dev.json` Tapis app definition file for development.
+William Mobley - [email protected]