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/ # 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 ./ ./s2i ./sti
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
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
|Dockerfile||Yes||Defines the base builder image|
|s2i/bin/assemble||Yes||Script that builds the application|
|s2i/bin/usage||No||Script that prints the usage of the builder|
|s2i/bin/run||Yes||Script that runs the application|
|s2i/bin/save-artifacts||No||Script for incremental builds that saves the built artifacts|
|test/run||No||Test script for the builder image|
|test/test-app||Yes||Test 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.
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