OpenKIM Pipeline Resources

The heart of the OpenKIM Pipeline is the computational resources which have been donated to the project across the world. To maintain a consistent running environment we have developed a single virtual machine or live environment on which to run. You can find descriptions and download links for these VMs in the left tabs. Please note that following one of the download methods (Vagrant, VirtualBox, LiveCD) is sufficient to get started. They provide different ways to access the same virtual machine.


Vagrant boxes and Virtual Machines

NOTE: this method automates the download and setup of VirtualBox harddrive found in the section VirtualBox. You do not need to do both.

Our primary means of development and launching workers for the pipeline is through the virtual machine manager known as Vagrant. At their site, you can find documentation detailing how it works. In addition, vagrant requires a Virtual Machine backend where you can choose one of Virtual Box or VMware. To begin, download both vagrant and one of the supported backends. For brevity, we provide a short synopsis on how to use vagrant.

Vagrantfiles and boxes

Vagrant is a program that is able to take a snapshot of a VM and package it into a box for distribution to other machines. These boxes can be used locally or added from a url. They specify the entire operating system at a particular snapshot.

On top of this, additional configuration is provided by a Vagrantfile. This tells vagrant how to provision the base operating system to add virtual folders, forward ports, or change the amount of RAM and disk space to use. The Vagrantfile also specifies the base box to use.

Vagrant commands

To interact with a vagrant machine, you need to first make a new directory, grab a Vagrantfile, then run

vagrant up
This command downloads the appropriate box from pipeline.openkim.org, sets up a virtual machine using your favorite provider (for instance VirtualBox), provisions, boots, and sets up the entire OS.

From there, you can run

vagrant ssh
to login into the box. When you are done using the box, you can logout and shut it down using
vagrant halt
If you want to ever completely get rid of the box, you can delete it along with all of its hard disks by calling
vagrant destroy

Download

To get our box, grab the Vagrantfile!


VirtualBox

NOTE: download and setup of the VirtualBox harddrive can be done automatically using Vagrant. Information on how to do so is found in Vagrant VM. You do not need to do both.

VirtualBox (VB) provides an easy route to virtualization, or running an entire guest operating system within you host operating system. You can learn about it and download the software from here

Download the harddrive

One of the methods we support for creating a virtual machine is directly downloading a copy of our VB harddrive, a vmdk file. The link to download is found at the bottom of this page. Once downloaded, follow the instructions below to initialize the machine.

Creating a guest system

Once you have downloaded both VB and our vmdk harddrive, start up VB. You will be greeted with a screen that looks like this:

Next, click the blue "New" button in the toolbar to create a new virtual machine (VM). Hit next to proceed to the wizard. Give the VM a name and choose the operating system as Linux, Ubuntu 64-bit.

Next, choose the amount of RAM you want to dedicate to your machine. A safe amount is 512MB, but you are welcome to select higher amounts depending on your host machine.

After that, we want to choose the harddrive for our VM. This is the one that you have already downloaded. Select "Use existing hard disk" and locate the openkim-vm-<version>.vmdk file on your host hard drive.

Finally, select 'Create' and your VM should ready to run. Highlight in the list and click start. After a little while, the VM should have booted. At this point, there are almost no packages on your virtual machine.

To fix this, we need to download the current version of openkim setup scripts. There is a script located at /pipeline/runsetup. To run, execute

sudo /pipeline/runsetup
If you want to obtain the August 2014 KIM Boot Camp version of the pipleline setup use the following command instead:
sudo /pipeline/runsetup bootcamp-aug-2014
At this point, you should have a ready-to-go OpenKIM Virtual Machine.

Setting up shared folders

When not going through Vagrant, file sharing with the host system is not set up by default. To enable this easy method of file transfer, we need to set up a shared folder. First, in the Virtual Machine, we have to install the appropriate Guest Additions by running the commands

sudo apt-get update
sudo apt-get install virtualbox-guest-utils
Next, in the settings for the VirtualBox interface, navigate to the settings for the Virtual Machine

Under the Shared Folders tab on the left, locate the icon of a folder with a plus symbol to add a new shared folder. A new dialog should pop up after clicking this icon. In the Folder Path heading, select the drop down which will allow you to select which folder on the Host machine you want to share. The Folder Name heading indicates the name visible to the Guest machine. For this, I have chosen share.

After selecting the option to make this a permanent folder share (persisting between reboots), select the OK dialog box and OK again in the settings folder. Back in the Virtual Machine, you should next mount the new shared folder. To do so, create a folder on the Guest that you want to share with the Host machine and mount it by running the following commands:

sudo mkdir /media/share
sudo mount -t vboxsf share /media/share -o rw,uid=1000,gid=1000
After this has been done, any files which are copied into the "Folder Path" you specified above on the Host machine will be visible from the folder you mounted on the Guest (/media/share/ in this example), and vice versa.

Better user interfaces

Admittedly, the user interface provided by tty terminals is sort of hard to use day-to-day. There is no built in scrolling, and the default size is quite small. However, by default, there is no X11 shipped with the OpenKIM VM - doing so would cause the size to balloon by a factor of 2. There are ways around this limitation though.

The first way is to SSH into the box and interact with the VM through your favorite terminal application. To do so, enable port forwarding of SSH from port 22 on the guest to a port, $PORT, on the host. You can find this option in the VM settings under network.

Next, you need to set a password for the openkim user by running sudo passwd openkim. Finally, in your terminal, you can log in to the VM using ssh -p $PORT openkim@localhost.

The other option is if you would like a graphical user interface, you can install it by issuing the commands

sudo apt-get update
sudo apt-get install virtualbox-guest-utils virtualbox-guest-x11 virtualbox-guest-dkms
sudo apt-get install xfonts-100dpi  # optional - courier fonts
sudo apt-get install ubuntu-desktop  # install the actual desktop
sudo apt-get clean  # IMPORTANT!
sudo passwd openkim  # set a password
sudo reboot
You should now be on the desktop.



OpenKIM LiveCD

NOTE: this method is intended for advanced users. Recommended alternatives are provided using Vagrant VM and VirtualBox.

Since it is sometimes more convenient to run a machine on 'bare metal' instead of through virtualization, we have provided an option to install to a bare disk or run as a Live CD such as though found in your favorite Linux distribution. It is the exact same as the machine provided through Vagrant, but without running through a VM. That being said, you can certainly still launch the live cd inside of a virtual machine and run that way

With the ISO, you can install to a USB using your favorite method:

From there, you can simply boot from the drive just like any other operating system