Source-to-Image (S2I) is a toolkit and workflow for building reproducible container images from source code. S2I is used to produce ready-to-run images by injecting source code into a container image and letting the container prepare that source code for execution.

S2I gives you an easy way to version and control your build environments exactly like you use container images to version your runtime environments. Here we will show you how to easily install S2I Toolkit on a Linux system and use it to build container applications.

Install Source-To-Image (S2I) Toolkit on Linux – CentOS / Fedora / Ubuntu / Arch / Debian e.t.c

We will download Source-To-Image (S2I) binary package archive, extract it and place the binary file in our system PATH.

Visit the releases page and download the correct distribution for your machine. If on a 32-bit system, choose the linux-386 or the linux-amd64 for 64-bit.

mkdir /tmp/s2i/ && cd /tmp/s2i/ 
curl -s \
  | grep browser_download_url \
  | grep linux-amd64 \
  | cut -d '"' -f 4 \
  | wget -qi -

Once downloaded, Unpack the tar using the command.

$ tar xvf source-to-image*.gz

The file should be executable, move it to /usr/local/bin path.

sudo mv s2i /usr/local/bin
rm -rf /tmp/s2i/

Confirm file location and check installed version.

$ which s2i                                                                                                                      

$ s2i version  
s2i v1.1.14

To see usage help page, use:

$ s2i --help
Source-to-image (S2I) is a tool for building repeatable docker images.

A command line interface that injects and assembles source code into a docker image.
Complete documentation is available at

  s2i [flags]
  s2i [command]

Available Commands:
  build       Build a new image
  completion  Generate completion for the s2i command (bash or zsh)
  create      Bootstrap a new S2I image repository
  rebuild     Rebuild an existing image
  usage       Print usage of the assemble script associated with the image
  version     Display version

      --ca string        Set the path of the docker TLS ca file (default "/home/jmutai/.docker/ca.pem")
      --cert string      Set the path of the docker TLS certificate file (default "/home/jmutai/.docker/cert.pem")
      --key string       Set the path of the docker TLS key file (default "/home/jmutai/.docker/key.pem")
      --loglevel int32   Set the level of log output (0-5)
      --tls              Use TLS to connect to docker; implied by --tlsverify
      --tlsverify        Use TLS to connect to docker and verify the remote
  -U, --url string       Set the url of the docker socket to use (default "unix:///var/run/docker.sock")

Use "s2i [command] --help" for more information about a command.

To bootstrap a new S2I enabled image repository, use command syntax:

$ s2i create <image name> <destination directory>

This command will generate a skeleton .s2i directory and populate it with sample S2I scripts you can start hacking on. See example:

mkdir /tmp/s2i-test && cd /tmp/s2i-test
s2i create cent7-app .

The dir tree:

$ tree                                                       
├── Dockerfile
├── Makefile
├── s2i
│   └── bin
│       ├── assemble
│       ├── run
│       ├── save-artifacts
│       └── usage
└── test
    ├── run
    └── test-app
        └── index.html

4 directories, 9 files

Using Source-To-Image (S2I) on Linux

Now that we have installed the S2I tool, we can consider a simple example of how it can be used to build your images with applications. For simplicity, we’ll use Software Collections S2I repository which contains pre-created templates for many applications.

Our example is for Nginx web server. Let’s clone the repository with Dockerfiles for Nginx images for OpenShift. You can choose between RHEL and CentOS based images.

git clone --recursive

Change to Nginx version folder.

cd nginx-container
git submodule update --init
cd 1.12

For using other versions of Nginx, just replace the 1.12 value by particular version in the commands above.

Files and Directories in the repository

DockerfileYesDefines the base builder image
s2i/bin/assembleYesScript that builds the application
s2i/bin/usageNoScript that prints the usage of the builder
s2i/bin/runYesScript that runs the application
s2i/bin/save-artifactsNoScript for incremental builds that saves the built artifacts
test/runNoTest script for the builder image
test/test-appYesTest application source code

Once you have the repository locally, create a CentOS 7 builder image named nginx-centos7.

docker build -t nginx-centos7 .

Creating the application image

The application image combines the builder image with your applications source code, which is served using whatever application is installed via the Dockerfile, compiled using the assemble script, and run using the run script.

You can use the created image as a base to build a simple sample-app application that can be run on Openshift Container platform. The following command will create the application image:

$ cd nginx-container/1.12
$ s2i build test/test-app nginx-centos7 nginx-centos7-app
 ---> Installing application source
 ---> Copying nginx.conf configuration file…
 './nginx.conf' -> '/etc/opt/rh/rh-nginx112/nginx/nginx.conf'
 ---> Copying nginx configuration files…
 './nginx-cfg/default.conf' -> '/opt/app-root/etc/nginx.d/default.conf'
 ---> Copying nginx default server configuration files…
 './nginx-default-cfg/alias.conf' -> '/opt/app-root/etc/nginx.default.d/alias.conf'
 ---> Copying nginx start-hook scripts…
 Build completed successfully

Using the logic defined in the assemble script, s2i will now create an application image using the builder image as a base and including the source code from the test/test-app directory.

Check to confirm you have application image created.

$ docker images | grep nginx-centos7-app
nginx-centos7-app              latest              59cbe8e707c7        About a minute ago   320MB

Running the application image

Run the application image by invoking the docker run command:

docker run -d -p 8080:8080 nginx-centos7-app

The application deployed consists of a simple static web page and it should be accessible at http://localhost:8080.

install and use s2i

For detailed usage of S2I toolkit, check below resources.

For setting up Kubernetes/OpenShift locally in your machine, check:

Deploy Lightweight Kubernetes with MicroK8s and Snap

How to Setup OpenShift Origin (OKD) on Ubuntu

How To Setup Local OpenShift Origin (OKD) Cluster on CentOS 7

How to setup 3 node Kubernetes Cluster on Ubuntu 

How to Install Minikube on Ubuntu

Your support is our everlasting motivation,
that cup of coffee is what keeps us going!

As we continue to grow, we would wish to reach and impact more people who visit and take advantage of the guides we have on our blog. This is a big task for us and we are so far extremely grateful for the kind people who have shown amazing support for our work over the time we have been online.

Thank You for your support as we work to give you the best of guides and articles. Click below to buy us a coffee.


Please enter your comment!
Please enter your name here