Difficulty: intermediate
Estimated Time: 15-20 minutes

If this is the first time you are reading about Source-to-Image (S2I) it is strongly advised to start with one of the introductory tutorials which shows how to deploy an application from source code using an existing S2I Builder Image.

The goal of this tutorial is to show how to create a simplified S2I Builder Image yourself and then use the image to create another image containing your application.

This tutorial is divided into three parts.

  1. Introduction to creating an S2I Builder Image.
  2. Creating the S2I Builder Image.
  3. Using the S2I Builder Image.

In this tutorial, you learnt about S2I Builder Images and how to create and use them to produce new images containing applications.

There are several related blogs about deploying applications from images and here is another blog about creating S2I Builder Images.

Read more about the Anatomy of a builder image.

More examples of creating S2I Builder Images can be found here.

More can be read about S2I at the project's home page

Create your own S2I Builder Image

Step 1 of 3

Topic 1 - Introduction

Before we get started, you need to log in and create a project in OpenShift to work in.

To log in to the OpenShift cluster used for this course from the Terminal, run:

oc login -u developer -p developer

This will log you in using the credentials:

  • Username: developer
  • Password: developer

You should see the output:

Login successful.

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

    oc new-project <projectname>

To create a new project called myproject run the command:

oc new-project myproject

You should see output similar to:

Now using project "myproject" on server "".

The Source-To-Image (S2I) tool comes fully integrated with OpenShift. S2I is especially useful for developers as it can shield them from the details of creating Docker images.

Two of the main reasons to use S2I are:

  1. Developers can get up and running with Linux containers without knowing much (if at all) about Docker itself. This is great for Developers who just want to get their code running in a Linux container.
  2. Enterprises need more control over how their teams build images and don't want to allow developers the freedom to install anything they choose (as root) into container images. The S2I process constrains somewhat how the user builds images and does not allow anything to be installed during the S2I process using root privileges.

So, for this scenario, imagine you are a Lead Developer or an Operations Lead and want to create a way for your developers (OpenShift users) to easily and securely create docker images containing their applications.

The Simplified Runtime

For this scenario, we will avoid any complications with specific runtimes and/or languages and their build processes and use a very simple runtime.

The application "runtime" we will use is simply represented by the Linux command "cat" which displays the contents of files.

Our S2I Builder Image's runtime will contain the command "cat". To create an application image, the developer need only pass files ("source code") during the build process. The Builder container will know where to place the source code so that it can be later "executed" by the runtime "cat".

The S2I Build Process

The S2I Builder Image contains the scripts needed to first build the application and then to run the application.

S2I Build Process

As shown above, and in the simplest case, the process of building the application image is as follows:

  1. Instantiate the S2I Builder Image (this can be triggered automatically by a code change or by the user).
  2. Copy the source code into the running container.
  3. Execute the assemble script to build the source code to create the application.
  4. Commit the container to create the new image.

Running the Application Image

When the resulting application image is instantiated, the run script executes the cat command to display the contents of any "source code" stored inside the image.