Learn how to – Install and Use Source-To-Image (S2I) Toolkit on Linux

Learn how to – Install and Use Source-To-Image (S2I) Toolkit on Linux.

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

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/ 

# Linux
curl -s https://api.github.com/repos/openshift/source-to-image/releases/latest| grep browser_download_url | grep linux-amd64 | cut -d '"' -f 4  | wget -qi -

# macOS
 curl -s https://api.github.com/repos/openshift/source-to-image/releases/latest| grep browser_download_url | grep darwin-amd64 | cut -d '"' -f 4  | wget -qi -

Once downloaded, Unpack the tar using the command.

$ tar xvf source-to-image*.gz
./
./sti
./s2i

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                                                                         
/usr/local/bin/s2i

$ s2i version  
s2i v1.3.1

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 http://github.com/openshift/source-to-image

Usage:
  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

Flags:
      --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
├── README.md
├── 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 https://github.com/sclorg/nginx-container.git

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

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.

For detailed usage of S2I toolkit, check below resources.

• Descriptions and examples of the S2I commands
• Instructions for using builder images
• Guidance for S2I builder image creators
• Using a non-builder image for the base of the application image
• Troubleshooting and debugging S2I problems

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