Red Hat OpenShift is a container application platform that brings docker and Kubernetes to the enterprise. You can think of OpenShift as an operating system, images as applications that you run on them, and the containers as the actual running instances of those applications. For developers, OpenShift comes with the ability to run a production like environment on their local machine. Thus, testing of new features and fixes becomes easy and more reliable.

However, the first time setup is not that easy. This guide helps you to bypass common pitfalls installing OpenShift on your local machine.

Prerequisites

OpenShift is designed to run on Unix operated systems. Therefore, running OpenShift using MS Windows requires a virtual machine. We will use Hyper-V since it is shipped with almost any Windows 10 installation. Maybe you will have to enable Hyper-V on your machine. To do so, please refer to the Microsoft documentation. In addition, you will need to create a Virtual Switch using the Hyper-V Manager.

Finally, you must set the environment variable HYPERV_VIRTUAL_SWITCH to the Virtual Switch’s name:

Using the Command Prompt, you must not use quotes. If you are using PowerShell, you need to use quotes.

Please be aware that the Virtual Switch is bound to a concrete network adapter. If you change the network you are connected to (for example from LAN to W-LAN) you will have to create another Virtual Switch and reset the value in HYPERV_VIRTUAL_SWITCH.

The VM for running OpenShift will required a minimum of 2GB of RAM. However, I would recommend attaching at least 4GB – depending on the number and kind of containers you want to run.

Minishift

Minishift is a tool that helps you run OpenShift locally by running a single-node OpenShift cluster inside a VM. You can download the latest Minishift binaries from GitHub. When writing this article the current release version is 1.16.1.

Extract the contents of the archive to any directory on your machine. Please note that due to an unresolved issue, you need to place the Minishift binary on the same local drive as your Windows installation (this is most likely C:). You cannot run Minishift from a network drive. Add the Minishift binary to your PATH environment variable.

Minishift will use any SSH binary found on the PATH in preference to internal SSH code. Ensure that any SSH binary in the system PATH does not generate warning messages, as this will cause installation problems.

Start your OpenShift cluster

So, finally we are ready to start our OpenShift cluster:

Make sure that you are running your console as administrator (use “run as administrator” when starting the console). If everything goes fine, Minishift creates and starts new virtual machine, pulls and runs the latest OpenShift docker image within that VM. Depending on your internet connection, the first start will take some minutes. When the OpenShift cluster was successfully started, you should see the following lines in your console:

Now, you can copy the link and access the web console for example. Username and password are printed only on first start.

Your first app

To test my setup I will create a simple hello world application:

oc login connects you to your cluster. By default, you are now using project ‘myproject’. A project is used to group a couple of related applications.oc new-app creates a new application, pulls the given docker image and starts a container for that image. To make the application available for others we need to create a so called service usingoc expose (A service serves as an internal load balancer in order to proxy the connections it receives to one or more containers). This should only take some seconds. You can test your first application using curl (or the web browser):

That’s it! Now, you can run all your apps on your local machine in your own OpenShift cluster.

Troubleshooting

I already tried to note all possible mistakes and traps in the setup. However, if you are facing any problems, have a look at my troubleshooting compendium.

Changing your network

This is probably the nastiest issue. When starting Minishift for the first time the OpenShift setup creates some certificates that are bound to your current IP address. Now, if you change the network you are connected to (just assume you pick your laptop and go home), the virtual machine is certainly not going to boot again:

There is no solution yet. A workaround could be to start Minishift using different profiles, e.g. ‘home’ and ‘office’ (A profile is an isolated instance of the Minishift VM. Each Minishift profile is created with its own configuration regarding memory, CPU, disk size, and so on). This works for me. However, you will have to install all your apps twice.

Hyper-v commands have to be run as an Administrator

Missing administrator privileges you might see this error when starting Minishift:

Make sure to start your console using the “run as administrator” command. If there error does not go away, maybe a look into Minishift documentation might help you.

Insufficient memory

The default Minishift setup initializes the virtual machine with only 2 GB of memory. Starting a couple of services might quickly get you running out of memory. An indicator for that issue can be a service that is circularly crashing when starting or deploying.

You can fix this by increasing the memory in Hyper-V Manager (the VM needs to be stopped). You could also set the memory limit when starting Minishift for the first time:

For more options have a look at the Minishift documentation.

Connecting to the Minishift VM

Sometime you might need to alter the OpenShift installation – an issue might be missing permissions on the file system. To do so, you can connect into the Minishift VM by simply typing minishift ssh.

Further reading

If you still have problems, try to have a look at Minishift’s getting started guide or the Minishift troubleshooting pages.