Creating and Running VM

In the following, “host” refers to the physical computer that you are working on (your laptop in most cases). “VM” refers to a virtual machine, which each of you will use for this course. Everyone should use the standard VM setup for the course—you’ll get access to all the tools and datasets with minimal effort. You have two options:

  • Local VM using Vagrant with VirtualBox: Here, the VM will run on your own computer. This option is recommended because of it provides the convenience of sharing files between your computer and the VM transparently, as well as a GUI when you need it.
  • Remote VM using Vagrant with Amazon AWS: Here, the VM runs remotely on Amazon’s cloud. You should consider this option if you find the local option to be too slow on your computer. You might also want to consider this option if you want to access your VM from anywhere. However, you won’t be able to work offline without an Internet connection, and it will be difficult to access GUI-based programs on your VM.

It is possible to run both options. If you want to pursue that option, you should use two separate directories on your host, one for each setup, with its own Vagrantfile (details below).

In the following instructions, we will frequently refer to a host “shell” (see also Shell Basics). If your host runs Mac or Linux, you get a shell with the Terminal application. If your computer runs Windows, we recommend installing MobaXterm; see Prerequisites below for installation instructions.

Prerequisites

  1. Download and install the latest version of VirtualBox. Make sure you also install the extensions.
  2. Windows users only: You need a shell and a command-line ssh client. We highly recommend installing MobaXterm, which includes a shell, ssh, as well as an X server (which you will need in order to access GUI-based programs on your VM).
    • Start MobaXterm, go to Settings -> Configuration -> Terminal (tab), and enable “Append Windows PATH environment variable…” You will need to quit and restart MobaXterm for the change to take effect and for newly installed Windows programs to be recognized as available commands.
  3. Download and install Vagrant.
    • If you choose the remote option, you also need to install the Amazon AWS plugin for Vagrant. Get a shell on your host and issue the following commands:
      vagrant plugin install vagrant-aws
      vagrant box add dummy https://github.com/mitchellh/vagrant-aws/raw/master/dummy.box
      vagrant plugin install vagrant-awsinfo

Creating a Local VirtualBox VM

  1. Create a directory on your host—it will hold files that are automatically shared between your host and VM. Pick a convenient location, say 216, for example. Download the file named Vagrantfile from http://www.cs.duke.edu/courses/spring17/compsci216/vb/Vagrantfile and save it in this directory. Do NOT rename the file.

    One of the most common problem people encounter is that some browser (e.g., Safari) automatically adds an .txt extension to Vagrantfile when you download this file. That will cause all sorts of issues that are hard to recover from later on. So, after you download the file, open up the containing folder and double-check that the file has no suffix at all.

  2. Get a host shell and change into the directory with the Vagrantfile. Then, type this command to create (and start) the VM:
    vagrant up
    The first time it runs it will create the VM from scratch, which takes some time. (The same command will be used to restart an existing VM that has been previously stopped; that will be much faster.) As the VM starts, VirtualBox will also present you with a window showing the VM login prompt; you should just ignore that for now.
  3. From your host shell, log into your VM (if you use Windows and MobaXterm, see Accessing VM for instructions on shell access):
    vagrant ssh
    You should now be in your VM shell. Follow the instructions for Readying Your VM for the Course.
  4. You now need to reboot your VM. Exit from from your VM shell (using the exit command), get back to your host shell, and then issue the following commands (wait for some time between the two commands):
    vagrant halt
    vagrant up
  5. You should now be able to access your course-ready VM in two ways:
    • In your host shell, use the command vagrant ssh. This gives you a text-based VM shell.
    • From the VirtualBox window showing the VM desktop, you can login as user vagrant and password vagrant. This mode of access is useful if you want to use GUI-based programs in your VM.

Inside your VM, you will find a subdirectory (actually, a symbolic link) named shared under your VM home directory. It mirrors all files on your host under the directory with the Vagrantfile. Therefore, you can create/view/edit such files on your host using your favorite software; the VM will automatically see any changes you make. Conversely, if you do your work under the shared directory in your VM (such as producing an output file by running a script in your VM), you will see the changes in your host’s file system as well.

Creating a Remote Amazon VM (NEEDS TO BE FIXED … MOVE TO GOOGLE)

  1. Create a directory on your host. Pick a convenient location, say 216, for example. Download the file named Vagrantfile from http://www.cs.duke.edu/courses/spring15/compsci216/aws/Vagrantfile and save it in this directory. Do NOT rename the file.

    One of the most common problem people encounter is that some browser (e.g., Safari) automatically adds an .txt extension to Vagrantfile when you download this file. That will cause all sorts of issues that are hard to recover from later on. So, after you download the file, open up the containing folder and double-check that the file has no suffix at all.

    Use a text editor to modify Vagrantfile and replace the following values with correct ones, obtained by following the instructions at Getting Started with Amazon AWS under “Getting Ready”:
    aws.access_key_id = "ABCDEFGHIJK123456789"
    aws.secret_access_key = "abcdefghijklmnopqrstuvwxyz01234567890abc"

    Then, follow the instructions at Getting Started with Amazon AWS under “Getting Ready” to to obtain a key pair and save the file datacourse.pem in the same directory as the Vagrantfile.

  2. Get a Terminal on your host and change into the directory with the Vagrantfile. Then, type this command to create the VM:
    vagrant up --provider=aws
    The command may hang at the step “default: Waiting for SSH to become available”: this is expected since by default Amazon VMs does not accept incoming connections. To fix this, follow the instructions from Getting Started with Amazon AWS, under “Useful Tasks,” to edit your Amazon security settings to enable incoming SSH access.
  3. Wait for a few minutes after the VM has been created. Then, log into your VM (if you use Windows and MobaXterm, see Accessing VM for instructions on shell access):
    vagrant ssh
    You should now be in your VM shell. Follow the instructions for Readying Your VM for the Course.
  4. You now need to reboot your VM. Exit from from your VM shell (using the exit command), get back to your host shell, and then issue the following commands (wait for a few minutes between the commands):
    vagrant halt
    vagrant up
  5. You should now be able to access your course-ready VM using vagrant ssh.

Your Amazon VM is completely separate from your host. The files on our Amazon VM do NOT live on your host. For text files (including code), you can just view/edit them inside the VM shell. If your work requires a GUI program (e.g., viewing PDF, or using a Web browser to WebSubmit), you must either 1) download relevant files to your host, work on them, and then upload any edited files back to your VM; or 2) install X windows on your host, so you can run GUI programs on your VM and have them display on your host. See VM and Linux Primer for tips.

Common Vagrant Tasks

All commands below should be issued from a host shell, when you are inside the directory containing the Vagrantfile.

Starting the VM:
vagrant up
If you have previously stopped your VM, you need this command above to restart it before you can accessing it. You might have to wait for a bit before it is ready to accept connections.

Checking the VM status:
vagrant status

Accessing the VM:
(If you use a Windows host and MobaXterm, see Accessing VM for instructions.)

For basic command-line shell access:
vagrant ssh
You shouldn’t need a password. If successful, you will be now be inside a shell on your VM. If this command hangs, hit Ctrl-C to get back to your host shell prompt, and check the VM status to see if it is ready. For additional connection options, see Accessing VM.

Stopping the VM:
vagrant halt
Unless explicitly stopped using the above command, your VM will keep running, which will either slow your computer down (if it is a VirtualBox VM) or continue to incur Amazon charges (if it is an Amazon VM). Thus, we recommend that you stop your VM when you are not working on it (unless it is an Amazon VM running a web server that you want others to access all the time).

You can completely destroy your VM using another command called vagrant destroy, but you will lose everything stored in your VM’s file system. Do NOT use this command unless you really want to get rid of the VM and all its data (e.g., when you finish this course).