DOC: Add SURF setup instructions

docs/user-guide/tutorials/index.md

@@ -1,6 +1,7 @@
 # Tutorials
 
 ```{nbgallery}
+surf_research_cloud_setup.ipynb
 ADCP_data_tutorial.ipynb
 CTD_data_tutorial.ipynb
 Drifter_data_tutorial.ipynb

docs/user-guide/tutorials/surf_research_cloud_setup.ipynb

@@ -0,0 +1,99 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "vscode": {
+     "languageId": "plaintext"
+    }
+   },
+   "source": [
+    "# SURF Resarch Cloud: Virtualship environment setup\n",
+    "\n",
+    "> Note:  \n",
+    "> This guide is specific to students who are enrolled at UU in the {} course.\n",
+    "\n",
+    "In the class, we use virtualship in the cloud (in this case, SURF Research Cloud - called SURF RC from here-on). This has several advantages:\n",
+    "\n",
+    "- You aren't limited to the power of your laptop\n",
+    "- Input datasets are downloaded faster, as they're downloaded to the cloud instance (and not to your laptop)\n",
+    "- It's easier to collaborate with your peers\n",
+    "\n",
+    "For each team, we have set up a Jupyter workspace (with virtualship installed)along with 100Gb of persistent storage. The storage and the workspace are named after a research vessel. **Only use the workspace associated with your research vessel.**\n",
+    "\n",
+    "100Gb should be sufficient for the data that you need to download - just make sure to clear up space from prior runs if you run out.\n",
+    "\n",
+    "> IMPORTANT: Make sure to pause the instance when you're not using it, and if you're done with a run, and resume it next time you log in.\n",
+    "\n",
+    "\n",
+    "## 1. Accepting SURF RC invite\n",
+    "\n",
+    "In your student email you'll have an invite to join a project on SURF RC. Accept this invite.\n",
+    "\n",
+    "## 2. Navigate to the SURF Research Cloud Dashboard\n",
+    "\n",
+    "You'll arrive at a dashboard that looks like the following. Here you can click \"Resume\" to boot up your instance. Once started, an \"Access\" button will appear in the same spot. Clicking this will open the Jupyter workspace in a new tab.\n",
+    "\n",
+    "\n",
+    "## 3. Jupyter workspace layout and additional config\n",
+    "\n",
+    "> Note: This only needs to be done once during setup.\n",
+    "\n",
+    "In the Jupyter workspace, you'll see the following in your file explorer:\n",
+    "```\n",
+    ".\n",
+    "├── KERNEL-README.ipynb\n",
+    "├── data\n",
+    "│   └── datasets\n",
+    "|   └── {your research vessel name}    <--- Your persistent storage\n",
+    "└── scratch\n",
+    "```\n",
+    "\n",
+    "The `data/{your research vessel name}` folder is your persistent storage. This is the primary place you should store your `virtualship` configs and content relevant to this unit.\n",
+    "\n",
+    "---\n",
+    "\n",
+    "To be able to run virtualship from the terminal, we need to take some additional steps which are detailed in the `KERNEL-README.ipynb` contains important information for configuring your environment. Namely, for our uses, the \"Initialize conda\" section. Do the following.\n",
+    "\n",
+    "> #### Initialize conda\n",
+    "> \n",
+    "> To make the already installed conda-tool available for yourself, you have to initialize your terminal shell.\n",
+    "> \n",
+    "> Start a \"Terminal\" tab in the Jupyter Lab launcher and type:\n",
+    "> ```\n",
+    "> /etc/miniconda/bin/conda init\n",
+    "> ```\n",
+    "> Close the terminal tab and start a new one.\n",
+    "> You will see that the terminal prompt has changed to something like\n",
+    "> ```\n",
+    "> (base) metheuser@mywsp:\n",
+    "> ```\n",
+    "> This is conda telling you that you are currently in the \"base\" environment.\n",
+    "\n",
+    "From here, you already have another environment set up for you. Running `conda env list` in the terminal, you should see:\n",
+    "\n",
+    "```bash\n",
+    "(base) $ conda env list\n",
+    "\n",
+    "# conda environments:\n",
+    "#\n",
+    "base                 * /etc/miniconda\n",
+    "virtualship            /etc/miniconda/envs/virtualship`\n",
+    "```\n",
+    "\n",
+    "Here you can do `conda activate virtualship` to activate the environment called \"virtualship\". Now you have access to the `virtualship` command in your terminal, which can be confirmed by running `virtualship --help`. From here you can `cd` into `data/{your research vessel name}` and run `virtualship` commands as you would on your local machine.\n",
+    "\n",
+    "---\n",
+    "Finally, when you're working in Jupyter Notebooks, you are able to access the Conda environment with `virtualship` and related dependencies by switching the Kernel in the top right of the UI.\n",
+    "\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}