adding tutorial for adding app and deploying

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 <app specific string>*, replacing *<app specific string>* 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...

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 [email protected]: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

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

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'