Using OpenShift 3 on your local environment

You have probably heard about all of the cool new things we are working on for developers in the latest version of OpenShift that we call OpenShift 3.  This includes including support for native docker containers, orchestration and scheduling with the Kubernetes project, and tools created to make life easier for both Developers and System Administrators.
The trouble though, is that most developers don’t want to spend the time learning how to install and administrator a linux system just to use OpenShift 3 on their local machine.  This makes sense because a Container Application Platform, like OpenShift, is supposed to free the developer up from the admin side of the house in order to focus on code.

In this blog post, I will discuss the latest version of the all-in-one virtual machine image that a few of us have put together. We made this Vagrant image to make your life even easier and give you the ability to quickly spin up and develop against the latest and greatest open source OpenShift Container Application Platform.


First of all, let’s get where you can run this out of the way.  I am happy to state that the all-in-one image will run on the big three operating systems: Windows, OS X, and Linux (actually it runs anywhere Vagrant and VirtualBox run).  Personally, I am using Linux (Fedora) but realize most developers are on either Windows or OS X so we wanted to make it a great experience regardless of what operating system you use as your daily driver.


Software requirements

In order to run the all-in-one image, you only need a couple of things on your system.  Namely, Vagrant, VirtualBox, and the oc command line tool.  All this is laid out on the OpenShift Origin VM page (


Step 1: Install VirtualBox

The OpenShift all-in-one image makes use of VirtualBox as the virtualization system in which to run the Platform.  You are probably wondering why we chose VirtualBox for this over x, y, or z.  No real solid reason other than it’s free for everyone so let’s not argue about it and just move on to downloading it.


Point your browser to the following URL:

And download the correct package for you operating system.  



Once you have it downloaded, follow the instruction on the VirtualBox site in order to install the software.

Step 2: Install Vagrant


You probably already have Vagrant install on your system, but if you don’t simply head over the download page and follow the instructions for your operating system.

Note: For Linux systems, is it recommended that you install via the package manager provided by your distribution.  For example, to install Vagrant on Fedora 23, I would issue the following command:

$ sudo dnf install vagrant



Step 3: Download the latest oc toolset

OpenShift 3 allows you to work from the command line, web console, or via the Eclipse IDE using the latest JBoss Tools.  However, for the purpose of this blog post, we are going to focus on using the command line tool called oc.  The oc tool is a single executable that is written in the Go programming language.  For this reason, there is actually nothing to install.  You simply need to download the tool and add it to your PATH.  Sounds easy, right?  Well, it is for OS X and Linux users but Windows users will need to hunt around a bit to change the system path as it considered an advanced feature, but I digress.  Let’s start with downloading the toolset.  The only real requirement for the oc tools is that you are using a 64 bit operating system.  Use the following links to download the appropriate tool for your operating system:



Once you have the tool downloaded, extract the contents and add the oc executable to your PATH.  For example, if I extracted the contents to the cli directory in my home directory, I would issue the following command on both Linux and OS X:

$ export PATH=$PATH:~/cli/

Windows: Because changing your PATH on windows varies by version of the operating system, we will not list each operating system here. However, the general workflow is right click on your computer name inside of the file explorer. Select Advanced system settings. I guess changing your PATH is considered an advanced task? :) Click on the advanced tab, and then finally click on Environment variables. Once the new dialog opens, select the Path variable and add “;C:\CLI” at the end (ensure you replace C:\CLI with the location of where you extracted the tool). For an easy way out, you could always just copy it to C:\Windows or a directory you know is already on your path. For more detailed instructions:

Windows XP

Windows Vista

Windows 7

Windows 8

Windows 10 – Follow the directions above.

Step 4: Download the Vagrantfile

The last thing we need to download is the Vagrantfile which tells Vagrant what type of system we want to download as well as some configuration information.  You can download the Vagrantfile at the following link:

Step 5: Change your memory configuration
The last thing you may want to do is customize the amount of memory that you will the OpenShift Container Application Platform to use.  By default, the Vagrantfile will allocate 4gb of memory for the platform but you may want to change this depending on your specific needs.  For example, my development rig has 32gb of memory (yeah, I am bragging a bit here) so I like to allocate 16gb.  The relevant line you want to change in the Vagrantfile is:

vb.memory = "4096"

Step 6: Start things up

The last thing we need to do is start the platform up.  To do this, ensure that you are in the directory where your Vagrantfile is and issue the following command:

$ vagrant up --provider=virtualbox


At this point, the all-in-image will be downloaded so be patient and it depends on your connection speed to the internet.  For example, I have 300mbit (bragging again) and it took just over one minute for the box to download.  Here is example of the output I received after issuing the vagrant up command:

Bringing machine ‘default’ up with ‘virtualbox’ provider…

==> default: Box ‘thesteve0/openshift-origin’ could not be found. Attempting to find and install…

  default: Box Provider: virtualbox

  default: Box Version: >= 0

==> default: Loading metadata for box ‘thesteve0/openshift-origin’

  default: URL:

==> default: Adding box ‘thesteve0/openshift-origin’ (v1.1.1) for provider: virtualbox

  default: Downloading:


==> default: Successfully added box ‘thesteve0/openshift-origin’ (v1.1.1) for ‘virtualbox’!

==> default: Importing base box ‘thesteve0/openshift-origin’…

==> default: Matching MAC address for NAT networking…

==> default: Setting the name of the VM: origin-1.1.1

==> default: Clearing any previously set network interfaces…

==> default: Preparing network interfaces based on configuration…

  default: Adapter 1: nat

  default: Adapter 2: hostonly

==> default: Forwarding ports…

  default: 22 => 2222 (adapter 1)

==> default: Running ‘pre-boot’ VM customizations…

==> default: Booting VM…

==> default: Waiting for machine to boot. This may take a few minutes…

  default: SSH address:

  default: SSH username: vagrant

  default: SSH auth method: private key

  default: Warning: Connection timeout. Retrying…


  default: Vagrant insecure key detected. Vagrant will automatically replace

  default: this with a newly generated keypair for better security.


  default: Inserting generated public key within guest…

  default: Removing insecure key from the guest if it’s present…

  default: Key inserted! Disconnecting and reconnecting using new SSH key…

==> default: Machine booted and ready!

==> default: Checking for guest additions in VM…

  default: No guest additions were detected on the base box for this VM! Guest

  default: additions are required for forwarded ports, shared folders, host only

  default: networking, and more. If SSH fails on this machine, please install

  default: the guest additions and repackage the box to continue.


  default: This is not an error message; everything may continue to work properly,

  default: in which case you may ignore this message.

==> default: Setting hostname…

==> default: Configuring and enabling network interfaces…

Step 7: Authenticate to OpenShift 3 with the web console

Now that we have everything up and running, you probably want to authenticate to the platform.  Let’s start by using the web console.  Open up your browser and go to the following URL:

If things worked correctly, you should see the following screen:


You can enter anything you wish for username/password as the authentication is open (there is already an account for admin/password that has a sample project in it).  If the user doesn’t exist, it will be created.  Once you have logged in, you should see the following:


Step 8: Authenticate to OpenShift 3 with the CLI

Now that our OpenShift 3 environment is up and running, we can authenticate to it from the oc  command line tool.  In order to do so, enter in the following at your command prompt:

$ oc login

You should see the following response:

Authentication required for (openshift)

Enter in the username/password combination remembering that if they user doesn’t exist, it will be created on the fly.  You should see the following:

Login successful.

You don't have any projects. You can try to create a new project, by running

$ oc new-project

Note: If you are on Windows, I suggest that you take a look at my blog post that discusses what I believe is a great command line environment for working with OpenShift on Windows:


From here on out you have a working OpenShift machine to work against. We will follow up with more blog posts using this machine so get ready!


In the blog post, I discuss how to download and use the latest and great open source OpenShift platform on your local machine.  For up to date information on the status of the all-in-one image project, you can visit the official project page at:

OpenShift Container Platform, OpenShift Dedicated, OpenShift Online, OpenShift Origin, Products

9 Responses to “Using OpenShift 3 on your local environment”

  1. Ayemi Musa

    What if you already have Docker setup in an existing VirtualBox on your Windows system, can both Docker and OpenShift VM coexist?

    • Grant Shipley

      @ayemimusa:disqus Yes, this should be fine.

  2. Camilo Crespo

    Having some issues with the command line: oc login, results in: Unable to connect to the server: x509: certificate has expired or is not yet valid. Then I tried: oc login –insecure-skip-tls-verify, which results in: Error from server: Internal error occurred: unexpected response: 503. Any help appreciated ;)

    • Grant Shipley

      The correct command is:

      $ oc login –server= –insecure-skip-tls-verify=true

      • Ken

        Minor correction:
        oc login –server= –insecure-skip-tls-verify=true
        oc login –insecure-skip-tls-verify=true

        Need the s on http otherwise you will get a malformed response.

  3. Camilo Crespo

    If I do: oc login it works. It might be a good idea to verify this and update tutorial if needed. Great post by the way!!!

  4. Sal Carceller

    I have experience with OpenShift and have already followed the labs in your book OpenShift for Developers. I’m now looking for a decent book on Jenkins usage with OpenShift, any recommendation? I have a OSE local install already and have it working with GitHub and webhooks, looking for next steps with Jenkins. Thanks in advance.

  5. CK Gan

    I am new to OpenShift, managed to get the VM running. What is the login id and password for the Fedora OS? Without this I am not able to shutdown the VM.

  6. Bas Meijer

    Launching the box takes forever on OSX Sierra, Vagrant 1.8.6, VirtualBox 5.1.10.

Comments are closed.