Minishift is a tool that helps you run OpenShift locally by running a single-node OpenShift cluster inside a VM. You can try out OpenShift or develop with it, day-to-day, on your local host.
- Known Issues
Minishift requires a hypervisor to run the virtual machine containing OpenShift. Depending on your host OS, you have the choice of the following hypervisors:
Minishift ships with drivers for VirtualBox and VMware Fusion out of the box. Other drivers require manual installation, see docker machine drivers installation for more details.
- For most hypervisors, VT-x/AMD-v virtualization must be enabled in the BIOS. For Hyper-V, however, it needs to be disabled.
- We recommend that you use
Virtualbox >= 5.1.12on Windows to avoid the issue Error: getting state for host: machine does not exist
Download the archive matching your host OS from the Minishift releases page and unpack it. Copy the contained binary to your preferred location and optionally ensure it is added to your PATH.
- Due to issue #236, you need to execute the minishift binary on Windows OS from the drive containing your %USERPROFILE% directory.
- Automatic update of minishift binary and virtual machine ISO is currently disabled, due to issues #204, #178, #112 and #192. We will take a comprehensive look at these issues in an upcoming release and provide an improved solution for automatic updates.
Installing via Homebrew
On OS X you can also use Homebrew Cask to install the stable version of Minishift:
$ brew cask install minishift
If you want to install the latest beta version of Minishift you will need the homebrew-cask versions tap. After you install homebrew-cask, run the following command:
$ brew tap caskroom/versions
You can now install the latest beta version of minishift.
$ brew cask install minishift-beta
This section contains a brief demo of Minishift and the provisioned OpenShift instance. For details on the usage of Minishift refer to the Using Minishift guide. The interaction with OpenShift is via the command line tool oc which is copied to your host.
Assuming you have put minishift on the PATH as described in Installing Minishift you can start Minishift via:
$ minishift start Starting local OpenShift instance using 'kvm' hypervisor... ... OpenShift server started. The server is accessible via web console at: https://192.168.99.128:8443 You are logged in as: User: developer Password: developer To login as administrator: oc login -u system:admin
Note that, the IP seen above is dynamic and can change. It can be retrieved with
minishift ip. Also, instead of 'kvm', you will see 'xhyve' on Mac OS and 'hyperv' on Windows.
Note: By default Minishift uses the driver most relevant to the host OS. To use a driver of choice for Minishift, use the
minishift start. For example, to use VirtualBox instead of KVM for Fedora, use
minishift start --vm-driver=virtualbox.
ocbinary to the PATH:
Note: How to modify the PATH varies depending on host OS, version of the OC binary and other variables. In case of doubt, you can check the content of the
$ export PATH=$PATH:~/.minishift/cache/oc/v1.3.1
Login to your OpenShift account and authenticate yourself:
$ oc login https://192.168.99.128:8443 -u developer -p developer
Deploying a sample application
You can use Minishift to run a sample Node.js application on OpenShift as follows:
Create a Node.js example app:
$ oc new-app https://github.com/openshift/nodejs-ex -l name=myapp
Track the build log until the app is built and deployed using:
$ oc logs -f bc/nodejs-ex
Expose a route to the service as follows:
$ oc expose svc/nodejs-ex
Access the app:
$ curl http://nodejs-ex-myproject.192.168.99.128.xip.io
To stop Minishift, use:
$ minishift stop Stopping local OpenShift cluster... Stopping "minishift"...
Reusing the Docker daemon
When running OpenShift in a single VM, it is recommended to reuse the Docker daemon which Minishift uses for pure Docker use-cases as well. By using the same docker daemon as Minishift, you can speed up your local experiments.
To be able to work with the docker daemon on your Mac/Linux host use the
docker-env command in your shell:
eval $(minishift docker-env)
You should now be able to use docker on the command line of your host, talking to the docker daemon inside the Minishift VM:
The following documentation is available:
- Using Minishift
- Command reference
- Installing docker-machine drivers
- Developing Minishift
The following features are not supported in Minishift.
- Features that require a Cloud Provider, such as:
- Features that require multiple nodes, such as advanced scheduling policies
- Alternate runtimes such as
Minishift is an open-source project dedicated to developing and supporting Minishift. The code base is forked from the Minikube project.
Contributions, questions, and comments are all welcomed and encouraged! Minishift developers hang out on IRC in the #openshift-dev channel on Freenode.
If you want to contribute, make sure to follow the contribution guidelines when you open issues or submit pull requests.