2021 Call for Code Awards: Live from New York, with SNL’s Colin Jost! Learn more

Create your own source-to-image entry in an OpenShift cluster

In this tutorial, you learn how to create your own source-to-image (S2I) entry for an OpenShift cluster. For example, if you plan to deploy multiple apps to the cloud, you could use your custom S2I rather than building individual images for each project or app. Or, maybe you want to use S2I and GitHub webhooks if you have an app that gets updated on GitHub and you want the updates to automatically trigger and deploy a build. The examples in this tutorial use Red Hat® OpenShift® on IBM Cloud™.


To complete this tutorial you need to set up the following environment:

Estimated time

Completing this tutorial should take about 20 minutes.

Step 1: Understand builder images and Docker images

OpenShift source-to-image entries are created from a builder image. These images are used for building reproducible container images from source code. This tutorial focuses on Docker images on Docker Hub.

With Docker, you have a few options for creating a source-to-image entry:

  • Build a base image from scratch.
  • Build a parent image from an existing base image.
  • Use an existing base or parent image from Docker Hub.

Step 2: Build a Go parent image

For this tutorial, you build a simple Go parent image from an existing base image. To begin, save the following into a Dockerfile:

FROM centos/go-toolset-7-centos7:latest

All this is doing is using the existing base image and exposing port 8080 to allow us to access an application that runs in a container from this image.

Step 3: Push your new image to Docker Hub

From the directory where your Dockerfile is located, push your new image to Docker Hub with the following commands:

export DOCKERHUB_USERNAME=<your-dockerhub-username>
docker build -t $DOCKERHUB_USERNAME/go_s2i:latest .
docker login
docker push $DOCKERHUB_USERNAME/go_s2i:latest

Step 4: Define an image stream

The next thing we need to do is define an Image Stream. To do this, we will create goImageStream.json which will consist of the following:

NOTE: Replace <your-dockerhub-username> with your actual Docker Hub username

    "apiVersion": "v1",
    "kind": "ImageStream",
    "metadata": {
        "annotations": {
            "openshift.io/display-name": "Go"
        "name": "golang"
    "spec": {
        "tags": [
                "name": "latest",
                "annotations": {
                    "description": "Build and run Go applications on CentOS 7 using this builder image",
                    "iconClass": "icon-go-gopher",
                    "openshift.io/display-name": "Go (Latest)",
                    "supports": "golang",
                    "tags": "builder,golang,go"
                "from": {
                    "kind": "DockerImage",
                    "name": "docker.io/<your-dockerhub-username>/go_s2i:latest"
                "referencePolicy": {
                    "type": "Local"

Step 5: Create the S2I entry in your OpenShift cluster

After you provision an OpenShift cluster on IBM Cloud, open the OpenShift web console and copy your login command into a terminal window. From the directory where your newly created goImageStream.json file is, run the following command to create your own source to image entry in your OpenShift cluster:

oc apply -n openshift --as system:admin -f goImageStream.json

Refresh your OpenShift web console, and you should see a Go entry in the catalog.

Step 6: Create an S2I application using the builder image

You can now create an S2I application using this builder image. Create a new project and select the new Go option from the catalog. Select the newly created project and give the application a name. For the Git Repository, use https://github.com/sclorg/golang-ex.git

This repository is a simple Go application that displays Hello OpenShift! in the browser. After the application is done building, click on the created route and you should see the application running.


You have now successfully created a builder image on Docker Hub, defined and applied an image stream to your OpenShift cluster, and deployed an application to OpenShift using your own Source-to-Image entry. You can try this on your own with Red Hat OpenShift on IBM Cloud.

To learn more about Source-to-Image, you can watch this video.