Merge pull request #9 from jiavila/update_docs

Update docs and additional settings

doc/1-choose-an-integration-method.md

@@ -10,7 +10,7 @@ Check with your admin as to the best option for you.
 
 If cron is enabled, this is probably the best choice. The below example would run Cast once a minute.
 
-1. Create a new crontab file. Note: you maybe to prepend `sudo` if there are any permission issues.
+1. Create a new crontab file. Note: you may have to prepend `sudo` if there are any permission issues.
 
 ```
 crontab -e
@@ -40,8 +40,8 @@ If the script does not run, try using `bash` or `sh` in the command:
 */1 * * * * bash ~/fw-cast/settings/start-cast.sh
 ```
 
-4. Save and exit. Save the file with `control + O`, and hit enter when prompted about the file name and location.
-Exit with `control + X`
+4. Save and exit. If you're using nano, save the file with `control + O`, and hit enter <br/>
+   when prompted about the file name and location. Exit with `control + X`
 
 For further options, check out [crontab guru](https://crontab.guru/#*/1_*_*_*_*) or your system documentation.
 

doc/3-cluster-install.md

@@ -91,3 +91,49 @@ You need to edit each of these files in turn to configure it for your cluster:
 Each file has a variety of comments to guide you through the process.<br/>
 Work with your collaborating Flywheel employee on these settings, particularly the <br/>
 connection credential (i.e., `SCITRAN_CORE_DRONE_SECRET` in `credentials.sh`).
+
+
+### Folder settings
+There are five different directories/folders that one should consider.  Four of these <br/>
+default folders can be changed by exporting/setting the corresponding environment <br/>
+variable in `fw-cast/settings/credentials.sh`
+
+#### [SINGULARITY_TMPDIR](https://sylabs.io/guides/latest/user-guide/build_env.html#temporary-folders)
+"When building a container, or pulling/running a SingularityCE container from a Docker/OCI source, <br/>
+a temporary working space is required. The container is constructed in this temporary space <br/>
+before being packaged into a SingularityCE SIF image."
+
+
+#### [SINGULARITY_WORKDIR](https://sylabs.io/guides/latest/user-guide/appendix.html)
+"The working directory to be used for `/tmp`, `/var/tmp` and `$HOME` (if -c or --contain was also used)".<br/>
+Instead of mounting to the default directory of the OS--i.e., `tmp` (not to be confused <br/>
+with the singularity image's `tmp` directory)--one can mount a drive that can handle intermediate <br/>
+files generated when the singularity image is run.
+
+Note: when the singularity container is built and Cast executes singularity, it passes [the flag](https://sylabs.io/guides/latest/user-guide/bind_paths_and_mounts.html?highlight=containall#containall) <br/>
+`--containall`, which does not mount a user's `$HOME` directory and additionally contains <br/>
+PID, IPC, and environment. One can set this flag when developing and testing singularity <br/> 
+images to simulate similar conditions. 
+
+#### [SINGULARITY_CACHEDIR](https://sylabs.io/guides/latest/user-guide/build_env.html#sec-cache)
+When a gear is pulled and converted to a sif file, this folder is where both docker and <br/>
+sif images are stored. The cache is created at `$HOME/.singularity/cache` by default. </br>
+
+
+#### Engine folders
+The folders `ENGINE_CACHE_DIR` and `ENGINE_TEMP_DIR` are where gear inputs and output files <br/>
+will be stored. These should be set to a location that will be able to handle the size of both
+<br/> input and output files, and both should be set to the same directory.
+
+#### Log folders
+When Cast finds a job from a Flywheel instance, it creates an executable script (`.sh`) for the <br/>
+job and its associated log file. The job id will be the in the title of executable and <br/>
+its `.txt` log file; they are stored in the directories `fw-cast/logs/generated` and <br/>
+`fw-cast/logs/queue`, respectively.  
+
+The executable job script is created from a `SCRIPT_TEMPLATE` (found in `fw-cast/code/cluster`), <br/>
+depending on the HPC's job scheduler/cluster type (e.g., slurm). The `start-cast.sh` file <br/>
+logs this template in `fw-cast/logs/cast.log`. When troubleshooting an HPC gear, it is <br/>
+convenient to use the command `tail -60 fw-cast/logs/cast.log` to print out the last 60 lines from the <br/>
+log file, since this can get quite long.
+

examples/settings/credentials.sh

@@ -11,8 +11,11 @@ export ENGINE_TEMP_DIR="/some-folder"
 # Flywheel SDK settings
 export FLYWHEEL_SDK_SKIP_VERSION_CHECK="1"
 
-# Flywheel site credentials
-export SCITRAN_RUNTIME_HOST="<your-hostname>"
+# Flywheel site credentials. SCITRAN_RUNTIME_HOST is your flywheel site URL (e.g.,
+# `ga.ce.flywheel.io`). Do not use the scheme portion of your URL (e.g., `https://`),
+# or subdirectories (e.g., `#/projects`), only domains. SCITRAN_CORE_DRONE_SECRET will
+# be provided by flywheel support staff.
+export SCITRAN_RUNTIME_HOST="<your-flyhwheel-site-domain>"
 export SCITRAN_RUNTIME_PORT="443"
 export SCITRAN_CORE_DRONE_SECRET="<your-credentials>"
 
@@ -25,4 +28,15 @@ export ENGINE_SIGNED_URLS=1
 # HPC compatible compute
 export ENGINE_MODULE=singularity
 
+# absolute path to the singularity executable
+export PATH=$PATH:/usr/local/bin/
+
+# singularity working directory for /tmp, /var/tmp, and $HOME. Default is the OS `tmp`
+# directory
+# export SINGULARITY_WORKDIR="path/to/singularity_workdir"
+
+# "SingularityCE will cache SIF container images generated from remote sources, and any
+# OCI/docker layers used to create them". The default is $HOME/.singularity/cache
+# export SINGULARITY_CACHEDIR="path/to/singularity/cache"
+
 # Do NOT put other engine settings in this file.

readme.md

@@ -31,13 +31,19 @@ Otherwise, some light python development will be required.
 2. It is strongly recommended that you [make a private github repo](doc/2-tracking-changes-privately.md) to track your changes.<br/>
 This will make Cast much easier to manage.
 
-3. Perform the [initial cluster setup](doc/3-cluster-install.md).
+3. Perform the [initial cluster setup](doc/3-cluster-install.md). If you are unfamiliar with <br/>
+singularity, it is recommended that you read--at a minimum--SingularityCE's [introduction](https://sylabs.io/guides/latest/user-guide/introduction.html) <br/>
+   and [quick start](https://sylabs.io/guides/latest/user-guide/quick_start.html) guides.
+
+4. [Create an authorization token](doc/Flywheel%20HPC%20Client%20-%20Singularity%20api%20key%20configuration.pdf) 
+   so Singularity and Flywheel can work with each other.
 
-4. If your queue type is not in the above table, or is sufficiently different, review the guide for [adding a queue type](doc/4-development-guide.md).
+5. If your queue type is not in the above table, or is sufficiently different, review the guide for [adding a queue type](doc/4-development-guide.md).
 
-5. Collaborate with Flywheel staff to install an Engine binary and run your first HPC job tests.
+6. Collaborate with Flywheel staff to [install an Engine binaries](doc/Flywheel%20HPC%20Client%20-%20engine%20configuration.pdf) 
+   and run your first HPC job tests.
 
-6. Complete the integration method you chose in step one.<br/>
+7. Complete the integration method you chose in step one.<br/>
 Confirm Cast is running regularly by monitoring `logs/cast.log` and the Flywheel user interface.
 
-7. Enjoy!
+8. Enjoy!