26. June 2017
14 min

Getting Started: MiniShift - An OpenShift Origin All-in-One VM


This blog post described briefly some concepts to get started with (Red Hat) OpenShift Origin using Minishift. I will guide you through the process of deploying Minishift and some OpenShift related concepts.

I will review the following topics:

  • Background
  • OpenShift Origin Installation Methods
  • What is MiniShift?
  • MiniShift Installation Options
  • Installing Minishift on Windows 7/8/10
  • Installing Minishift on Ubuntu-based Linux (KVM)
  • Installing Minishift on Ubuntu Linux (VirtualBox)
  • Connecting to OpenShift Origin (Minishift)
  • Let’s deploy our first app


Red Hat OpenShift Container Platform V3 (formerly known as OpenShift Enterprise) takes advantage of newer technologies such as Docker (1.1x) and Kubernetes (1.5), for managing and running applications within containers. It provides with a complete open source container application platform. Basically, it is a supported distribution of Kubernetes using Docker containers and DevOps tools for accelerated application development plus OpenShift’s own magic sauce (application lifecycle management functionality and DevOps tooling). Red Hat offers OpenShift in nearly any infrastructure, public or private. 

OpenShift allows the ability to easily deploy web application code directly using a library of pre-defined image builds or we can bring our own Docker images. With features such as persistent volumes, we are not limited to just running 12-factor or cloud native applications, but also deploy databases and many legacy applications.

Briefly, Red Hat OpenShift offering is….

  • OpenShift Online is Red Hat’s public cloud application development and hosting service. On-Demand Access.
  • OpenShift Dedicated is Red Hat’s managed private cluster offering for Enterprises. Own OpenShift cluster operated by Red Hat.
  • OpenShift Container Platform  is Red Hat’s on-premise private PaaS product. Whether it’s on premise in customer data center or private cloud.

OpenShift Origin is the upstream community project used in OpenShift Online, OpenShift Dedicated, and OpenShift Container Platform.

Note.- I am referring to OpenShift Origin 1.5 (OpenShift 3.5) released on April, 2017.

OpenShift Origin Installation Methods

OpenShift Origin has multiple installation methods available. Quick installation and Advanced installation methods are supported for development and production environment.

There are 3 quick installation methods:

  1. Running in a Container (from DockerHub) – Only for Red Hat based distributions, RHEL, Fedora and CentOS.
  2. Download a Binary (GitHub). This is an all-in-one version. Pay attention with this option, because versions for Windows and Mac are limited.
  3. Building from source, locally or using Vagrant.

Docker and OpenShift Origin must run on the Linux operating system. If you wish to run the server from a Windows or Mac OS X you should go for the Vagrant flavour in method 3.

All of them requires some prerequisites on your hosts, which includes verifying system and environment requirements and installing and configuring Docker. So, only after ensuring your hosts are properly setup you could continue with one of them.

For production environments, several factors influence installation and the advanced installation method would be suitable:

  • HA needed?
  • Single Master or Multiple Master?
  • Sizing, How many hosts or nodes are required in your cluster?
  • RPM vs Containerized

The advanced installation method uses Ansible playbooks, so knowledge of Ansible is assumed. This is out of the scope of this blog entry…sorry guys.

I have chosen Minishift as our first option and I encourage you this option if you are approaching OpenShift for the very first time.

What is MiniShift?

Minishift is an upstream community project that is intended for OpenShift Origin. Minishift is a tool that helps you run OpenShift locally by launching a single-node OpenShift Origin cluster inside a virtual machine. With Minishift you can try out OpenShift Origin or develop with it, day-to-day, on your local machine. You can run Minishift on Windows, Mac OS, and GNU/Linux operating system. Given its focus on application developers, it should NOT be used in production.

Please be advised that there are some references out there regarding OpenShift All-in-One VM, which is a VirtualBox VM packaged up and shipped using a Vagrant file. As of February 6th, 2017, OpenShift guys decided to retire the OpenShift All-in-One VM in favor of the Minishift option, please have a look at https://blog.openshift.com/goodbye-openshift-all-in-one-vm-hello-minishift/

MiniShift Installation Options

Minishift requires a hypervisor to run the virtual machine containing OpenShift, so only 64 bits Operating Systems are allowed. Depending on your host operating system, you have the choice of the following hypervisors:

  • OS X: xhyve (default), VirtualBox, VMware Fusion
  • GNU/Linux: KVM (default), VirtualBox
  • Windows: Hyper-V (default), VirtualBox, VMware Workstation (Using Linux guest OS with KVM, nested virtualization)

I will go throughout two different deployment options: Windows and Linux. I will show you that installing Minishift with the VirtualBox option as hypervisor is very easy and works the same way, regardless Windows or Linux. Installing using KVM as hypervisor implies further steps, but not too difficult.

For demonstration purposes, I will use the following user profile name: novatec

Let’s go ahead.

Installing Minishift on Windows 7/8/10

As we can expect, installing Minishift on Windows is quite straightforward. By default, Minishift will try to use Hyper-V as hypervisor on Windows, which is the Microsoft hypervisor solution implemented on Windows 7/8/10. This is an OS optional feature disabled by default which requires a reboot and have some further implications when enabled. For simplicity, I would encourage that you use VirtualBox as the hypervisor option on Windows. If you have Linux with VirtualBox, the installation works the same way, I will explain how to do it below.

In order to avoid a couple of bugs, you should check the following:

  1. Use VirtualBox 5.1.12 or later. Please, check your version and upgrade it accordingly. As of this writing, latest version is 5.1.22.
  2. Deploy Minishift on the drive containing your %USERPROFILE% directory, usually the C: drive. We will use C: drive, so no worries.
How to check %USERPROFILE%

Open a command prompt console and run the following command (in blue):

C:\Users\novatec> set | findstr USERPROFILE


NOTE.- We can see that xxx userprofile is located at C: drive, where xxx is your user profile name

So far, so good. We are ready to go. Just follow these steps…

(Optional!) You might want to check the hash of the downloaded binary. This is very common in *NIX environments, but quite easy in Windows as well. Feel free. You might use your 7-Zip, right click on the zip file and choose CRC SHA → SHA256 and that´s it. For Windows lovers, Windows 10 includes a Powershell cmdlet, Get-FileHash, to do it. Not working on W7 because PS should be 4.0 or later.

  • Create a new folder under your profile path. We will use the following path: C:\Users\Novatec\Minishift\ for simplicity.
  • Just unzip the binary to this folder. We should have something similar to this:

  • We should add the minishift folder to the PATH environment variable.

There are multiple ways to achieve this, and there are minor differences between Windows 7, 8 or 10. Changes can be temporary or permanent, per user or per system, using the command line (set, setx, powershell..) or GUI.. To keep it simple, just modify the user environment variable using the GUI as shown below.

  • Windows 7 – Click on Start → Computer → Properties → Advanced System Settings → Environment variables → Click on PATH →Choose Edit
  • Windows 10 – Open Start Menu → Just Type ‘System Settings’ → Advanced View Settings →  Environment variables → Click on PATH → Choose Edit

  • Now, just type minishift start –vm-driver=virtualbox Your screen will look like this…

At this point, Minishift binary is performing many tasks in order to prepare our All-in-One VM environment. One of them is downloading the ISO image that the hypervisor uses to provision the Minishift VM.

FYI, The following ISO images are available:

  • Minishift Boot2Docker (Default). This ISO image is based on Boot2Docker, which is a lightweight Linux distribution customized to run Docker containers. This ISO image size is small and optimized for development but not for production.
  • Minishift CentOS. This ISO image is based on CentOS, which is an enterprise-ready Linux distribution that more closely resembles a production environment. This ISO image size is larger than the Boot2Docker ISO image.

Additionally, Minishift will download the OpenShift binary command-line tool, based on the version of the VM, which is called OC. It is written in Go programming language, so nothing to install.

    (Note) It might be possible that Windows asks you for the following confirmation. This behavior is normal and expected. Do not worry if you do not receive this warning. When the Minishift binary runs for the very first time, it might require new Host-Only Virtual Box network interfaces to be created.

    Finally, we will have something similar to this… Be aware of the server IP, URL and login credentials needed to interact with OpenShift Origin.

If you go to your Virtual Box Manager console, you will see a new running VM.

  • Modify your PATH environment variable (Yes, again. Good thing is you are going to learn how to do it forever..)

Now, we have Minishift running, however on Windows we will need an additional setup action: A path environment variable.

Remember, when you use Minishift, you interact with two components:

  1. A virtual machine (VM) created by Minishift
  2. The OpenShift cluster provisioned by Minishift within the VM

First one is managed by the minishift binary (.exe) and the second one is managed by the OpenShift binary command-line tool, called oc (‘oc’ stands for OpenShift client). As part of the provision, Minishift downloaded OC binary tools,  however we cannot run any oc command because PATH environment variable has not been updated.

Just run the following command, minishift oc-env to display the command you need to type into your shell in order to add the oc binary to your PATH environment variable. The output is OS dependent, on Windows we will see something similar to this:

C:\Users\Novatec\Minishift>minishift oc-env
SET PATH=C:\Users\Novatec\.minishift\cache\oc\v1.5.1;%PATH%
REM Run this command to configure your shell:
REM     @FOR /f “tokens=*” %i IN (‘minishift oc-env’) DO @call %I

Therefore, OpenShift client path is C:\Users\Novatec\.minishift\cache\oc\v1.5.1 In order to use ‘oc’ command you should add the path to the system variables and reboot. Otherwise, every time you open a command prompt you will have to run SET PATH=C:\Users\Novatec\.minishift\cache\oc\v1.5.1;%PATH%

Installing Minishift on Ubuntu-based Linux (KVM)

I have been working with Elementary OS for the last couple of years, so I will use it. It is an Ubuntu-based distribution.

We will be using KVM as hypervisor which is the default option for Minishift running under Linux.

Docker Machine is a tool that lets you install Docker Engine on virtual hosts, and manage the hosts with docker-machinecommands.

Minishift uses Docker Machine and its driver plugin architecture to provide a consistent way to manage the OpenShift VM. KVM driver requires specific installation and configuration steps, which are different between Linux flavours. I will focus on Ubuntu, for other distributions commands are different, it is up to you… For further info go to: https://docs.openshift.org/latest/minishift/getting-started/setting-up-driver-plugin.html

Note.- I will use jga as username in Linux.

  • Install the KVM binary as follows:

  • Make the binary executable:
  • Install libvirt and qemu-kvm on your system:

  • Add yourself to the libvirtd group. At the end of the command you should put your username (jga in my case)
  • Update current session:

  • Check if KVM is running fine….

i.e. the screenshot below shows an unsupported configuration, so we should figure out what is happening and solve before trying to use Minishift with kvm as hypervisor. Typical errors: Your system BIOS has no virtualization features enabled, Intel VT or AMD-V, or maybe your trying to use a nested virtualization which is not allowed with VirtualBox (Running a Linux OS on Windows Virtual Box). Other products such as VMware allows you to play with nested virtualization. As of this writing, VirtualBox cannot do it.

How to check CPU support

Just type the following command. If the output contains svm (AMD) or vmx (Intel), your CPU has virtualization support enabled.

$ cat /proc/cpuinfo | egrep ‘svm|vmx’

  • …..We would prefer a message as follows..

  •  Uncompress it… For demonstration purposes, I will create a new folder called Minishift  and copy the binary there, but this is not required. You may want to just unzip it in the Downloads folder. It is up to you.

  • Now, just type ./minishift start

The binary will proceed with the required steps to provision your OpenShift Cluster. So, at this point, Minishift binary is performing many tasks in order to prepare our All-in-One VM environment, one of them is download the oc tools and the ISO. Remember that we have 2 ISO images available: Boot2Docker (Default) and CentOS. Please go back and read the Windows section (above) if you need further details.

As we can see above, Minishift binary have downloaded and configured everything fully automated. Please note the IP and login credentials that should be used to connect.

  • Ideally, Minishift VM is running fine, however we may need to modify our PATH environment variable to include the OpenShift client tools. Please let me rephrase what I mentioned in the Windows section.

When you use Minishift, you interact with two components:

  1. A virtual machine (VM) created by Minishift
  2. The OpenShift cluster provisioned by Minishift within the VM

First one is managed by the minishift binary (.exe) and the second one is managed by the OpenShift binary command-line tool, called oc (‘oc’ stands for OpenShift client). As part of the provision, Minishift downloaded OC binary tools,  however we cannot run any oc command because PATH environment variable has not been updated.

Just run the following command, ./minishift oc-env to display the command you need to type into your shell in order to add the oc binary to your PATH environment variable.

jga@novatec-minishift:~/minishift$ ./minishift oc-env
export PATH=”/home/jga/.minishift/cache/oc/v1.5.1:$PATH”
# Run this command to configure your shell:
# eval $(minishift oc-env)
jga@novatec-minishift:~/minishift$ export PATH=”/home/jga/.minishift/cache/oc/v1.5.1:$PATH”

Now, we can run oc commands and Minishift VM has been deployed successfully…

Installing Minishift on Ubuntu Linux (VirtualBox)

If you have VirtualBox on your linux machine (preferably 5.1.x), the installation of Minishift is as easier as on Windows. Pretty much the same process, obviously different minishit binary, the binary for Linux.

Note.- If you do not have VirtualBox, you can always download it at  https://www.virtualbox.org/wiki/Linux_Downloads

You should download the binary from the Minishift releases page. Available @ https://github.com/minishift/minishift/releases

Unzip it to your desired folder and…Now, just type..



And that´s all!!

Well..you should adjust your path environment variable as we explained above, if you want to use the oc commands.

Just run the following command, ./minishift oc-env to display the command you need to type into your shell in order to add the oc binary to your PATH environment variable.

jga@novatec-minishift:~/minishift$ ./minishift ocenv
export PATH=”/home/jga/.minishift/cache/oc/v1.5.1:$PATH”
# Run this command to configure your shell:
# eval $(minishift oc-env)
jga@novatec-minishift:~/minishift$ export PATH=”/home/jga/.minishift/cache/oc/v1.5.1:$PATH”

Connecting to OpenShift Origin (Minishift)

As you know, we have two different command line tools, in one hand we have the tool called minishift. It has assisted us to create a provision a local, single-node OpenShift Origin cluster in a VM/KVM.  However, minishift has a lot of additional available commands to help us in interacting with and configure our local OpenShift instance: modifying, stopping, starting, deleting, and so on.. In the other hand, we have OpenShift client tools, called oc. With oc we are working directly with OpenShift, so we can create applications, manage projects, etc,etc.

So, we can work from the command line, web console, or via the Eclipse IDE using the latest JBoss tools. However, I am going to focus on using the cli tool and the web console here.

Now that we have everything in place let’s go ahead and login using the web console. …Hum…(sad) what was the URL to connect to? No worries, Minishift will help you, just type the following command:



..and you will see the URL to connect to. In my case…

jga@novatec-minishift:~/minishift$ ./minishift console —url

By default, any non-empty user name and password can be used to login to the local cluster. The recommended user name and password combination is developer/developer, because it already has a default project myproject and also can impersonate the administrator.

Now, log in as admin using the CLI:

using developer/developer.

Do you prefer the GUI?

Let’s deploy our first app

OpenShift Origin is designed for building and deploying applications. Depending on how much you want to involve OpenShift Origin in your development process, you can choose to:

  • focus your development within an OpenShift Origin project, using it to build an application from scratch then continuously develop and manage its lifecycle, or
  • bring an application (e.g., binary, container image, source code) you have already developed in a separate environment and deploy it onto OpenShift Origin.

You can create a new OpenShift Origin application from components including source or binary code, images and/or templates by using either the OpenShift CLI or web console.

Creating from source code option show up one of the most powerful features of Openshift comes in with the Source-to-Image (S2I). It is a toolkit and workflow for building reproducible Docker images from source code. S2I produces ready-to-run images by injecting source code into a Docker container and letting the container prepare that source code for execution. What that means is that OpenShift only needs to know the URL of your git repository and then the platform takes care of the rest. Under the covers, when you create a new project and container, the platform matches a base image of the desired runtime up with your source, performs a build, and then creates a new Docker image on the fly.

Origin needs to know what kind of application it is, somehow. Origin attempts to determine the language builder to use by the presence of certain files in the root or specified context directory of the repository:

I will use a very basic Java application hello world application located a github.com. (forked from gshipley/book-helloworld)

So then, we are going to bring an existing application onto Origin using the web console.

If it supposed that we have a Project. Let’s click on Add to Project.

Choose Java Template and WildFly afterwards:

You should see…

Now, Just copy&paste the GIT repository, in our case… I will use https://github.com/jmgalvez/book-helloworld.git

When you click on Create button you will see something similar to this:

At this point, S2I is executed, this may take a few minutes as the builder image is downloaded and the source code for the project is compiled: A new deployment will be created automatically once the build completes.

Note the info in the upper right hand of the screen.  The application has an associated route, which is the DNS name for our app in our local network (using the NIP.io domain).

At the end, we will see a blue indicator with 1 pod. App is ready !!

And… Voilá!!

On your Minishift GUI, If you click on #1 link (Build HelloWord,#1), we will obtain some interesting detail about the build. Source type is git, build strategy is source and so on.

After a code change, we only need to git commit & push and come back here to create a new build. That’s all.

That’s all folks!

Comment article


  1. David Snyder

    My PC must have gotten ashamed of itself. the install finally worked. I’m good!

  2. David Snyder

    Jose, I am am encountering an error when I attempt to install minishift on my Windows 7 Home Premium Edition – Service Pack 1.

    When i run the ” minishift start –vm-driver=virtualbox” command, the VM is created in Virtual box, but I receive the following error:
    Error determining Docker settings: dial-http tcp read tcp 127.0
    .0.1:56999-> wsarecv: An existing connection was forcibly closed
    by the remote host.

    I thought I would touch base with you to see if you might have any guidance/suggestions?

    thank you sir!


  3. Jose Manuel Galvez Rodriguez

    Thank you Marco! Happy to read that.

  4. Jose Manuel Galvez Rodriguez

    Thanks Akram!

  5. Jose Manuel Galvez Rodriguez

    Hello David!

    Thanks for the feedback.

    I have checked and the command is correct (originally there are 2 –, however, it seems to be only 1, some kind of html/font issue, do not know). In the screenshot below it is clearly shown.

  6. David Snyder

    thank you very much for providing this blog! Extremely helpful! One item to correct, in the instructions for installing on Windows 7/8, Now, “just type minishift start –vm-driver=virtualbox Your screen will look like this…”, a ‘-‘ is missing in the command, it should be revised to
    “minishift start –-vm-driver=virtualbox.

    thanks again!

  7. Marco

    Great article Jose.

    I looked for an article like this once I’d failed to install Minishift on Windows using only Hyper-V.
    I got a lot of problems with that solution; I run your configuration and everything work!

  8. Roshan Patil

    Can we setup c++ development environment with minishift or openshift origin ?

  9. Walid

    install was smooth, how would one go about updates later on?

  10. Jose Manuel Galvez Rodriguez

    Thank you very much for your feedback, Wolfram. Yep, it is quite easy as well.

  11. Wolfram Richter

    Cool Stuff! BTW installing on a mac is also easy when using homebrew (http://brew.sh/):

    Wolframs-MacBook-Pro-7:~ wolfram$ brew cask install minishift
    ==> Satisfying dependencies
    ==> Downloading https://github.com/minishift/minishift/releases/download/v1.2.0/minishift-1.2.0-darwin-amd64.tgz
    ######################################################################## 100.0%
    ==> Verifying checksum for Cask minishift
    ==> Installing Cask minishift
    ==> Linking Binary ‘minishift’ to ‘/usr/local/bin/minishift’.
    minishift was successfully installed!
    Wolframs-MacBook-Pro-7:~ wolfram$ minishift start
    Starting local OpenShift cluster using ‘virtualbox’ hypervisor…
    Downloading OpenShift binary ‘oc’ version ‘v1.5.1’
    18.94 MiB / 18.94 MiB [==============================================================================================================================================================] 100.00% 0s
    — Checking OpenShift client … OK
    — Checking Docker client … OK
    — Checking Docker version … OK
    — Checking for existing OpenShift container …
    Deleted existing OpenShift container
    — Checking for openshift/origin:v1.5.1 image …
    Pulling image openshift/origin:v1.5.1
    Pulled 0/3 layers, 3% complete
    Pulled 1/3 layers, 68% complete
    Pulled 2/3 layers, 87% complete
    Pulled 3/3 layers, 100% complete
    Image pull complete
    — Checking Docker daemon configuration … OK
    — Checking for available ports … OK
    — Checking type of volume mount …
    Using Docker shared volumes for OpenShift volumes
    — Creating host directories … OK
    — Finding server IP …
    Using as the server IP
    — Starting OpenShift container …
    Starting OpenShift using container ‘origin’
    Waiting for API server to start listening
    OpenShift server started
    — Removing temporary directory … OK
    — Checking container networking … OK
    — Server Information …
    OpenShift server started.
    The server is accessible via web console at:

    To login as administrator:
    oc login -u system:admin

    Wolframs-MacBook-Pro-7:ose3-ticket-monster wolfram$