cicd-with-nic5.md

@@ -2,6 +2,7 @@
 title: Configuring a standard experiment for NIC5
 ---
 
+
 Thanks to GitLab CI/CD features and thanks to [Jacamar CI](https://ecp-ci.gitlab.io/docs/admin/jacamar/introduction.html), you can configure a standard experiment for BAMHBI to run on a cluster which you will be able to kickstart from ULiège GitLab with a simple click. For the time being, all CI/CD experiments of the MAST will be run on the NIC5 cluster, notably to benefit from the many MAST resources already stored on NIC5.
 
 This tutorial details the requirements you should meet beforehand, for both security and storage concerns, then how you can write a suitable CI/CD configuration to create your experiment.
@@ -227,10 +228,52 @@ lr_nic5_run:
     expire_in: 1 week
 ```
 
-Finally, it's worth noting you can absolutely mix NIC5 jobs with jobs running on GitLab. You can find again an example in the [Nemo4.2.0-Bamhbi CI/CD configuration](https://gitlab.uliege.be/especes/mast/nemo4.2.0-bamhbi/-/blob/main/.gitlab-ci.yml), where the outputs from the NIC5 job running the simulation are sent to a containerized job running Python code to produce various figures to assess the model. The obvious constraint of this approach is that the inputs of the GitLab job must be entirely contained in the artifacts of the NIC5 job, as the GitLab job will not have access to the NIC5 environment.
+Finally, it's worth noting you can absolutely mix NIC5 jobs with jobs running on GitLab. You can find again an example in the [Nemo4.2.0-Bamhbi CI/CD configuration](https://gitlab.uliege.be/especes/mast/nemo4.2.0-bamhbi/-/blob/main/.gitlab-ci.yml), where the outputs from the NIC5 job running the simulation are sent to a containerized job running Python code to produce various figures to assess the model (see also next section). The obvious constraint of this approach is that the inputs of the GitLab job must be entirely contained in the artifacts of the NIC5 job, as the GitLab job will not have access to the NIC5 environment.
+
+## Using the Toolbox at the end of the pipeline
+
+You can use the [Toolbox](https://gitlab.uliege.be/especes/mast/toolbox) to assess model outputs at the end of a pipeline. For this purpose, you will need to use a suitable environment, featuring Python and the relevant packages, and to clone the [Toolbox repository](https://gitlab.uliege.be/especes/mast/toolbox) within the environment.
+
+To use a compatible environment, you may define a job using the ``jefgrailet/especes:model-assess`` Docker image available on Docker Hub, with the usual syntax. The next job excerpt defines such a job, whose prerequisite is a ``lr_nic5_run`` job (which may be identical, or pretty close to the example job given in [More elaborate pipelines](cicd-with-nic5#more-elaborate-pipelines)).
+
+```
+lr_nic5_assess:
+  stage: assess
+  image: jefgrailet/especes:model-assess
+  needs:
+    - lr_nic5_run
+```
+
+Once you have a suitable environment, the main technical hurdle in using the [Toolbox](https://gitlab.uliege.be/especes/mast/toolbox) is to have its code available in said environment. A simple solution would be to download it from some location online (e.g., a FTP server), as both ``wget`` and ``curl`` can be used in the ``jefgrailet/especes:model-assess`` environment, but this solution has the obvious problem of having to refresh the code available for download at every update. A better option is then to use the ``git clone`` command to locally clone the [Toolbox repository](https://gitlab.uliege.be/especes/mast/toolbox) and move its code at the location where you it to be.
+
+However, since this repository is not public (for the time being), you need to use an access token to be able to clone it. Moreover, such access token cannot be stored "as is" in the repository, as it could constitute a vulnerability from a security point of view. GitLab does provide the option to store _secret files_, files that cannot be read while browsing the Web interface of GitLab, but which can be copied during a CI/CD job. Such files are listed in **Settings > CI/CD > Secure files** on a repository. **For now, please contact me (@Jean-Francois.Grailet) to create such files.**
+
+To copy a secure file, such as ``Token_Toolbox.txt`` on the Nemo4.2.0-Bamhbi repository, you have to start the ``script:`` part of your job with a very specific line, the last one in the next excerpt.
+
+```
+lr_nic5_assess:
+  stage: assess
+  image: jefgrailet/especes:model-assess
+  needs:
+    - lr_nic5_run
+  variables:
+    SECURE_FILES_DOWNLOAD_PATH: 'test_cases/lr_cluster/scripts/'
+  script:
+    - curl --silent "https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/download-secure-files/-/raw/main/installer" | bash
+```
+
+Note the ``SECURE_FILES_DOWNLOAD_PATH``. This is the place where the secure file will be copied. Then, during the script used by the job, one can use the next commands to clone the [Toolbox](https://gitlab.uliege.be/especes/mast/toolbox).
+
+```
+cp test_cases/lr_cluster/scripts/Token_Toolbox.txt /home/
+cd /home
+git clone https://cicd:$(cat ./Token_Toolbox.txt)@gitlab.uliege.be/especes/mast/toolbox.git
+```
+
+Very similar instructions can be found in [this file from the Nemo4.2.0-Bamhbi repository](https://gitlab.uliege.be/especes/mast/nemo4.2.0-bamhbi/-/blob/main/test_cases/lr_cluster/scripts/lr_nic5_assess.sh).
 
 ## And then, we push the button
 
 Once you have configured your CI/CD pipeline for NIC5, and if you used the ``when: manual`` keyword as recommended, all you have to do next is to literally push the button in the pipeline display, which you may access from the root of the repository (by clicking the CI/CD icon), or by accessing the latest pipeline in **Build > Pipelines**. Do not hesitate to take example on the [Nemo4.2.0-Bamhbi CI/CD configuration](https://gitlab.uliege.be/especes/mast/nemo4.2.0-bamhbi/-/blob/main/.gitlab-ci.yml) to write your own for NIC5 !
 
-<img src="uploads/a5edb8364709399ded6dd4097e9e4a74/nic5_manual_pipeline.png" alt="nic5_manual_pipeline" width="900"/>
\ No newline at end of file
+<img src="uploads/bbfda5c33331c32423e0e4f5bfb6d44d/nic5_manual_pipeline.png" alt="nic5_manual_pipeline" width="900"/>
\ No newline at end of file