diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 9a56995e..70d3a645 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,5 +1,5 @@ -- [ ] Closes #xxxx +- Closes #xxxx - [ ] Tests added - [ ] Re-ran README.md help commands if the CLI has changed diff --git a/docs/user-guide/tutorials/old_surf_research_cloud_setup.ipynb b/docs/user-guide/tutorials/old_surf_research_cloud_setup.ipynb new file mode 100644 index 00000000..7cc281be --- /dev/null +++ b/docs/user-guide/tutorials/old_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 +} diff --git a/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb b/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb index 7cc281be..299d9cb0 100644 --- a/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb +++ b/docs/user-guide/tutorials/surf_research_cloud_setup.ipynb @@ -23,28 +23,9 @@ "\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", + "## 2. Open the environment\n", "\n", + "Navigate to the [SURF Research Cloud Dashboard](https://portal.live.surfresearchcloud.nl/), and click \"access\" on the shared workspace.\n", "\n", "## 3. Jupyter workspace layout and additional config\n", "\n", @@ -56,11 +37,11 @@ "├── KERNEL-README.ipynb\n", "├── data\n", "│ └── datasets\n", - "| └── {your storage name} <--- Your persistent storage\n", + "| └── shared-storage <--- The shared 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", + "The `data/shared-storage` folder is your persistent storage. Here you can make a folder (e.g., `mkdir data/shared-storage/{your-group-name}` replacing `{your-group-name}` with your group name) to house your work for the unit. This folder will be visible to anyone using the workspace, but only you will be able to make edits to it. This is the primary place you should store your `virtualship` configs and content relevant to this unit.\n", "\n", "---\n", "\n", @@ -84,7 +65,7 @@ "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", + "conda env list\n", "\n", "# conda environments:\n", "#\n", @@ -92,11 +73,23 @@ "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", + "Here you can do `conda activate virtualship` to activate the environment called \"virtualship\". This environment is a shared environment among all workspace users that can be centrally updated. If you want you can create and manage your own environments by running the relevant conda commands.\n", + "\n", + "With the `virtualship` environment, you now have access to the `virtualship` command in your terminal, which can be confirmed by running `virtualship --help`. From here you can `cd` into `data/shared-storage/{your-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" + "\n", + "\n", + "\n", + "## Course facilitator notes\n", + "\n", + "If `virtualship` is updated on GitHub, and you want to update the shared environment, you can do so by running the following commands in the terminal:\n", + "\n", + "```bash\n", + "conda activate virtualship\n", + "sudo /etc/miniconda/envs/virtualship/bin/pip install --upgrade git+https://github.com/OceanParcels/virtualship@main\n", + "```" ] }, {