Creating and Running VM

UNDER CONSTRUCTION

Everyone should use the standard VM setup for this course. You’ll get access to all the tools (relational algebra, database systems, project support) 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.
  • 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 construct a website that’s publicly visible at all times (even in that case, we still recommend a local VM for homework as well as project development and testing—you only roll out your production website to Amazon).

In the following instructions, we will frequently refer to “shell” on your host (computer). If your computer runs Mac or Linux, you get a shell with the Terminal application. If your computer runs Windows, we recommend “Git Bash” that comes with msysgit; 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 msysgit, which includes a shell, ssh, as well as git (which you will likely use at some point anyway)! With msysgit, you can get a shell on your Windows host by right clicking your mouse on the desktop, and selecting “Git Bash” from pop up window.
  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 command:
      vagrant plugin install vagrant-aws

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 316, for example. Download the file named Vagrantfile from http://www.cs.duke.edu/courses/fall14/compsci316/vb/Vagrantfile and save it in this directory. Do NOT rename the file.
  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 is used to restart an existing VM that has been previously stopped, and that will be much faster.)
  3. Log into your VM:
    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 commands):
    vagrant halt
    vagrant up
  5. You should now be able to access your course-ready VM using vagrant ssh.

Inside your VM shell, 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

  1. Create a directory on your host. Pick a convenient location, say 316, for example. Download the file named Vagrantfile from http://www.cs.duke.edu/courses/fall14/compsci316/aws/Vagrantfile and save it in this directory. Do NOT rename the file. 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 dbcourse.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
  3. Wait for a few minutes after the VM has been created. Then, log into your VM:
    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. To work with files on your Amazon VM, you can either view/edit the files inside the VM shell, or you can download them to your host, work on them, and then upload any edited files back to your VM. See VM and Linux Primer for tips. To submit files inside your Amazon VM for grading, you will need to download them first to your host and then submit them (because you cannot run a web browser inside the VM shell).

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:
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.

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).