DOC: Add SURF setup instructions

.gitignore

@@ -6,6 +6,7 @@ __pycache__/
 # Figures
 *.jpg
 *.gif
+!docs/**/*.gif
 
 # Data files created
 /results

docs/user-guide/tutorials/index.md

@@ -5,6 +5,7 @@
 maxdepth: 1
 caption: Tutorials
 ---
+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,115 @@
+{
+ "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 Dynamical Oceanography 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",
+    "\n",
+    "\n",
+    "## 1. Accepting SURF RC invite\n",
+    "\n",
+    "In your student email you'll have an invite from SURF Research Access Management (SRAM) to join a project on SURF RC. Accept this invite.\n",
+    "\n",
+    "## 2. Create the environment\n",
+    "\n",
+    "Navigate to the [SURF Research Cloud Dashboard](https://portal.live.surfresearchcloud.nl/), and create the storage and compute resources you need.\n",
+    "\n",
+    "Below we show create the storage.\n",
+    "\n",
+    "![Adding storage GIF](./assets/add-storage.gif)\n",
+    "\n",
+    "As shown: to create the storage go to the storage tab, click `+`, and add a SURF HPC Cloud Volume of 100Gb (naming it something unique and memorable). This will be your persistent storage for your workspace instance.\n",
+    "\n",
+    "Below we show create the workspace.\n",
+    "\n",
+    "![Adding workspace GIF](./assets/add-workspace.gif)\n",
+    "\n",
+    "\n",
+    "As shown: to create the workspace instance go to the workspace tab, click `+`, search for and select \"virtualship\", then choose the storage you just created, adjust the expiration date to some time after 14 march 2025, and change the name/hostname to something memorable.\n",
+    "\n",
+    "Once the workspace is created, you can click \"Access\" to open it in a new tab. This might take a while (up to 10 minutes) - make sure to occasionally refresh the page.\n",
+    "\n",
+    "\n",
+    "> IMPORTANT: Make sure to pause the instance when you’re not using it, and resume it next time you log in. Only the workspace creator can pause, resume, and delete the workspace - this is an unavoidable limitation of SURF RC.\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 storage name}    <--- Your persistent storage\n",
+    "└── scratch\n",
+    "```\n",
+    "\n",
+    "The `data/{your storage 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 storage 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"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}