Run OpenShift Locally with Minishift

OpenShift Origin is a distribution of Kubernetes optimized for continuous application development and multi-tenant deployment. OpenShift adds developer and free operations-centric tools on top of Kubernetes. This helps small and large teams rapidly develop applications, scale and deploy easily, and maintain an app throughout a long-term lifecycle. Minishift helps you run OpenShift locally by running a single-node OpenShift cluster inside a VM. With Minishift, you can try out OpenShift or develop with it daily on your local host. Under the hood it uses libmachine for provisioning VMs, and OpenShift Origin for running the cluster.

Installing and Using Minishift


Minishift requires a hypervisor to start the virtual machine on which the OpenShift cluster is provisioned. Make sure KVM is installed and enabled on your system before you start Minishift on Fedora.

First, install libvirt and qemu-kvm on your system.

sudo dnf install libvirt qemu-kvm

Then, add yourself to the libvirt group to avoid sudo.

sudo usermod -a -G libvirt <username>

Update your current session for the group change to take effect.

newgrp libvirt

Next, start and enable libvirtd and virlogd services.

systemctl start virtlogd
systemctl enable virtlogd systemctl start libvirtd systemctl enable libvirtd

Finally, install the docker-machine-kvm driver binary to provision a VM. Then make it executable. The instructions below are using version 0.7.0.

sudo curl -L -o /usr/local/bin/docker-machine-driver-kvm
sudo chmod +x /usr/local/bin/docker-machine-driver-kvm


Download the archive for your operating system from the releases page and unpack it. At the time of this writing, the latest version is 1.1.0:

tar -xvf minishift-1.1.0-linux-amd64.tgz

Copy the contents of the directory to your preferred location.

cp minishift ~/bin/minishift

If your personal ~/bin folder is not in your PATH environment variable already (use echo $PATH to check), add it:

export PATH=~/bin:$PATH

Get started

Run the following command. The output will look similar to below:

$ minishift start
Starting local OpenShift cluster using 'kvm' hypervisor...
OpenShift server started.
The server is accessible via web console at:

You are logged in as:
User:     developer
Password: developer

To login to your Minishift installation as administrator:
oc login -u system:admin

This process performs the following steps:

  • Downloads the latest ISO image based on boot2docker (~40 MB)
  • Starts a VM using libmachine
  • Downloads OpenShift client binary (oc)
  • Caches both oc and the ISO image into your $HOME/.minishift/cache folder
  • Finally, provisions OpenShift single node cluster in your workstation

Now, use minishift oc-env to display the command to add the oc binary to your PATH. The output of oc-env differs depending on the operating system and shell.

$ minishift oc-env
export PATH="/home/john/.minishift/cache/oc/v1.5.0:$PATH"
# Run this command to configure your shell:
# eval $(minishift oc-env)

Deploying an application

OpenShift provides various sample applications, such as templates, builder applications, and quickstarts. The following steps deploy a sample Node.js application from the command line.

First, create a Node.js example app.

oc new-app -l name=myapp

Then, track the build log until the app is built and deployed.

oc logs -f bc/nodejs-ex

Next, expose a route to the service.

oc expose svc/nodejs-ex

Now access the application.

minishift openshift service nodejs-ex -n myproject

To stop the service, use the following command:

minishift stop

Refer to the official documentation for getting started with a single node OpenShift cluster.


We’d love to get your feedback. If you hit a problem, please raise an issue in the issue tracker. Please search through the listed issues, though, before creating a new one. It’s possible a similar issue is already open.


The community hangs out on the IRC channel #minishift on Freenode ( You’re welcome to join, participate in the discussions, and contribute.


Fedora Project community For Developers


  1. Stephen Martin

    Thanks for this, I managed to run through your tutorial, I noticed that there is a formatting issue with the line that starts

    systemctl enable virtlogd

    I think it needs to be in the above code block

    The second issue was

    minishift openshift service nodejs-ex -n myproject

    this produced

    Namespace myproject doesn't exits

    However I manged to login to the new application from the management web interface.

    Thanks I have been meaning to play with the new openshift for ages.

    • Thanks for catching the format issue — fixed.

      • there is a typo issues in this command:

        systemctl enable virtlogd systemctl start libvirtd systemctl enable libvirtd

        the correct commando is:

        systemctl enable virtlogd ; systemctl start libvirtd ; systemctl enable libvirtd

  2. I’d really suggest avoiding “newgrp libvirt”, as this changes your primary group, rather than simply adding a secondary group. This has unintended side-effects; for example, all files created during this session will now be owned by group libvirt. That probably is not the intention. It’s better to log back out and back in again.

    BUT, that said, it’s even better to not add yourself to that particular group and instead configure PolicyKit.

  3. once minishift oc-env is added to your


    , is a nice idea enable the bash completion for oc command.

    So, we can run:

    oc completion bash &gt; /tmp/oc
    sudo cp /tmp/oc /etc/bash_completion.d/
    source /etc/bash_completion.d/oc
    oc &lt;Tab&gt;&lt;Tab&gt;
  4. lucodealethea

    Nice blog and thanks for the added replies, all usefull. I personally met a small issue with

    #minishift start
    "Network not found: no ERROR network with matching name'default'"

    That I resolved as following:

    find / -name default.xml


    virsh net-define /usr/share/libvirt/networks/default.xml

    virsh net-start default

    find / -name default.xml


    resulting in a new entry for default network


    minishift start

    minishift start
    Starting local OpenShift cluster using 'kvm' hypervisor...
    Downloading OpenShift binary 'oc' version 'v1.5.1'
     19.96 MiB / 19.96 MiB [============================================] 100.00% 0s
    -- Checking OpenShift client ... OK
    -- Checking Docker client ... OK
    -- Checking Docker version ... OK
    -- Checking for existing OpenShift container ... OK
    -- 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, 71% complete
       Pulled 2/3 layers, 96% 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 ...
       Creating initial OpenShift configuration
       Starting OpenShift using container 'origin'
       Waiting for API server to start listening
       OpenShift server started
    -- Adding default OAuthClient redirect URIs ... OK
    -- Installing registry ... OK
    -- Installing router ... OK
    -- Importing image streams ... OK
    -- Importing templates ... OK
    -- Login to server ... OK
    -- Creating initial project "myproject" ... OK
    -- Removing temporary directory ... OK
    -- Checking container networking ... OK
    -- Server Information ...
       OpenShift server started.
       The server is accessible via web console at:

    You are logged in as:
           User:     developer
           Password: developer

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

Comments are Closed

The opinions expressed on this website are those of each author, not of the author's employer or of Red Hat. Fedora Magazine aspires to publish all content under a Creative Commons license but may not be able to do so in all cases. You are responsible for ensuring that you have the necessary permission to reuse any work on this site. The Fedora logo is a trademark of Red Hat, Inc. Terms and Conditions