Minishift
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.
Minishift uses libmachine for
provisioning VMs, and OpenShift Origin for running the cluster.
Installation
Prerequisites
Minishift requires a hypervisor to start the virtual machine containing OpenShift.
Make sure that the hypervisor of your choice is installed and enabled on your system before you
install Minishift.
Depending on your host OS, you have the choice of the following hypervisors:
If you encounter issues related to the hypervisor, see the Troubleshooting guide.
Installing Minishift
Manually
- Download the archive for your operating system from the Minishift releases page and unpack it.
- Copy the contents of the directory to your preferred location.
- Add the
minishift
binary to your PATH environment variable.
Note:
- On Windows operating system, due to issue #236, you need to execute the minishift binary
from the drive containing your %USERPROFILE% directory.
- Automatic update of the Minishift binary and the virtual machine ISO is currently disabled. See also issue #204
With Homebrew
Stable
On OS X you can also use Homebrew Cask to install the stable version of Minishift:
$ brew cask install minishift
Latest Beta
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
Uninstalling Minishift
-
Delete the Minishift VM and any VM-specific files:
$ minishift delete
This command deletes everything in the MINISHIFT_HOME/.minishift/machines/minishift
directory.
Other cached data and the persistent configuration are not removed.
-
To completely uninstall Minishift, delete everything in the MINISHIFT_HOME
directory
(default ~/.minishift
) and ~/.kube
:
$ rm -rf ~/.minishift
$ rm -rf ~/.kube
-
With your hypervisor management tool, confirm that there are no remaining artifacts related
to the Minishift VM. For example, if you use KVM you need to run the virsh
command.
Quickstart
This section contains a brief demo of Minishift and the provisioned OpenShift cluster.
For details on the usage of Minishift refer to the Managing Minishift topic.
The interaction with OpenShift is via the command line tool oc which is copied to your host. For more information on how Minishift can assist you in interacting with and configuring your local OpenShift instance refer to the Interacting with OpenShift topic.
For more information about the OpenShift cluster architecture,
see Architecture Overview in the
OpenShift documentation.
The following steps describe how to get started with Minishift on a GNU/Linux operating system
with the KVM hypervisor driver.
Starting Minishift
-
Run the minishift start
command.
$ minishift start
Starting local OpenShift cluster 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:
- The IP is dynamically generated for each OpenShift cluster. To check the IP, run the
minishift ip
command.
- By default Minishift uses the driver most relevant to the host OS. To use a different driver, set the
--vm-driver
flag in minishift start
. For example, to use VirtualBox instead of KVM on GNU/Linux operating systems, run minishift start --vm-driver=virtualbox
. For more information about minishift start
options,
see the minishift start command reference.
-
Add the oc
binary to the PATH environment variable.
$ export PATH=$PATH:~/.minishift/cache/oc/v1.4.1
Note: Depending on the operating system and the oc
version, you might need
to use a different command to add oc
to the PATH environment variable.
To verify the oc
version, check the contents of the ~/.minishift/cache/oc
directory.
For more information about interacting with OpenShift with the command-line interface and
the Web console, refer to the Interacting with OpenShift topic.
Deploying a sample application
OpenShift provides various sample applications, such as templates, builder applications,
and quickstarts. The following steps describe how to deploy a sample Node.js application
from the command-line.
To deploy the Node.js sample application from the command-line:
-
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:
$ minishift openshift service nodejs-ex -n myproject
-
To stop Minishift, use:
$ minishift stop
Stopping local OpenShift cluster...
Stopping "minishift"...
For more information about creating applications in OpenShift,
see Creating New Applications in
the OpenShift documentation.
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.
-
Make sure that you have the Docker client binary installed on your machine. For information about
specific binary installations for your operating system, see the Docker installation page.
-
Start Minishift with the minishift start
command.
-
Use the minishift docker-env
command
to export the environment variables that are required to reuse the daemon.
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. To test the connection, run the following command:
docker ps
If successful, the shell will print a list of running containers.
Documentation
The following documentation is available:
Limitations
The following features are not supported in Minishift.
- Features that require a Cloud Provider, such as:
- LoadBalancers
- PersistentVolumes
- Ingress
- Features that require multiple nodes, such as advanced scheduling policies
- Alternate runtimes such as
rkt
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 #minishift channel on Freenode.
If you want to contribute, make sure to follow the contribution guidelines
when you open issues or submit pull requests.