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.8To 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 filesUsing 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.gitChange to Nginx version folder.
cd nginx-container
git submodule update --init
cd 1.24For using other versions of Nginx, just replace the 1.24 value by particular version in the commands above.
Files and Directories in the repository
| File | Required? | Description |
|---|---|---|
| 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 Fedora bbuilder image named nginx-fedora.
docker||podman build -f Dockerfile.fedora -t nginx-fedora .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.24
$ s2i build test/test-app nginx-fedora nginx-fedora-app
---> Installing application source
---> Copying nginx.conf configuration file…
'./nginx.conf' -> '/etc/opt/rh/rh-nginx124/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 successfullyUsing 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 320MBRunning the application image
Run the application image by invoking the docker run command:
docker run -d -p 8080:8080 nginx-centos7-appThe 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:
