diff --git a/.gitignore b/.gitignore index 2093f7c3..4efdfe45 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ __pycache__/ # Figures *.jpg *.gif +!docs/**/*.gif # Data files created /results diff --git a/docs/user-guide/tutorials/assets/add-storage.gif b/docs/user-guide/tutorials/assets/add-storage.gif new file mode 100644 index 00000000..19fbb2a4 Binary files /dev/null and b/docs/user-guide/tutorials/assets/add-storage.gif differ diff --git a/docs/user-guide/tutorials/assets/add-workspace.gif b/docs/user-guide/tutorials/assets/add-workspace.gif new file mode 100644 index 00000000..3cecde89 Binary files /dev/null and b/docs/user-guide/tutorials/assets/add-workspace.gif differ diff --git a/docs/user-guide/tutorials/index.md b/docs/user-guide/tutorials/index.md index e7daf534..ed65ced9 100644 --- a/docs/user-guide/tutorials/index.md +++ b/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 diff --git a/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb b/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb new file mode 100644 index 00000000..7cc281be --- /dev/null +++ b/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 +}