This document describes the process of setting up a VM running an OpenShift development environment inside VirtualBox.

You need to have a virtualization application such as KVM, or VirtuaBox installed on your workstation and you will need at least 25GB of free disk space. The compressed download is about 1.3GB and when you unpack it the resulting image file is almost 4GB vmdk file or 20 GB uncompressed RAW disk file (Linux only).

1. Download VM

Download the VM from the OpenShift "mirrors" site:

$ wget

2. Unpack VM files

The download package is a ZIP archive. Unpack it with `unzip`or your system’s archive utility.

$ unzip

This can take quite a while. The files being uncompressed are pretty large. The result will be the creation of four additional files:

$ ls -1t

3. Configure mDNS

The VM image is configured to use mDNS to provide DNS name resolution so that your browser and RHC client can resolve the URL of the broker and applications running on the VM. mDNS services are built-in on MacOSX (bonjour) and Windows (zeroconf) system, but require a few addition steps on Fedora 19 or other linux based systems.

  1. Install the mDNS resolver RPM:

    $ yum install -y nss-mdns
  2. Edit your /etc/nsswitch.conf file. Search for a list beginning with "hosts:" and add mdns4 to the end of the line. After the edit, it should look like:

    hosts:      files mdns4_minimal [NOTFOUND=return] dns myhostname mdns4

This will allow your browser and RHC client to properly resolve the hostname and application URLs.

4. Set up the Virtual Machine

The base VM image is distributed as a VMDK file and will run on a variety of virtualization technologies. Specific setup instructions are included below. Skip down to the one you intend to use.

  • libvirt/KVM - Kernel Virtual Machine (Linux)

  • VirtualBox - Process based virtualization (Linux, Windows, MacOS)

4.1. KVM

KVM or "Kernel Virtual Machine" (aka libvirt) is a Linux native virtualization mechanism. With KVM/libvirt installed on a Linux host you can run virtual machines for any Ix86 or x86_64 based operating system.

4.1.1. Installing KVM Tools

Start by installing the KVM/libvirt RPMs:

$ yum install -y virt-manager libvirt
This step may take a while depending on the speed of your internet connection.

4.1.2. Convert The Image

KVM requires a RAW disk image file. We can use qemu-img command to convert the VMDK image to RAW format.

Install the qemu-img RPM:

$ yum install -y qemu-img

Run qemu-img to convert the image file and then copy it into the libvirt directory.

$ qemu-img convert -O raw origin-release-3.vmdk /var/lib/libvirt/images/origin-release-3.dsk

4.1.3. Create New VM

Ensure that libvirt is running:

$ systemctl start libvirtd.service

Start virt-manager on the command line:

$ virt-manager

Once virt-manager starts, click on the "Create a new virtual machine" icon or right click on localhost and select New.


Enter "openshift_origin" as the name of the virtual machine, select "Import existing disk image" and click "Forward".


4.1.4. Select VM Disk Image

Select "Linux" as the "OS Type" and "Fedora 19" as the version then click "Browse…" to select the disk image.


Select the "openshift-origin.dsk" image and click "Choose Volume"


Once you are back to the setup screen, click "Forward".

4.1.5. Set VM Memory Size

Set the memory size to something reasonably large. 1GB should be a good start. Click the "Forward" button.


4.1.6. Set VM Memory Size

Select "Virtual Network default: NAT" network and click Finish to start the VM.


4.1.7. Starting the VM

When the VM has finished booting. It will go through some initialization and then present you with the URL a menu where you can start working with your VM.


4.2. VirtualBox

VirtualBox is a process based virtual machine system.

You can start VirtualBox either by clicking on the desktop item in the startup menus or from the command line:

$ virtualbox &

4.2.1. Create New VM

When you start VirtualBox and you should see the welcome page. Click the New button in the upper left to begin the process of creating creating a new VM and importing the OpenShift virtual disk.


Fill in the name. It feels like VirtualBox knows that things called "OpenShift" will be Linux, but you should change the version to Fedora (64 bit) and click Next.

4.2.2. Set VM Memory Size

VirtualBox gives some of your computer’s memory to the virtual machine. You want it to be large enough so that the machine runs well, but not so large that it consumes all of your computer’s memory.

Set the memory size to something reasonably large. 1GB should be a good start. Click the Next button.


4.2.3. Select VM "Hard Drive" Image

Normally Virtualbox will create a new virtual hard drive for you. In this case you want to select the virtual disk image which contains the OpenShift Origin virtual machine.

Check the radio button labeled "Use an existing virtual hard drive file" and click the little folder icon with the green circumflex in the lower right corner.


VirtualBox will present a file selection dialog. Browse to find the "openshift-origin.vmdk" file and select it. Press the button labeled "Open".


Press the button labeled "Open".


When the disk has been selected click "Create". VirtualBox will create the stopped virtual machine and present the VM manager display.


4.2.4. Add Bridged Networking

By default VirtualBox uses Network Address Translation (NAT) to create a virtual network interface for your virtual machines. NAT will not let you connect back into your virtual machine. You need to add a second network adaptor configuration to use Bridged networking. Then your virtual machine will get an IP address from your DHCP server, and you will be able to use that address to browse or log in.

Highlight the OpenShift virtual machine (if it’s the only one, it will be already) and click the Settings icon (shaped like a gear) in the upper left corner. When the Settings window opens, select Network in the settings list.


Leave Adapter 1 as NAT and select the tab for Adapter 2.

  1. First, check the Enable Network Adapter box, which will unlock the other adapter settings.

  2. Next, set the Attached to: value to "Bridged Adapter"

  3. Finally, set the Name value to the network adapter that you want to bridge.

Each system may have different names for their physical network adaptors.

Press "OK" to finish changing the VM settings and return to the main window. Highlight the OpenShift Origin VM in the left hand column and click the "Start" button. VirtualBox will display the VM console as a black window and you can observe the boot process.

Virtualbox may show several informational dialog messages during startup about "Auto capture keyboard" and "mouse pointer integration". It is safe to click them away and to check the "don’t show me again" box when you do.

When the VM has finished booting. It will go through some initialization and then present you with the URL a menu where you can start working with your VM.


5. Accessing the Virtual Machine

When the VM is running it is accessable from the host machine either using the OpenShift console via a web browser or on a command line interface using SSH. The web interface is useful for easily managing applications while the CLI allows the user to write and test applications and components. The web browser will also be used to verify the test applications during development.

5.1. User Accounts

There are two user accounts which are used to access the OpenShift Origin VM. Both are displayed on the VM console when it boots as shown in the examples above.

The first one is the OpenShift service account. This is used to access the web console and to run the rhc CLI commands as a developer.

  • Username: admin

  • Password: admin

The second account is the developer account. This is a UNIX account which is used to log into the OpenShift VM via SSH. It provides a work space for exploring the CLI and development environment of OpenShift Origin.

  • Username: openshift

  • Password: openshift

If you try logging in with one of thse and it fails, try using the other.

5.2. Using a browser to view the OpenShift Console

When the VM is running you can use the OpenShift Console to create and manage applications in the VM. Enter the URL from the CLI boot console into your browser. Enter the username and password when prompted.