00_InitialSetup.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "ST5HulCPypEc"
   },
   "source": [
    "# System setup for BWSI Remote Sensing for Disaster Response course\n",
    "This notebook will run through the initial setup of the course environment, and get you familiar with the JupyterLab interface. [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/) is the next-gen web interface for Jupyter, and includes additional features such as tabs, integrated file browser, and modular windows.\n",
    "\n",
    "The course is designed to use the hosted jupyterhub instance at https://jupyter.bwsi-remote-sensing.net, which hosts a jupyter server with the required packages all pre-installed. The jupyterhub service is only available to registered participants of BWSI Remote Sensing for Disaster Relief 2020, and uses github for authentication. If you are following along on your own system, we have provided a [docker image](https://hub.docker.com/r/bwsiremotesensing/jupyter-gis-image/tags) which has the requirements for this course installed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basics of JupyterLab\n",
    "---\n",
    "To run code in a jupyter notebook, first click on a cell to highlight it, then press `Ctrl+Enter`. To run the code and advance to the next cell, highlight the cell and press `Shift+Enter` or click on the play button in the menu bar."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Welcome to BWSI Remote Sensing for Disaster Relief\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "colab_type": "text",
    "id": "lCI9hXxAySvQ"
   },
   "source": [
    "## Setting up GitHub\n",
    "---\n",
    "We will be using github for the lesson code. First, we need to set up SSH keys so that we can pull and push from github in jupyterhub.\n",
    "\n",
    "SSH keys are pairs of files---a public and a private key---which allow holders of the public key to identify if a message came from the holder of the private key. This is an example of [public-key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography). We will generate a key pair and upload our public key to your GitHub account and save the private key to your jupyter server. This is an alternative to having to input your account username and password every time you make a git push/pull.\n",
    "\n",
    "This section of the lesson is adapted from the [GitHub tutorials](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) for generating a new SSH key.\n",
    "\n",
    "### Generate a key pair\n",
    "First, open a new Terminal tab `File > New > Terminal`. This will create a command line interface to your virtual machine.\n",
    "\n",
    "If you want, you can click and drag the Terminal tab down to create a side-by-side interface with the notebook and terminal within JupyterLab.\n",
    "\n",
    "Inside the terminal window, run the following command:\n",
    "```bash\n",
    "$ ssh-keygen -t rsa -b 4096 -C \"your_email@example.com\"\n",
    "```\n",
    "where `your_email@example.com` is replaced with your email address used for your GitHub account.\n",
    "\n",
    "This creates a new ssh key, using the provided email as a label.\n",
    "```bash\n",
    "> Generating public/private rsa key pair.\n",
    "```\n",
    "\n",
    "When you're prompted to \"Enter a file in which to save the key,\" press `Enter`. This accepts the default file location.\n",
    "```bash\n",
    "> Enter a file in which to save the key (/c/Users/jovyan/.ssh/id_rsa):[Press enter]\n",
    "```\n",
    "Note that the default username on the Jupyter VM is `jovyan`, which is an alternate name for the god Jupiter. This will be the username that everyone has for JupyterHub.\n",
    "\n",
    "You will then be prompted to type a passphrase to add an extra layer of security to your ssh keys. Optionally, you can leave it blank and press `Enter` to save your keys without a passphrase.\n",
    "```\n",
    "> Enter passphrase (empty for no passphrase): [Type a passphrase]\n",
    "> Enter same passphrase again: [Type passphrase again]\n",
    "```\n",
    "\n",
    "At this point, you should have created an SSH key-pair, saved the file, and added it to the `ssh-agent`. To test this, we can take a look at the `.ssh` folder in your home directory by running the following:\n",
    "\n",
    "```bash\n",
    "$ ls ~/.ssh/\n",
    "```\n",
    "\n",
    "which should return\n",
    "\n",
    "```bash\n",
    "id_rsa  id_rsa.pub  known_hosts\n",
    "```\n",
    "\n",
    "We want to make sure your private key `id_rsa` has the correct permissions (only your user can interact with it), so we run:\n",
    "\n",
    "```bash\n",
    "$ chmod 700 ~/.ssh/id_rsa\n",
    "```\n",
    "\n",
    "For more information about the `chmod` command and why code `700` corresponds to user-access-only, check out [this link](https://ss64.com/bash/chmod.html).\n",
    "\n",
    "You can take a look at the public key with:\n",
    "\n",
    "```bash\n",
    "$ cat ~/.ssh/id_rsa.pub\n",
    "```\n",
    "which should print out your public key\n",
    "\n",
    "> Alternatively, you can input terminal commands in jupyter notebooks using the `!` prefix.\n",
    "> Typically, code cells in jupyter only run within the Python kernel. However, the `!` prefix\n",
    "> tells jupyter to run the line as a system terminal command.\n",
    "> Try this with the code cells below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!ls ~/.ssh"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!cat ~/.ssh/id_rsa.pub"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we need to add our new SSH public key to our GitHub account so GitHub knows about our keys. Copy the public key we just printed out with\n",
    "\n",
    "```bash\n",
    "$ cat ~/.ssh/id_rsa.pub\n",
    "```\n",
    "\n",
    "Then, go to your GitHub account, click on your profile photo (top right corner) and go to `Settings`. \n",
    "\n",
    "![image of profile photo dropdown menu](https://help.github.com/assets/images/help/settings/userbar-account-settings.png)\n",
    "\n",
    "Click on the menu item `SSH and GPG keys` on the user settings sidebar.\n",
    "\n",
    "![ssh and gpg keys menu item](https://help.github.com/assets/images/help/settings/settings-sidebar-ssh-keys.png)\n",
    "\n",
    "Click New SSH key or Add SSH key.\n",
    "\n",
    "![Image of New SSH Key button](https://help.github.com/assets/images/help/settings/ssh-add-ssh-key.png)\n",
    "\n",
    "In the \"Title\" field, add a descriptive label about the machine that is using this new key, such as \"BWSI 2020 JupyterHub\".\n",
    "Paste your public key into the `Key` field.\n",
    "\n",
    "![Image of Key field in new SSH key dialogue](https://help.github.com/assets/images/help/settings/ssh-key-paste.png)\n",
    "\n",
    "Click `Add SSH key`\n",
    "\n",
    "![Image of Add SSH key button](https://help.github.com/assets/images/help/settings/ssh-add-key.png)\n",
    "\n",
    "If prompted, confirm your GitHub password. \n",
    "\n",
    "![Image of password confirmation prompt](https://help.github.com/assets/images/help/settings/sudo_mode_popup.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's test if this worked! GitHub lets you check if you've successfully authenticated using ssh using the command:\n",
    "```bash\n",
    "$ ssh -T git@github.com\n",
    "```\n",
    "\n",
    "If successful, you should see a message similar to:\n",
    "```\n",
    "Warning: Permanently added the RSA host key for IP address '140.82.114.3' to the list of known hosts.\n",
    "Hi username! You've successfully authenticated, but GitHub does not provide shell access.\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!ssh -T git@github.com"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next we need to do some configuration of git. Run in the terminal\n",
    "```bash\n",
    "$ git config --global user.email \"you@example.com\"\n",
    "```\n",
    "\n",
    "```bash\n",
    "$ git config --global user.name \"Your Name\"\n",
    "```\n",
    "to set your account's default identity, replacing `you@example.com` and `Your Name` with your email and name respectively"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "colab": {
   "collapsed_sections": [],
   "include_colab_link": true,
   "name": "00-InitialSetup.ipynb",
   "provenance": [],
   "toc_visible": true,
   "version": "0.3.2"
  },
  "kernelspec": {
   "display_name": "Python 3",
   "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.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}