Tutorial_4_terminals_remote_hosts.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Learning your terminal\n",
    "\n",
    "The terminal acts as a type of hub for our computers. It is the most basic and direct way to interact with your system and holds a lot of power if you know how to use it. The goal of this tutorial is to help you:\n",
    "\n",
    "* Setup an effective terminal environment\n",
    "* Customize your terminal for your workflow\n",
    "* Automate routine commands through bash scripting\n",
    "* Interface with remote systems\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Opening the terminal / Setting up the terminal\n",
    "\n",
    "As a starting point lets talk about how you can access your terminal depending on which system you're running.\n",
    "\n",
    "**Linux**\n",
    "* Using the shortcut (`ctrl + alt + t`) \n",
    "* Typing \"terminal\" after hitting the windows key\n",
    "\n",
    "**Mac** \n",
    "* Press (`⌘ + space bar`) then type \"terminal\"\n",
    "  * (As a side note I would recommend installing [iTerm2](https://www.iterm2.com/) though that is just my personal preference.)\n",
    "  \n",
    "**Windows**\n",
    "* This one is a bit different. I would recommend:\n",
    "  * Installing [Git Bash](https://gitforwindows.org/)\n",
    "  * Installing the Windows Subsystem for Linux. A nice guide to follow for this can be found [here](https://char.gd/blog/2017/how-to-set-up-the-perfect-modern-dev-environment-on-windows).\n",
    "  \n",
    "Now that we have a terminal open let's practice some different commands of things that we can do from here.\n",
    "\n",
    "**Commands:**\n",
    "\n",
    "`ls` - lists files in the current directory\n",
    "\n",
    "To see all files, including hidden, you can use the flag `-a` for \"all.\" If you want more details on files or directories such as permissions, size, etc. use the flag `-l` for \"long.\"\n",
    "\n",
    "`pwd` - tells you where in the computer you currently are\n",
    "\n",
    "`cd` - this allows you to change directories\n",
    "\n",
    "By default typing `cd` with nothing else will take you to your home directory. The home directory can also be reached by using the shortcut `~/`. When using the `cd` command we can specify which directory we want to go to such as \"`cd /path/to/file`\". We can use other shortcut commands like `cd ../` to move up one file level (so from a subfolder to the folder it is contained in, or we can use `cd -` to return to the most recent directory.\n",
    "\n",
    "`mkdir name` - makes a new directory called \"name\" \n",
    "\n",
    "By default the new directory will be located in the current directory unless we put a file path in front of it like `mkdir /path/to/name`.\n",
    "\n",
    "`cp name location` - copies \"name\" to \"location\" \n",
    "\n",
    "To copy an entire directory we simply need to use the flag `-r` for \"recursive.\"\n",
    "\n",
    "`mv name location` - moves \"name\" to \"location\"\n",
    "\n",
    "If \"location\" is not a path to a new place, then the file will \"name\" will be renamed to \"location\".\n",
    "\n",
    "`rm name` - permanently deletes \"name\"\n",
    "\n",
    "**<font color=red> WARNING:</font>** `rm` is the destroyer of files. There is no recovering files from \"trash\" after deleting using this command. For safety you can use the flag `-i` to make your system verify that you really want to delete the item. There is a greater nuclear option `rm -r` that, you guessed it, removes the whole directory! Use with caution... Really."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Beefing up your terminal\n",
    "\n",
    "Now that we know some basics of the terminal let's add some enhanced functionality. If you have used the terminal for any length of time you may have noticed that it can be tedious to write long commands over and over again, especially if they are fairly common. This is where [Z shell](https://gist.github.com/derhuerst/12a1558a4b408b3b2b6e) comes in. \n",
    "\n",
    "### Z shell \n",
    "\n",
    "Z shell is a different shell (similar to bash) that has some increased functionality like searching through function commands. \n",
    "\n",
    "Suppose you run Python commands from your terminal frequently, but want to change some user input argument like \n",
    "\n",
    "`python simulation.py --user=\"-r=0\"`.\n",
    "\n",
    "Now maybe I want to run this again with `r=1`. If I have done a lot of other terminal things between runs then cycling through my command history may be impractical. With Z shell you can start typing the first few letters `py` then cycle using your arrow keys to all previous commands that contained that began with that string of characters. \n",
    "\n",
    "Z shell also has really nice autocomplete features so typing `py` then hitting the \"tab\" key will complete to `python` or to other programs that start with \"py.\" It is really a great tool!\n",
    "\n",
    "### Styling Z shell\n",
    "\n",
    "While vanilla Z shell is nice, sometimes the default terminal is a bit hard on the eyes. That is where [Oh-My-Zshell](https://ohmyz.sh/) comes in! It allows you to customize with a bunch of different themes, etc. to tailor your command line experience. Install instructions can be found at both links above for all major operating systems.\n",
    "\n",
    "\n",
    "Now your terminal has some added functionality and looks fabulous. Great! There is one more thing we should install to make our lives a little easier. I'm not a huge fan of having a ton of terminal windows open all over the place, which can easily happen when running multiple projects. Instead I recommend using a terminal splitter or multiplexer. For this tutorial I recommend [tmux](https://github.com/tmux/tmux/wiki).\n",
    "\n",
    "### <font color=lightblue> Tip:</font>\n",
    "There are plenty of plugins for Z shell such as: autocomplete, syntax highlighting, and git. I encourage you to look into some of these as they may make your life much easier!\n",
    "\n",
    "### Tmux\n",
    "\n",
    "Tmux allows you to switch between several programs in the same terminal. Tmux comes with its own set of shortcuts and commands. I will list a few here, but would recommend altering your \"tmux.config\" file to make shortcuts to your liking. I will list commands that I have altered in parenthesis. All tmux shortcut commands start with the key combo `ctrl + b`, so I will write this command in brackets so you know they should be hit together first before finishing a command\n",
    "\n",
    "`tmux` - starts a tmux session\n",
    "\n",
    "`tmux new-session -t name` - starts a new session with the tag \"name\"\n",
    "\n",
    "`tmux ls` - lists all current tmux sessions\n",
    "\n",
    "`[ctrl+b] \"`<font color=blue>( `-` )</font> - splits the window horizontally\n",
    "\n",
    "`[ctrl+b] %`<font color=blue>( `/` )</font> - splits the window vertically\n",
    "\n",
    "`[ctrl+b] arrow` - moves focus to pane in the direction of the arrow key that is pressed\n",
    "\n",
    "`[ctrl+b] d` - detaches current session\n",
    "\n",
    "`tmux a -t name` - reattaches session \"name\"\n",
    "\n",
    "`exit` - closes current pane (if only one pane then it kills session)\n",
    "\n",
    "There are many more commands that can be found at the link above, but these should get you through most of the daily functionality. \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Automation \n",
    "\n",
    "Now that our terminal has all the necessary equipment we can start tweaking things to improve our workflow, starting with our \"rc\" file.\n",
    "\n",
    "### .zshrc / .bashrc files\n",
    "\n",
    "The \".zshrc\" (default \".bashrc\" file if not using z shell) is a hidden bash script that is run when a terminal is opened. It is a powerful tool for adding default behavior you want integrated in your terminal as well as any aliases you may want to set up. An alias is a reference type function that when typed executes it's definition. We can edit the .zshrc file to include useful aliases that reduce the amount of typing we do.\n",
    "\n",
    "For example, suppose you have built a code package from source, then you have chosen to modify the code in some way. This means that for your changes to take effect you may need to \n",
    "\n",
    "1. enter the build folder\n",
    "2. compile the code again\n",
    "3. build the code\n",
    "\n",
    "which can be a bit tedious if you are making modifications fequently. Instead of always having to run \n",
    "```bash\n",
    "cd /path/to/program/build\n",
    "make -j4\n",
    "sudo make install\n",
    "``` \n",
    "we can make an alias that does this for us. In the rc file we will add lines that look like this:\n",
    "```bash\n",
    "### Alias to build program ###\n",
    "alias makeprogram=\"cd /path/to/program/build && make -j4 && sudo make install && cd -\"\n",
    "```\n",
    "   <font color=red>Note:</font> When writing shell commands `&&` separates commands so you can write multiple on a single line. In this example the make command is given the flag `-j4` which tells the computer how many CPU \"cores\" to use for compiling. Lastly, the \"make install\" command is preceded by `sudo` which means this will be run as \"root\" or as the \"Administrator,\" which has more privileges and will install the program system-wide.\n",
    "    \n",
    "Then running `source ~/.zshrc` in terminal will reload our rc file and running `makeprogram` in terminal will change your build directory, recompile the program, build it, and return you to the directory you were originally in!\n",
    "\n",
    "You can also make less involved aliases. Suppose you are terrified of nuking an important document. We can write `alias rm=\"rm -i\"` so that we can't accidently delete things without verification through the terminal. \n",
    "\n",
    "Or suppose you are a good programmer and back your code up to some repository, but get sick of typing `git push origin master`, we can alias this to something shorter like `gpom`. \n",
    "\n",
    "Really the options are limitless.\n",
    "\n",
    "### Bash functions\n",
    "\n",
    "You can also include functions in your rc files. I will give an example of one shortly that makes working remotely much easier. My goal with this is to make you aware of a toolkit that is available to you, but detailed functions are well beyond the scope of these tutorials."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Working remotely\n",
    "\n",
    "Much of what we do is possible through offloading much of the computational burden on remote workstations, clusters, etc. We need to know how to interface with them. In order to log onto a remote system you will first need to know the systems IP address. This can be accessed through the terminal using `hostname - I`. \n",
    "\n",
    "I will use the cluster SHEAR as an example for these commands, but these are generalizable for all remote systems.\n",
    "\n",
    "Logging into a remote server is done through the `ssh` command. So for you to log into a server it would look something like `ssh username@IPaddress` or `username@shear.che.caltech.edu`, for our example system.\n",
    "\n",
    "Upon connecting with the remote server you will be prompted for your password to log in. Once that is successful you will be interfacing with the remote server through the terminal (which is why we built our command line skills up earlier).\n",
    "\n",
    "Now if you are going to be consistently logging into your remote device from your current host device, you may want to set up an SSH key so that you don't have to type your password in each time you log onto your account (on remote) from your device (local). To that we will execute the following:\n",
    "\n",
    "```bash\n",
    "ssh-keygen -t rsa\n",
    "ssh username@remote mkdir -p .ssh\n",
    "cat .ssh/id_rsa.pub | ssh username@remote 'cat >> .ssh/authorized_keys'\n",
    "```\n",
    "\n",
    "Now you can log onto your remote device without typing in your password!  <font color=blue>NOTE:</font> Once you have generated an SSH key on your local device, you do not need to generate a new one for additional systems that you wish to log onto without password. For this you only need to append the ssh key onto the authorized key file that is on the remote machine (i.e. follow the last two lines of code written above).\n",
    "\n",
    "You can take this a step further by aliasing the ssh command \n",
    "\n",
    "`alias remote='ssh username@remote'`, \n",
    "\n",
    "which really streamlines the process.\n",
    "\n",
    "Now that we can easily log onto our host device we need to get scripts onto the device to run. We will use \"scp\" to copy files from our local device to the remote device.\n",
    "```bash\n",
    "scp file username@remote:/path/where/I/want/code/to/go/\n",
    "```\n",
    "\n",
    "Once our code is there we can run it either from the command line (or from VS code as in Tutorial-3). Once we have run our code we probably want the data back so we can look at it. To copy files back we just run \n",
    "```bash\n",
    "scp username@remote:/path/where/data/is/data .\n",
    "```\n",
    "from our local terminal and this should place the file \"data\" in our current directory on the local machine.\n",
    "\n",
    "**<font color=blue>NOTE:</font>** You should also look into using [rsync](https://rsync.samba.org/) instead of scp as it is faster and has some nice features. Most of the commands will be the same or very similar to those shown above.\n",
    "\n",
    "### Running long jobs remotely\n",
    "What if you want to run a fairly long job from your laptop? Well unfortunately if we just run the code and close our laptop or device to go home for the day then this will kill the connection to the server and our session will end, thus killing our program. There are a few ways to get around this of course. The first is to use the `nohup` command followed by the command you would normally execute from the terminal. This has some challenges since you need to have any command line output save to a file, and in general can be a bit tricky to check on your program's progress. It just so happens that we can also use tmux! If tmux is installed on the remote device then we can\n",
    "1. ssh onto the remote host\n",
    "2. begin a tmux session\n",
    "3. start running our code\n",
    "4. detach the session\n",
    "\n",
    "After doing these things we can kill the ssh connection and when we want to check on our status we just log back onto the remote host and reattach the session! It makes working from multiple machines very simple. Especially if you are working on a cluster.\n",
    "\n",
    "### Remote jupyter notebooks\n",
    "Now suppose we want to do some data processing or early visualization before transferring files back over to our local device. We can actually start a jupyter notebook instance on our remote device and visualize it locally. [Here](https://benjlindsay.com/blog/running-jupyter-lab-remotely/) is a link to a great set of bash functions that can be placed in your rc file to make this process very simple!\n",
    "\n",
    "On our remote server let's define an alias `alias jlremote='jupyter lab --no-browser --port=8888'` for part of our function. We can run this alias in a persistent tmux session that we just detach on the remote device (<font color=red>NOTE:</font> we can choose any port we want, but need to be consistent with the choice across all instances of it).\n",
    "\n",
    "Next on our local side we will place a function on our .zshrc or .bashrc file (depending on the shell you are using).\n",
    "\n",
    "```bash\n",
    "function jllocal {\n",
    "  cmd=\"ssh -Y -fN -L localhost:8888:localhost:8888 USERNAME@HOSTNAME\"\n",
    "  running_cmds=$(ps aux | grep -v grep | grep \"$cmd\")\n",
    "  if [[ \"$1\" == 'kill' ]]; then\n",
    "    if [ ! -z $running_cmds ]; then\n",
    "      for pid in $(echo $running_cmds | awk '{print $2}'); do\n",
    "        echo \"killing pid $pid\"\n",
    "        kill -9 $pid\n",
    "      done\n",
    "    else\n",
    "      echo \"No jllocal commands to kill.\"\n",
    "    fi\n",
    "  else\n",
    "    if [ ! -z $n_running_cmds ]; then\n",
    "      echo \"jllocal command is still running. Kill with 'jllocal kill' next time.\"\n",
    "    else\n",
    "      echo \"Running command '$cmd'\"\n",
    "      eval \"$cmd\"\n",
    "    fi\n",
    "    url=$(ssh USERNAME@HOSTNAME \\\n",
    "            '/REMOTE/PATH/TO/jupyter notebook list' \\\n",
    "            | grep 8888 | awk '{print $1}')\n",
    "    echo \"URL that will open in your browser:\"\n",
    "    echo \"$url\"\n",
    "    open \"$url\"\n",
    "  fi\n",
    "}\n",
    "```\n",
    "\n",
    "This program, when executed with `jllocal` will\n",
    "1. ssh onto the remote device\n",
    "2. grab the token of the jupyter instance\n",
    "3. open a tab in your local browser.\n",
    "\n",
    "When you are done using the remote session you can run `jllocal kill` on your local machine to end the session. \n",
    "\n",
    "\n",
    "Hopefully these few things have been helpful in allowing you to take ownership of your terminal and really tailor it to your needs and uses!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Written by: adulaney"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "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.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}