Installation of a Vagrant machine

Installation of a Vagrant machine

Hans Petter Langtangen [1, 2] (hpl at

[1] Center for Biomedical Computing, Simula Research Laboratory
[2] Department of Informatics, University of Oslo

Jun 11, 2014

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.

Installation instructions

Notation. In the following, the prompt 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 Vagrant. Those who work on a Windows machines will select VirtualBox x.y.z for Windows hosts, which downloads an .exe file which can just 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 should 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 in the vagrant directory. The file is big, 5 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 scientific_computing
Terminal> vagrant init scientific_computing
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/ 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)

Save the file. Move to the terminal window with the Ubuntu (Vagrant) machine. Run

Machine> cd /vagrant/projects
Machine> python

You should see a plot of \( e^{-x} \) on the screen. If you encounter any problems, read the section Troubleshooting.

Working with the Vagrant machine

The daily work with the Vagrant machine is very easy. Simply go to the 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.

Shared directories

Inside the Vagrant machine, /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

import numpy as np
import matplotlib.pyplot as plt
x = np.linspace(0, 3, 11)
y = np.exp(-x)
plt.plot(x, y)

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

Terminal> cd /vagrant
Terminal> cd src
Terminal> python

A plot of the curve \( y = e^{-x} \) should now be seen on the screen.


Troubleshooting: shared directory is invisible

It may happen that the /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.

Troubleshooting: "couldn't connect to display ..."

This error message points to the problem that X11 graphics on the Vagrant machine cannot be shown on the host's screen. Inserting the line 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).

Troubleshooting: Internet is not reachable

A test if Internet is reachable is to run a ping command inside the machine, e.g.,

Machine> ping

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.

Stopping the Vagrant machine

There are three ways to stop the virtual Vagrant machine from the host (i.e., you must be logged out by Ctrl-D from the machine):