HOWTO - CSI 702 - Setting up your virtual machine

• Installing Virtualbox and Vagrant
  • Windows
  • macOS
  • Ubuntu
• Provisioning the virtual machine
• Install conda environment
• Basic usage
• References

Installing Virtualbox and Vagrant

Windows

Instructions below adapted from Ref. [1].

1. Install the latest versions of the following software:

   • Git: https://git-scm.com/downloads. Near the end of the install, select the option Windows Explorer integration so that Git Bash Here is added to your right-click menu.

   • Virtualbox: https://www.virtualbox.org/wiki/Downloads. The default settings are fine.

   • Vagrant: https://www.vagrantup.com/downloads.html. The default settings are fine.

   After installing Vagrant, you will need to reboot your computer.

2. Open Git bash by right-clicking your desktop or the white space inside a folder (Windows file explorer) and clicking Git Bash Here. If this is your first time using git on your Windows machine, you should set your user information by running these two commands:

   git config --global user.name "FirstName LastName"
   git config --global user.email "[email protected]"

   Replace FirstName LastName and [email protected] with your own information.

macOS

Open a terminal window and follow the instructions below. Instructions adapted from Ref. [2].

1. Xcode must be installed before you can do anything else. You can install Xcode by either downloading it from Apple's website, https://developer.apple.com/xcode/, or by running the following command in the terminal:

   xcode-select --install

2. (Possibly optional) Install XQuartz by downloading the dmg file from the project's website: https://www.xquartz.org/

3. Install Homebrew if it is not currently installed on your computer:

   ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

   Check your $HOME/.bash_profile file and see if /usr/local/bin is set in your $PATH environment variable. If it is not, run echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile to append a command that will set it. Close and reopen your terminal window after doing this.

   To check that everything is working, run brew doctor. For basic information on what you can do with Homebrew, see this page: http://sourabhbajaj.com/mac-setup/Homebrew/Usage.html.

4. Install Homebrew-Cask if it is not already installed:

   brew tap caskroom/cask

5. Install git using Homebrew:

   brew install git

6. If this is your first time using git, you should set your user information by running these two commands:

   git config --global user.name "FirstName LastName"
   git config --global user.email "[email protected]"

   Replace FirstName LastName and [email protected] with your own information.

7. Install Virtualbox using Homebrew-Cask:

   brew cask install virtualbox

8. Install Vagrant using Homebrew-Cask:

   brew cask install vagrant
   brew cask install vagrant-manager

Ubuntu

1. Install git and openssh-client if you haven't already:

   sudo apt-get update
   sudo apt-get install git openssh-client

2. If this is your first time using git, you should set your user information by running these two commands:

   git config --global user.name "FirstName LastName"
   git config --global user.email "[email protected]"

   Replace FirstName LastName and [email protected] with your own information.

3. Install the latest version of Virtualbox:

   wget -q https://www.virtualbox.org/download/oracle_vbox_2016.asc -O- | sudo apt-key add -
   wget -q https://www.virtualbox.org/download/oracle_vbox.asc -O- | sudo apt-key add -
   sudo add-apt-repository "deb [arch=amd64] http://download.virtualbox.org/virtualbox/debian $(lsb_release -cs) contrib"
   sudo apt-get update
   sudo apt-get install virtualbox-6.0

4. Install the latest version of Vagrant:

   # Install gdebi if you haven't done so already
   sudo apt-get install gdebi
   # Download Vagrant
   wget https://releases.hashicorp.com/vagrant/2.2.3/vagrant_2.2.3_x86_64.deb
   # Install Vagrant with gdebi
   sudo gdebi vagrant_2.2.3_x86_64.deb

Provisioning the virtual machine

1. Create a folder for the class, for example:

   mkdir -p ~/Documents/class/csi702

   This will be the root folder for the virtual machine, so all files and directories related to the class will go under this folder.

2. Navigate to this GitHub Gist, https://gist.github.com/jkglasbrenner/a51b4de9a1088c7d8f6b5c5983738851, click Download ZIP and save the file to your class folder. Extract the file contents directly into the folder. You should now see the following files in your class folder:

   /path/to/class/folder
   ├── ansible.cfg
   ├── CSI702_provision_virtual_machine.md
   ├── DESCRIPTION
   ├── environment.yml
   ├── Makefile
   ├── playbook.yml
   ├── requirements.yml
   └── Vagrantfile  
   

   If the files were unzipped into a new directory, move them into the class folder. Do not delete these files after setup.

3. Download the official base image for Ubuntu 18.04:

   vagrant box add ubuntu/bionic64

4. Provision your virtual machine by running

   vagrant up

   This will take a while. Please note that this step needs to be done from within the class folder where you stored all the unzipped files.

5. After the provisioning is complete, you can connect to the virtual machine by running

   vagrant ssh

Install conda environment

1. After connecting to your virtInstall conda environmentual machine with vagrant ssh, run the following commands to set up your conda environment:

   cd /vagrant
   make all

   This will take several minutes to complete.

2. After make all is done, run:

   make clean

   This will remove anaconda's temporary files and free up some of your virtual disk space To disconnect from the virtual machine, run

Basic usage

After you install the conda environment, you are ready to start using your virtual machine in CSI 702. Below are a few tips and reminders that are specific to using a Vagrant-provisioned virtual machine. Otherwise, you are expected to be familiar with the basics of using a full Linux environment and navigating via the command line.

• The steps in the Install conda environment section created a conda virtual environment named csi702. To activate it, run:

  conda activate csi702

• The /vagrant directory is a shared folder. If you followed the above directions, you should see any files and folders inside the class directory you created earlier.

• You can serve a Jupyter Lab instance from within the virtual machine and access it using your host OS's web browser. The easy way to do this is:

  cd /vagrant
  make lab

  Open your web browser (Google Chrome or Firefox are recommended) and type localhost:8888 in your address bar and press Enter. To stop the Jupyter Lab instance, just press Ctrl+C and answer y to the disconnect prompt.

• To disconnect from your virtual machine, run:

  logout

• The virtual machine will run in the background of your computer until you shut it down. To shut down the virtual machine, from the class folder, run

  vagrant halt

  This can only be done after you've disconnected with logout.

• To restart the virtual machine after running vagrant halt, from the class folder, run:

  vagrant up

• To remove the virtual machine from your computer, from the class folder, run

  vagrant destroy

References

[1] http://ifcuriousthenlearn.com/blog/2015/08/18/vagrant-linux/
[2] http://sourabhbajaj.com/mac-setup/