A Vagrant machine is a file that you can download and install on your laptop to get access to a complete Ubuntu computer in a Mac or Windows environment. You write programs in your host system (Mac or Windows), but run them in an Ubuntu environment.
Terminal> indicates a Unix terminal
window on Mac or a Command Prompt window on Windows. The prompt
Machine> indicates a terminal window where Ubuntu is running (in a
Vagrant machine).
Step 1.
Download and install VirtualBox. Choose the version
according to the operating system on the host.
For example, if you want to build or run Vagrant machines under Mac OS X, choose
VirtualBox x.y.z for OS X hosts, where x.y.z is the version number
of VirtualBox. Double click the downloaded .dmg file to install
VirtualBox. Those who work on a Windows machine will select VirtualBox
x.y.z for Windows hosts, which downloads an .exe file to be
double clicked to perform the installation.
Step 2.
Download and install Vagrant.
Choose the latest version and the installation file corresponding to
the host's operating system (where you installed VirtualBox). On a Mac, you
select the Vagrant-x.y.z.dmg file (x.y.z denotes the version of
the software), on Windows the Vagrant_x.y.z.msi file is the
relevant choice.
On Ubuntu, select vagrant_x.y.z_*.deb and install it
by sudo dpkg -i vagrant_x.y.z_*.deb.
Step 3 for Windows users. If you have a Windows machine, you must install Cygwin. Download the Cygwin's setup.exe file and follow the instructions given by the installer. Make sure you manually select the 'X11' category during installation. Notice that downloading Cygwin might take one or more hours, depending on the speed of your network. Cygwin is not needed on Mac computers.
Step 4. Start X11: run Applications - Utilities - X11 on a Mac, or Start - All Programs - Cygwin-X - XWin Server on Windows.
Step 5.
Move to your home directory and make a new directory
vagrant and a subdirectory projects:
Terminal> cd
Terminal> mkdir vagrant
Terminal> mkdir vagrant/projects
Terminal> cd vagrant
All files that you run from the Vagrant machine are supposed
to reside in vagrant/projects and its subdirectories.
Step 6.
Download the file from and store it as
inf1100.box in the vagrant directory. The file is big,
2.7 Gb, and may take hours to download.
Make sure you have a stable Internet connection and that you do not
bring your computer to sleep before the complete file is downloaded.
Step 7.
Make sure you stand in the vagrant directory.
Run
Terminal> vagrant box add INF1100 inf1100.box
Terminal> vagrant init INF1100
Terminal> vagrant up
Terminal> vagrant ssh
You are now inside a full-blown Ubuntu system with all software you need for the course.
Step 8.
Open a file vagrant/projects/test1.py in a text editor on the host system
and write the following lines in the file:
import numpy as np
import matplotlib.pyplot as plt
x = np.linspace(0, 3, 11)
y = np.exp(-x)
plt.plot(x, y)
plt.show()
Save the file. Move to the terminal window with the Ubuntu (Vagrant) machine. Run
Machine> cd /vagrant/projects
Machine> python test1.py
You should see a plot of \( e^{-x} \) on the screen. If you encounter any problems, read the section Troubleshooting.
vagrant
directory where the machine resides and run
Terminal> vagrant up
Terminal> vagrant ssh
You are now inside the machine and can reach
files on the host from
/vagrant/projects (see the next section for more details).
Log out with Ctrl-D and in again with vagrant ssh.
Create and edit files on the host in ~/vagrant/projects and its
subdirectories.
Before closing a laptop or shutting it down, it is recommended
to log out of the Vagrant machine and run vagrant suspend.
/vagrant is a directory shared with the
user's file system. More precisely, /vagrant points to the project
directory where the file Vagrantfile resides and where the vagrant
up command was run (~/vagrant if you have followed the specific
directory naming suggested in this document).
If users of the Vagrant machine keeps all their
files relevant for the machine in the project directory and its
subdirectories, all these directories will be shared between the machine and
the user's file system. Normally, this feature is enough for efficient
communication of files between the Vagrant machine's file system and
the user's file system. One can also set up other shared directories, see
the Vagrant documentation for Synced Directories.
Since the Vagrant machine shares directories with the host system, users can safely edit files in the shared directories with their favorite editor on the host system. The Vagrant machine will have immediate access to the files.
Here is a typical example. Assume that vagrant up and vagrant ssh
were run in a directory myubuntu. On the host,
create a subdirectory src of myubuntu. Start an editor and type in
the following Python program in a file test1.py:
import numpy as np
import matplotlib.pyplot as plt
x = np.linspace(0, 3, 11)
y = np.exp(-x)
plt.plot(x, y)
plt.show()
This program will show X11 graphics on your host machine. If this machine
runs the Linux operating system, everything is fine, but if this is a Mac
or Windows machine, X11 must be started as described in Step 4 of
the installation instructions. If that is necessary, log out, start X11,
log in again (vagrant ssh).
Run the test1.py program:
Terminal> cd /vagrant
Terminal> cd src
Terminal> python test1.py
A plot of the curve \( y = e^{-x} \) should now be seen on the screen.
/vagrant directory seems empty inside
the Vagrant machine. Two steps will fix this problem. First,
run
Machine> sudo /etc/init.d/vboxadd setup
inside the Vagrant machine. Second, log out and run
Terminal> sudo vagrant reload
outside the Vagrant machine.
Then do vagrant ssh and take an ls /vagrant to see that the
files in the project directory (e.g., Vagrantfile and the Vagrant
box) are visible.
config.ssh.forward_x11 = true
in the file Vagrantfile in the project directory and starting X11
on the host are the two steps that will fix the problem.
Unless you build a Vagrant box, the editing of Vagrantfile should
not be required as a ready-made box was packaged with
X11 forwarding (cf. the vagrant package command
in the section ref{vagrant:complete:install}).
To start X11 on Mac,
run Applications - Utilities - X11, while on Windows, go to
Start - All Programs - Cygwin-X - XWin Server. Log out of the
Vagrant machine (Ctrl-D) and in again (vagrant ssh).
ping command inside
the machine, e.g.,
Machine> ping us.ubuntu.archive.com
A hanging command indicates that Internet is not reachable.
Log out of the box, run vagrant reload, and
vagrant ssh. Try the ping command again.
vagrant suspend sends the machine to sleep mode. Waking it up is
done with vagrant up.vagrant halt shuts off the machine. To start it again, a full
boot with vagrant up is needed.vagrant destroy.