diff --git a/README.md b/README.md index df0495a25d2698d43d00cb053e017bf9e68f9fd1..a031c53ff3a1c07d829a29db6de2680ba3d410d5 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,143 @@ -# Batch Connect - OSC MATLAB +# FSL Sandbox App on Cheaha Open OnDemand - -[](https://opensource.org/licenses/MIT) - -A Batch Connect app designed for OSC OnDemand that launches MATLAB within an -Owens batch job. +This readme provides a guide for setting up FSL as a stand-alone Sandbox app, that you can use on a HPC Desktop Job. ## Prerequisites -This Batch Connect app requires the following software be installed on the -**compute nodes** that the batch job is intended to run on (**NOT** the -OnDemand node): +Sandbox must be set up for your account on Cheaha, you can do this by following the guide we have in our documentations page for Cheaha on setting up [Sandbox Apps](https://docs.rc.uab.edu). Setting up Sandbox for your Cheaha account is a one-time step. + +### Steps to Setup FSL + +These steps show you how to setup the FSL (FMRIB Software Library) Sandbox App on Cheaha. + +1. Under the "Develop" tab , click on "My SandBox Apps (Development)" + +  + +1. Clicking the "New App" button should direct you to a new page giving you an option to Clone an Existing App. + +  + + <!-- markdownlint-disable MD046 --> + !!! note + + You can ignore the message "No SSH key was found. You will need to generate a locally installed SSH key to clone the git repo using SSH" since you can clone the repo using https. The warning would apply if you would like to clone the repo using SSH's authentication. + <!-- markdownlint-enable MD046 --> + +1. Now import the already existing git repo for an app by clicking on the "Clone Existing App". A form (shown below) requiring your input will display. For the FSL App we will use a template we already created (you can use this template to prepare your app as well). + +  + + We will add the following values in the form: + + - **Directory Name:** FSL + + - **Git Remote:** `https://gitlab.rc.uab.edu/rc/bc_uab_igv.git` + + After completing the above steps, then click "**Submit**" + +1. When this is done successfully, you should see the below screen also showing your new FSL Sandbox App. +  + + <!-- markdownlint-disable MD046 --> + !!! note + + You can also check the option "Create a new Git Project from this?", about creating a new git repo, if you want to use it to maintain your own instance of the app. In this tutorial, we will not be selecting this option. + <!-- markdownlint-enable MD046 --> + +1. Click on "Files" to take a look at the app files (local git repo working directory) you just cloned. We will modify some of the files here, because its contents are not relevant to FSL. + +  + + 1. We first modify "manifest.yml" file (highlight the file, and click on edit) to change metadata for the sandbox app. + Change the variables appropriately. In this case we will change the following: + +  + + 1. Next, select "form.yml.erb" and click on "Edit" . Replace the content of this file with the .yml file below. + + ``` yaml + + <%- + partitions = OodAppkit.clusters[:SLURM_CLUSTER].custom_config[:partitions] + -%> + --- + cluster: "SLURM_CLUSTER" + attributes: + bc_num_hours: + value: 1 + + bc_num_slots: + widget: "number_field" + label: Number of CPU + value: 1 + min: 1 + max: 24 + step: 1 -- [MATLAB] R2016b+ -- [Xfce Desktop] 4+ + bc_num_mems: + widget: "number_field" + label: Memory per CPU (GB) + value: 4 + min: 1 + max: 128 + step: 1 -For VNC server support: + bc_num_gpus: + widget: "number_field" + label: Number of GPUs + value: 1 + min: 0 + max: 4 + step: 1 -- [TurboVNC] 2.1+ -- [websockify] 0.8.0+ + bc_partition: + widget: select + label: Partition + options: + <%- partitions.each do |p| -%> + - [ "<%= p %>", "<%= p %>" ] + <%- end -%> -For hardware rendering support: + version: + widget: select + label: "FSL version" + help: "This defines the version of FSL you want to load." + options: + - [ "6.0.3", "FSL/6.0.3" ] -- [X server] -- [VirtualGL] 2.3+ + form: + - version + - bc_num_hours + - bc_partition + - bc_num_gpus + - bc_num_slots + - bc_num_mems + - bc_email_on_started -**Optional** software: + ``` -- [Lmod] 6.0.1+ or any other `module purge` and `module load <modules>` based - CLI used to load appropriate environments within the batch job + Here we are specifying what the form for the app is going to look like, and changing relevant parameters for Cheaha. -[MATLAB]: https://www.mathworks.com/ -[Xfce Desktop]: https://xfce.org/ -[TurboVNC]: http://www.turbovnc.org/ -[websockify]: https://github.com/novnc/websockify -[X server]: https://www.x.org/ -[VirtualGL]: http://www.virtualgl.org/ -[Lmod]: https://www.tacc.utexas.edu/research-development/tacc-projects/lmod +1. Next, we edit the "script.sh.erb" file. This file can also be found in the "template" folder. Edit this file by adding the lines below to the end of the file. This is the actual job script that will be submitted to the cluster, just like you would submit a job with "sbatch" from the command line. -## Install + ``` YAML + module load FSL/6.0.3 + source /share/apps/rc/software/FSL/6.0.3/fsl/etc/fslconf/fsl.sh + fsl + ``` -Use git to clone this app and checkout the desired branch/version you want to -use: +Save the file, and close the tab. This script runs the app executable after loading the appropriate module, based on the version you choose in the form. -```sh -scl enable git19 -- git clone <repo> -cd <dir> -scl enable git19 -- git checkout <tag/branch> -``` + -You will not need to do anything beyond this as all necessary assets are -installed. You will also not need to restart this app as it isn't a Passenger -app. +### Launching your OOD Sandbox App -To update the app you would: +Click on Launch FSL, and submit the job with desired parameters. You should have your first dev app (FSL) running. -```sh -cd <dir> -scl enable git19 -- git fetch -scl enable git19 -- git checkout <tag/branch> -``` + -Again, you do not need to restart the app as it isn't a Passenger app. +### More info -## Contributing +[Contact us](../index.md#how-to-contact-us) if you run into any issues, or to discuss any new app. -1. Fork it ( https://github.com/OSC/bc_osc_matlab/fork ) -2. Create your feature branch (`git checkout -b my-new-feature`) -3. Commit your changes (`git commit -am 'Add some feature'`) -4. Push to the branch (`git push origin my-new-feature`) -5. Create a new Pull Request diff --git a/images/cheaha_develop_button.png b/images/cheaha_develop_button.png new file mode 100644 index 0000000000000000000000000000000000000000..c37e977d571b74945fc505f4c297f073352d4b2e Binary files /dev/null and b/images/cheaha_develop_button.png differ diff --git a/images/cheaha_develop_sandbox.png b/images/cheaha_develop_sandbox.png new file mode 100644 index 0000000000000000000000000000000000000000..b1f78a8c8c9a8bea20d28222bc016739c598e82c Binary files /dev/null and b/images/cheaha_develop_sandbox.png differ diff --git a/images/cheaha_help_button.png b/images/cheaha_help_button.png new file mode 100644 index 0000000000000000000000000000000000000000..e729ea5361b44bbc66d51862cc5a79656b44df6e Binary files /dev/null and b/images/cheaha_help_button.png differ diff --git a/images/cheaha_sandbox_shell_button.png b/images/cheaha_sandbox_shell_button.png new file mode 100644 index 0000000000000000000000000000000000000000..9fcb49d5745c298c64898b63bafd9efd6b7fef35 Binary files /dev/null and b/images/cheaha_sandbox_shell_button.png differ diff --git a/images/file_sandbox_app.png b/images/file_sandbox_app.png new file mode 100644 index 0000000000000000000000000000000000000000..8ced39d823aec9942bee89195f82be4b18922efb Binary files /dev/null and b/images/file_sandbox_app.png differ diff --git a/images/manifest_yml_sandbox.png b/images/manifest_yml_sandbox.png new file mode 100644 index 0000000000000000000000000000000000000000..d8e02645db57a4526bbd0d789f93a6e6562c8fa6 Binary files /dev/null and b/images/manifest_yml_sandbox.png differ diff --git a/images/new_fsl_sandbox_app.png b/images/new_fsl_sandbox_app.png new file mode 100644 index 0000000000000000000000000000000000000000..b2ca77b5c27956085a0f6fa7f234e1908dd38501 Binary files /dev/null and b/images/new_fsl_sandbox_app.png differ diff --git a/images/sandbox_formYmlErb.png b/images/sandbox_formYmlErb.png new file mode 100644 index 0000000000000000000000000000000000000000..8ea52596903d83e8b86fc564733b9a561177dd3b Binary files /dev/null and b/images/sandbox_formYmlErb.png differ diff --git a/images/sandbox_launchFSL.png b/images/sandbox_launchFSL.png new file mode 100644 index 0000000000000000000000000000000000000000..6c58e6217c488512a7a18ade343ba261720025ec Binary files /dev/null and b/images/sandbox_launchFSL.png differ diff --git a/images/sandbox_new_app.png b/images/sandbox_new_app.png new file mode 100644 index 0000000000000000000000000000000000000000..332ae7a93760373f1be703c5bbfa1c79d94231cb Binary files /dev/null and b/images/sandbox_new_app.png differ diff --git a/images/sandbox_new_app_form.png b/images/sandbox_new_app_form.png new file mode 100644 index 0000000000000000000000000000000000000000..0a560109be2ff9bef87557ec8b036c03df32fcfe Binary files /dev/null and b/images/sandbox_new_app_form.png differ diff --git a/images/sandbox_scriptShErb.png b/images/sandbox_scriptShErb.png new file mode 100644 index 0000000000000000000000000000000000000000..af6955a5c1601af91ef5912c51203f45fb5731d1 Binary files /dev/null and b/images/sandbox_scriptShErb.png differ