Update SURF setup instructions #128
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| <!-- Feel free to remove check-list items aren't relevant to your change --> | ||
|
|
||
| - Closes #xxxx | ||
| - [ ] Tests added | ||
| - [ ] Re-ran README.md help commands if the CLI has changed |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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", | ||
| "\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", | ||
| "\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 | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
replacing
{your-name}with your name)suggestion: add (group)
replacing
{your-name}with your (group) name)