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
- Download and install the latest version of VirtualBox. Make sure you also install the extensions.
- Windows users only: You need a shell and a command-line
ssh
client. We highly recommend installingMobaXterm
, 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 restartMobaXterm
for the change to take effect and for newly installed Windows programs to be recognized as available commands.
- Start
- 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
- 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:
Creating a Local VirtualBox VM
- 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 namedVagrantfile
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 toVagrantfile
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. - 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. - 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. - 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 - 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 passwordvagrant
. This mode of access is useful if you want to use GUI-based programs in your VM.
- In your host shell, use the command
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)
- Create a directory on your host. Pick a convenient location, say
216
, for example. Download the file namedVagrantfile
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 toVagrantfile
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 filedatacourse.pem
in the same directory as theVagrantfile
. - 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. - 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. - 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 - 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).