From 8aa9b4def79e05f8ae253981894258f943eeda63 Mon Sep 17 00:00:00 2001 From: Chris Scott Date: Tue, 30 Apr 2024 08:57:57 +1200 Subject: [PATCH] adding tutorial for adding app and deploying --- docs/tutorials/adding-new-app.md | 94 ++++++++++++++++++ docs/tutorials/deployment-on-nesi.md | 96 +++++++++++++++++++ ...r-intermediate-shell-for-bioinformatics.md | 3 + mkdocs.yml | 4 + 4 files changed, 197 insertions(+) create mode 100644 docs/tutorials/adding-new-app.md create mode 100644 docs/tutorials/deployment-on-nesi.md diff --git a/docs/tutorials/adding-new-app.md b/docs/tutorials/adding-new-app.md new file mode 100644 index 0000000..f543ad9 --- /dev/null +++ b/docs/tutorials/adding-new-app.md @@ -0,0 +1,94 @@ +# Adding a new app + +## Overview + +The suggested approach is to copy the existing app that most closely resembles your new app and modify that, we will document this approach here. +Some of the existing apps are: + +- [Apptainer workshop app](https://github.com/nesi/training-environment-jupyter-containers-app) + - based on JupyterLab +- [Intermediate shell workshop app](https://github.com/nesi/training-environment-jupyter-intermediate-shell-app) + - based on JupyterLab + - there is a [tutorial](jupyterlab-app-for-intermediate-shell-for-bioinformatics.md) for this app +- [Jupyter ML101 app](https://github.com/nesi/training-environment-jupyter-ml101-app) + - based on JupyterLab + - uses Miniconda to install dependencies +- [Jupyter ML102 app](https://github.com/nesi/training-environment-jupyter-ml102-app) + - based on JupyterLab + - uses Python virtualenv and pip to install dependencies +- [RStudio RNA-Seq app](https://github.com/nesi/training-environment-rstudio-rnaseq-app) + - based on RStudio + - includes data files in the docker image + - uses Miniconda to install some dependencies such as `samtools` and `fastqc` + - uses `BiocManager` and `install.packages` to install R dependencies +- [RStudio scRNA-Seq app](https://github.com/nesi/training-environment-rstudio-scrnaseq-app) +- [RStudio intro and intermediate R app](https://github.com/nesi/training-environment-rstudio-app) + +## What needs to be changed + +Here we summarise what is most likely to need to be changed when copying an existing app. +Assuming the app your are copying is based on the same web application (i.e. JupyterLab vs RStudio, etc.) then not much should need to change. + +- *view.html.erb* + - change the line that contains the string *Connect to *, replacing ** with something specific to your app +- *manifest.yml* + - change the `name` and `description` +- *form.yml* + - adjust `cpu`, `memory`, `wall_time` if needed (can also add/remove any options) +- *submit.yml.erb* + - change `script.native.container.name` to something unique for your app + - change `script.native.container.image` to the image that will be built for your app - this should look like your github repo name and include a label/version (you will need to create a git tag for the version you put here) +- *script/template.sh.erb* + - copy any data in your image before launching the app, e.g. using something like + ``` + rsync --ignore-existing -avz /path/in/docker/image/to/data/ ~/data/ + ``` +- *docker/Dockerfile* + - add additional packages and install steps (generally not a good idea to remove packages unless you know what you are doing) + - add any required data + +!!! info "Note about naming your git repo" + + When you copy an existing app repo you should take care when naming your new repository - make sure you do not use underscores - use hyphens instead as github packages do not support package names with underscores and the default github action we include uses the repository name for the package name + +## Creating a tag/release of your new app + +In order to deploy your app in the training environment we are going to tag a version/release of it, using git tags. + +1. Update the version label in `script.native.container.image` in *submit.yml.erb* to reflect the new version you are about to create, commit that file. For example, here we are going to release version "v0.2.2": `image: "ghcr.io/nesi/training-environment-rstudio-rnaseq-app:v0.2.2"` +2. Create a tag with that specific version, e.g. `git tag -a v0.2.2 -m "my new release"` +3. Push the tags, e.g. `git push --tags` +4. This should trigger a build of the docker image, check the "Actions" tab of your GitHub repo and wait for it to complete successfully + +## Adding your app to the training environment + +To add you app to the training environment you need to modify the [training-environment repo](https://github.com/nesi/training-environment), specifically the file *vars/ondemand-config.yml.example*: + +1. Identify the `ood_apps` section in the file *vars/ondemand-config.yml.example* +2. This section consists of a number of blocks, one for each app, so add a new block for your new app: + ```yaml + rstudio_rnaseq: + k8s_container: ghcr.io/nesi/training-environment-rstudio-rnaseq-app:v0.2.2 + repo: https://github.com/nesi/training-environment-rstudio-rnaseq-app.git + version: 'v0.2.2' + enabled: true + pre_pull: false + ``` +3. Next time you build the environment the new app should be included + +More detail on the keys above follows: + +- `rstudio_rnaseq` should be set to a unique value in the `ood_apps` block +- `k8s_container` must point to the docker image for your app, tagged with the specific version (the git tag you created above) +- `repo` the github repo for your app +- `version` should be the git tag you created above +- `enabled: true` so that your app shows up in ondemand +- `pre_pull: false` is a good default and can be changed to `true` when you are using that app in a training + +!!! note "Releasing a new version of your app" + + When you release a new version of your app you need to update both the `k8s_container` and `version` values with the new version of your app + +## Developing + +When developing it can be useful... diff --git a/docs/tutorials/deployment-on-nesi.md b/docs/tutorials/deployment-on-nesi.md new file mode 100644 index 0000000..169c020 --- /dev/null +++ b/docs/tutorials/deployment-on-nesi.md @@ -0,0 +1,96 @@ +# Deployment a training environment + +Here we document the process for deploying a training environment on the NeSI Flexi HPC platform. + +Details of how we have set up the project on Flexi HPC, the github repo, etc. are not covered here. + +## Clone the git repo + +Clone the repo if you don't already have it, e.g. using SSH: + +``` +git clone git@github.com:nesi/training-environment.git +cd training-environment +``` + +If you have already cloned the repo, make sure you commit or stash any local changes. +It is also a good idea to start from the *main* branch to pick up the latest changes. + +``` +git stash +git checkout main +``` + +## Configure the deployment + +Create a new branch. The branch name will used in the URL for the training environment, so pick something short and relevant to the workshop (no special characters, etc.). For example, *ml101*, *introtor*, etc. + +``` +git checkout -b my-test-env +``` + +We need to edit two files to configure the environment: + +### Edit *vars/ondemand-config.yml.example* + +- adjust `num_users_create` and `num_trainers_create` +- adjust `ood_apps` as required + - check `version` and `k8s_container` + - enable required apps (usually just leave them all enabled, except for containers) + - set which images to pre-pull (just choose the one you will be using, we have limited space currently on the worker nodes and pre-pulling will fail if you exhaust it) +- set `enable_pod_prepull` to "true" + - sometimes we have experienced really slow image pulls, this will pre-pull the image and cache it so it is fast to start + - only pre-pull the app you are actually going to use, don't pre-pull them all as there might not be enough disk space on the worker nodes +- set `control_plane_flavor` + - usually to `balanced1.4cpu8ram` for production + - `balanced1.2cpu4ram` is good for testing +- set `cluster_worker_count` and `worker_flavor` to have enough capacity for the number of users, e.g. + - `cluster_worker_count: 2` and `worker_flavor: balanced1.32cpu64ram` for up to 30 *2cpu4ram* sessions + - `cluster_worker_count: 3` and `worker_flavor: balanced1.32cpu64ram` for up to 45 *2cpu4ram* sessions + +### Edit *terraform/terraform.tfvars* + +- adjust `services_flavor_id` + - `e07cfee1-43af-4bf6-baac-3bdf7c1b88f8` *4cpu8ram* (usually used for testing) + - `2d02e6a4-3937-4ed3-951a-8e27867ff53e` *8cpu16ram* (usually used for production, should be good for around 40-50 users, haven't tested past that) + - `674fa81a-69c7-4bf7-b3a9-59989fb63618` *16cpu32ram* +- adjust `services_volume_size`, must be big enough for all the user home directories plus some extra room +- adjust `webnode_flavor_id` + - `e07cfee1-43af-4bf6-baac-3bdf7c1b88f8` *4cpu8ram* (usually used for testing) + - `2d02e6a4-3937-4ed3-951a-8e27867ff53e` *8cpu16ram* (usually used for production, should be good for around 40-50 users, haven't tested past that) + - `674fa81a-69c7-4bf7-b3a9-59989fb63618` *16cpu32ram* +- adjust `webnode_volume_size`, usually leave at 30 GB + +### Commit the changes + +Commit and push the changes to your branch, e.g. + +``` +git add terraform/terraform.tfvars vars/ondemand-config.yml.example +git commit -m "configuring environment for XXX workshop" +git push -u origin my-test-env +``` + +## Deploy the environment + +**This will change** + +Deployments are currently done via manually triggered GitHub actions. + +!!! important "Check there are enough resources" + + Before running a new deployment, let others know what you are planning via Slack to ensure there are enough resources in the training project + +1. Navigate to the deploy environment workflow [here](https://github.com/nesi/training-environment/actions/workflows/deploy.yml) +2. Under *Run workflow* select **your branch** (make sure you get the correct branch) and click "Run workflow" + +## Destroy the environment + +To destroy your environment after you have finished using it: + +1. Navigate to the destroy environment workflow [here](https://github.com/nesi/training-environment/actions/workflows/destroy.yml) +2. Under *Run workflow* select **your branch** (make sure you get the correct branch) and click "Run workflow" + +!!! important + + Double check that you have selected the correct branch diff --git a/docs/tutorials/jupyterlab-app-for-intermediate-shell-for-bioinformatics.md b/docs/tutorials/jupyterlab-app-for-intermediate-shell-for-bioinformatics.md index ff4614f..6392b18 100644 --- a/docs/tutorials/jupyterlab-app-for-intermediate-shell-for-bioinformatics.md +++ b/docs/tutorials/jupyterlab-app-for-intermediate-shell-for-bioinformatics.md @@ -21,6 +21,9 @@ The layout of the app looks like: ``` intermediate-shell-app +├── .github +│   └── workflows +│   └── build_container.yml ├── docker │   └── Dockerfile ├── form.yml diff --git a/mkdocs.yml b/mkdocs.yml index 019080a..58dfe61 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,6 +2,9 @@ site_name: NeSI Training Environment markdown_extensions: - admonition + - def_list + - pymdownx.tasklist: + custom_checkbox: true - pymdownx.highlight: anchor_linenums: true line_spans: __span @@ -13,6 +16,7 @@ markdown_extensions: nav: - Overview: 'index.md' - Tutorials: + - "Adding a new app": "tutorials/adding-new-app.md" - "JupyterLab app for Intermediate Shell for Bioinformatics": "tutorials/jupyterlab-app-for-intermediate-shell-for-bioinformatics.md" - Apps: - Overview: 'apps/index.md'