Copy instructions for VS code in Paperspace (#44)

* Copy instructions for VS code in Paperspace

* [GH-Actions] Add new files from specs (#45)

.github/deployment-configs/deploy-useful-tips.yaml

Co-authored-by: Rahul <[email protected]>

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Rahul <[email protected]>

Author: 3 people

.github/deployment-configs/deploy-useful-tips.yaml

@@ -0,0 +1,27 @@
+# Copyright (c) 2022 Graphcore Ltd. All rights reserved.
+
+_examples_internal_repository: &_examples_internal_repository
+  origin: examples-internal/
+  ref: null
+
+_common_target_repository: &_common_target_repository
+  origin: notebooks/
+  ref: null
+
+
+useful-tips:
+  source:
+    paths:
+    - path: useful-tips/
+      recursive: true
+    excludes:
+    - path: useful-tips/managing_ipu_resources.ipynb
+      recursive: false
+    repository:
+      origin: https://github.com/graphcore/Gradient-HuggingFace
+      ref: main
+      prefix: useful-tips
+  target:
+    repository:
+      <<: *_common_target_repository
+      prefix: useful-tips

useful-tips/images/connect-tunnel-from-web-1.png

@@ -0,0 +1,225 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Using VS Code in Paperspace Notebooks\n",
+    "\n",
+    "VS Code is a versatile code editor which can be used from your desktop or browser and can connect to remote machines to give you convenient access to remote compute resources.\n",
+    "\n",
+    "To connect to IPU machines in Gradient notebooks in Paperspace you can use the [Remote - Tunnels](https://marketplace.visualstudio.com/items?itemName=ms-vscode.remote-server) extension.\n",
+    "\n",
+    "This notebook will get you set up with a VS Code server that can be used to develop and run commands on the IPU machines in Paperspace from VS Code web editors or desktop applications.\n",
+    "\n",
+    "We've also included some troubleshooting steps for common issues."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2023-08-09T10:30:04.537632Z",
+     "iopub.status.busy": "2023-08-09T10:30:04.536837Z",
+     "iopub.status.idle": "2023-08-09T10:30:04.545588Z",
+     "shell.execute_reply": "2023-08-09T10:30:04.545027Z",
+     "shell.execute_reply.started": "2023-08-09T10:30:04.537611Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "%cd /notebooks"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2023-08-09T10:50:47.010715Z",
+     "iopub.status.busy": "2023-08-09T10:50:47.009950Z",
+     "iopub.status.idle": "2023-08-09T10:50:48.656974Z",
+     "shell.execute_reply": "2023-08-09T10:50:48.656221Z",
+     "shell.execute_reply.started": "2023-08-09T10:50:47.010692Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "!curl -Lk 'https://code.visualstudio.com/sha/download?build=stable&os=cli-alpine-x64' --output vscode_cli.tar.gz\n",
+    "!tar -xf vscode_cli.tar.gz"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The next cell will configure folders to make your VS Code installation persist across machines -- you won't have to reinstall extensions every time you restart your Gradient Notebook instance."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!mkdir -p /storage/.vscode/server\n",
+    "!ln -s /storage/.vscode/server $HOME/.vscode-server\n",
+    "!cp code /storage/.vscode/code\n",
+    "!ls /storage/.vscode"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can now start the tunnel with the following command. Let's name the tunnel `ipu-paperspace`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2023-08-09T10:53:07.032274Z",
+     "iopub.status.busy": "2023-08-09T10:53:07.031643Z",
+     "iopub.status.idle": "2023-08-09T11:02:45.570502Z",
+     "shell.execute_reply": "2023-08-09T11:02:45.569394Z",
+     "shell.execute_reply.started": "2023-08-09T10:53:07.032246Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "!/storage/.vscode/code tunnel --accept-server-license-terms --name=ipu-paperspace"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You should see something similar to the following in the console:\n",
+    "\n",
+    "```console\n",
+    "*\n",
+    "* Visual Studio Code Server\n",
+    "*\n",
+    "* By using the software, you agree to\n",
+    "* the Visual Studio Code Server License Terms (https://aka.ms/vscode-server-license) and\n",
+    "* the Microsoft Privacy Statement (https://privacy.microsoft.com/en-US/privacystatement).\n",
+    "*\n",
+    "To grant access to the server, please log into https://github.com/login/device and use code FA2A-360B\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "execution": {
+     "iopub.execute_input": "2023-08-09T10:25:51.970178Z",
+     "iopub.status.busy": "2023-08-09T10:25:51.969591Z",
+     "iopub.status.idle": "2023-08-09T10:25:52.157585Z",
+     "shell.execute_reply": "2023-08-09T10:25:52.157047Z",
+     "shell.execute_reply.started": "2023-08-09T10:25:51.970138Z"
+    }
+   },
+   "source": [
+    "You need to now log into GitHub to authorise the tunnel. Open https://github.com/login/device and enter the one-time code into the following screen:\n",
+    "\n",
+    "![code screen](https://raw.githubusercontent.com/graphcore/Gradient-HuggingFace/main/useful-tips/images/login-code.png)\n",
+    "\n",
+    "Once you have completed the login workflow on GitHub and see this screen you are good to go!\n",
+    "\n",
+    "![success screen](https://raw.githubusercontent.com/graphcore/Gradient-HuggingFace/main/useful-tips/images/login-success.png)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "On your console, you should now see:\n",
+    "\n",
+    "```console\n",
+    "[2023-08-09 11:37:06] info Creating tunnel with the name: ipu-paperspace\n",
+    "\n",
+    "Open this link in your browser https://vscode.dev/tunnel/ipu-paperspace/notebooks\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "Now, open https://vscode.dev/tunnel/ipu-paperspace/notebooks to access the machine from a browser.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Use the VS Code desktop app\n",
+    "\n",
+    "You can also connect from the VS Code desktop app:\n",
+    "\n",
+    "- either by clicking in the bottom left corner of the VS Code Web editor and selecting `Continue Working in VS Code Desktop`:\n",
+    "\n",
+    "![Click in the bottom right corner](https://raw.githubusercontent.com/graphcore/Gradient-HuggingFace/main/useful-tips/images/connect-tunnel-from-web-1.png)\n",
+    "\n",
+    "![Select \"Continue working in VS Code desktop\"](https://raw.githubusercontent.com/graphcore/Gradient-HuggingFace/main/useful-tips/images/connect-tunnel-from-web-2.png)\n",
+    "\n",
+    "- or by connecting directly from your desktop app. Install the [Remote - Tunnels](https://marketplace.visualstudio.com/items?itemName=ms-vscode.remote-server) extension and then add a new remote tunnel and when it's been created, connect to it:\n",
+    "\n",
+    "![Add the new remote tunnel](https://raw.githubusercontent.com/graphcore/Gradient-HuggingFace/main/useful-tips/images/connect-tunnel-to-app-1.png)\n",
+    "\n",
+    "![Connect to the remote tunnel](https://raw.githubusercontent.com/graphcore/Gradient-HuggingFace/main/useful-tips/images/connect-tunnel-to-app-2.png)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Common issues\n",
+    "\n",
+    "After you have completed the GitHub authorisation workflow, you can get the following error:\n",
+    "\n",
+    "```console\n",
+    "[2023-08-09 11:37:09] error Could not create tunnel with name: ipu-paperspace\n",
+    "Reason: tunnel name already in use\n",
+    "```\n",
+    "\n",
+    "In this case you can change the name of the tunnel. Alternatively, if the tunnel is no longer in use you can\n",
+    "[clear the stale tunnel](https://github.com/microsoft/vscode-remote-release/issues/7469#issuecomment-1303968245) from the VS Code application on your machine as follows:\n",
+    "\n",
+    "1. Make sure that the [Remote - Tunnels](https://marketplace.visualstudio.com/items?itemName=ms-vscode.remote-server) extension is installed on your machine.\n",
+    "2. Click on the Remote extensions pane (on the left of your UI).\n",
+    "3. Right click on the tunnel you want to clear.\n",
+    "4. Unregister the tunnel .\n",
+    "\n",
+    "![unregister a VS Code tunnel](https://raw.githubusercontent.com/graphcore/Gradient-HuggingFace/main/useful-tips/images/tunnel-unregister.png)\n",
+    "\n",
+    "You can now re-run the command to create a tunnel."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}