Chapter 2. Source-to-Image (S2I)

OpenShift Online provides an S2I builder image for building Java applications. This builder image takes your application source or binary artifacts, builds the source using Maven (if source was provided), and assembles the artifacts with any required dependencies to create a new, ready-to-run image containing your Java application. This resulting image can be run on OpenShift Online or run directly with Docker.

The builder image is intended for use with Maven-based Java standalone projects that are run via main class.

The current version of the Java S2I builder image supports OpenJDK 1.8, Jolokia 1.3.5, and Maven 3.3.9-2.8.

The RHEL 7 image is available through the Red Hat Registry:

$ docker pull registry.access.redhat.com/redhat-openjdk-18/openjdk18-openshift

You can use the image through the redhat-openjdk18-openshift image stream.

S2I produces ready-to-run images by injecting source code into a container and letting the container prepare that source code for execution. It performs the following steps:

See S2I Build Process for a detailed overview of the build process.

By default, the Java S2I builder image uses Maven to build the project with the following goals and options:

mvn -Dmaven.repo.local=/tmp/artifacts/m2 -s /tmp/artifacts/configuration/settings.xml -e -Popenshift -DskipTests -Dcom.redhat.xpaas.repo.redhatga -Dfabric8.skip=true package -Djava.net.preferIPv4Stack=true

Based on these defaults, the builder image compiles the project and copies all the transitive dependencies into the output directory without running tests. Additionally, if the project has a profile named openshift, then it is activated for the build.

You can override these default goals and options by specifying the following environment variables:

The same S2I builder image can be used to build a Java application from source or from binary artifacts.

The Java S2I builder image can be used to build an application from source by running oc new-app against a source repository:

$ oc new-app redhat-openjdk18-openshift~https://github.com/jboss-openshift/openshift-quickstarts --context-dir=undertow-servlet

By default, tests are not run. To build an application and run tests as part of the build, override the default MAVEN_ARGS, as in the following command:

$ oc new-app redhat-openjdk18-openshift~<git_repo_URL> --context-dir=<context-dir> --build-env='MAVEN_ARGS=-e -Popenshift -Dcom.redhat.xpaas.repo.redhatga package'

If a Java project consists of multiple Maven modules, it can be useful to explicitly specify the artifact output directory. Specifying the directory where the Maven project outputs the artifacts enables the S2I build to pick them up.

To specify the modules to build and the artifact output directory, use the following command:

$ oc new-app redhat-openjdk18-openshift~<git_repo_URL> --context-dir=<context-dir> --build-env='ARTIFACT_DIR=relative/path/to/artifacts/dir' --build-env='MAVEN_ARGS=install -pl <groupId>:<artifactId> -am'

The Java S2I builder image can be used to build an application using binary artifacts that you provide. To do so, first create a new binary build using the oc new-build command:

$ oc new-build --name=<application-name> redhat-openjdk18-openshift --binary=true

Next, start a build using the oc start-build command, specifying the path to the binary artifacts on your local machine:

$ oc start-build <application-name> --from-dir=/path/to/artifacts --follow

Finally, use the oc new-app command to create an application:

$ oc new-app <application-name>

.NET Core is a general purpose development platform featuring automatic memory management and modern programming languages. It allows users to build high-quality applications efficiently. .NET Core is available on Red Hat Enterprise Linux (RHEL 7) and OpenShift Online via certified containers. .NET Core offers:

For release details related to .NET Core version 2.2, see Release Notes for Containers.

For release details related to .NET Core version 2.1, see Release Notes for Containers.

Versions 1.1 and 1.0 (rh-dotnetcore11 and rh-dotnetcore10) ship with the project.json build system (1.0.0-preview2 SDK). See the Known Issues chapter in the version 1.1 Release Notes for details on installing this SDK on a non-RHEL system.

The RHEL 7 images are available through the Red Hat Registry:

$ docker pull registry.access.redhat.com/dotnet/dotnet-22-rhel7
$ docker pull registry.access.redhat.com/dotnet/dotnet-21-rhel7
$ docker pull registry.access.redhat.com/dotnet/dotnetcore-11-rhel7
$ docker pull registry.access.redhat.com/dotnet/dotnetcore-10-rhel7

You can use these images through the dotnet image stream.

S2I produces ready-to-run images by injecting source code into a container and letting the container prepare that source code for execution. It performs the following steps:

See S2I Build Process for a detailed overview of the build process.

The .NET Core images support several environment variables, which you can set to control the build behavior of your .NET Core application.

An image can be used to build an application by running oc new-app against a sample repository:

$ oc new-app dotnet:2.2~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-2.2 --context-dir=app
$ oc new-app dotnet:2.1~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-2.1 --context-dir=app
$ oc new-app dotnet:1.1~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-1.1 --context-dir=app
$ oc new-app dotnet:1.0~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-1.0 --context-dir=app

OpenShift Online provides S2I enabled Node.js images for building and running Node.js applications. The Node.js S2I builder image assembles your application source with any required dependencies to create a new image containing your Node.js application. This resulting image can be run either by OpenShift Online or by Docker.

Currently, OpenShift Online provides versions 4, and 6 of Node.js.

RHEL 7 images are available through the Red Hat Registry:

$ docker pull registry.access.redhat.com/openshift3/nodejs-010-rhel7
$ docker pull registry.access.redhat.com/rhscl/nodejs-4-rhel7

You can use these images through the nodejs image stream.

S2I produces ready-to-run images by injecting source code into a container and letting the container prepare that source code for execution. It performs the following steps:

See S2I Build Process for a detailed overview of the build process.

The Node.js image supports a number of environment variables, which can be set to control the configuration and behavior of the Node.js runtime.

To set these environment variables as part of your image, you can place them into a .s2i/environment file inside your source code repository, or define them in the environment section of the build configuration’s sourceStrategy definition.

You can also set environment variables to be used with an existing image when creating new applications, or by updating environment variables for existing objects such as deployment configurations.

Hot deployment allows you to quickly make and deploy changes to your application without having to generate a new S2I build. In order to immediately pick up changes made in your application source code, you must run your built image with the DEV_MODE=true environment variable.

You can set new environment variables when creating new applications, or updating environment variables for existing objects.

To change the source code of a running pod, open a remote shell into the container:

$ oc rsh <pod_id>

Entering into a running container changes your current directory to /opt/app-root/src, where the source code is located.

OpenShift Online includes an example template to deploy a sample Node.js application. This template builds and deploys the sample application on Node.js with a MongoDB database using a persistent volume for storage.

The sample application can be built and deployed using the rhscl/nodejs-4-rhel7 image with the following command:

$ oc new-app --template=nodejs-mongo-persistent

OpenShift Online provides S2I enabled Perl images for building and running Perl applications. The Perl S2I builder image assembles your application source with any required dependencies to create a new image containing your Perl application. This resulting image can be run either by OpenShift Online or by Docker.

Currently, OpenShift Online supports versions 5.16, 5.20, and 5.24 of Perl.

RHEL 7 images are available through the Red Hat Registry:

$ docker pull registry.access.redhat.com/openshift3/perl-516-rhel7
$ docker pull registry.access.redhat.com/rhscl/perl-520-rhel7
$ docker pull registry.access.redhat.com/rhscl/perl-524-rhel7

You can use these images through the perl image stream.

S2I produces ready-to-run images by injecting source code into a container and letting the container prepare that source code for execution. It performs the following steps:

See S2I Build Process for a detailed overview of the build process.

The Perl image supports a number of environment variables which can be set to control the configuration and behavior of the Perl runtime.

To set these environment variables as part of your image, you can place them into a .s2i/environment file inside your source code repository, or define them in the environment section of the build configuration’s sourceStrategy definition.

You can also set environment variables to be used with an existing image when creating new applications, or by updating environment variables for existing objects such as deployment configurations.

Access logs are streamed to standard output and as such they can be viewed using the oc logs command. Error logs are stored in the /tmp/error_log file, which can be viewed using the oc rsh command to access the container.

Hot deployment allows you to quickly make and deploy changes to your application without having to generate a new S2I build. To enable hot deployment in this image, you must set the PERL_APACHE2_RELOAD environment variable to true. For example, see the oc new-app command. You can use the oc set env command to update environment variables of existing objects.

To change your source code in a running pod, use the oc rsh command to enter the container:

$ oc rsh <pod_id>

After you enter into the running container, your current directory is set to /opt/app-root/src, where the source code is located.

OpenShift Online includes an example template to deploy a sample Dancer application. This template builds and deploys the sample application on Perl 5.24 with a MySQL database using a persistent volume for storage.

The sample application can be built and deployed using the rhscl/perl-524-rhel7 image with the following command:

$ oc new-app --template=dancer-mysql-persistent

OpenShift Online provides S2I enabled PHP images for building and running PHP applications. The PHP S2I builder image assembles your application source with any required dependencies to create a new image containing your PHP application. This resulting image can be run either by OpenShift Online or by Docker.

Currently, OpenShift Online provides versions 5.5, 5.6, and 7.0 of PHP.

RHEL 7 images are available through the Red Hat Registry:

$ docker pull registry.access.redhat.com/openshift3/php-55-rhel7
$ docker pull registry.access.redhat.com/rhscl/php-56-rhel7
$ docker pull registry.access.redhat.com/rhscl/php-70-rhel7

You can use these images through the php image stream.

S2I produces ready-to-run images by injecting source code into a container and letting the container prepare that source code for execution. It performs the following steps:

See S2I Build Process for a detailed overview of the build process.

The PHP image supports a number of environment variables which can be set to control the configuration and behavior of the PHP runtime.

To set these environment variables as part of your image, you can place them into a .s2i/environment file inside your source code repository, or define them in the environment section of the build configuration’s sourceStrategy definition.

You can also set environment variables to be used with an existing image when creating new applications, or by updating environment variables for existing objects such as deployment configurations.

The following environment variables set their equivalent property value in the php.ini file:

The following environment variable sets its equivalent property value in the opcache.ini file:

You can also override the entire directory used to load the PHP configuration by setting:

You can use a custom composer repository mirror URL to download packages instead of the default 'packagist.org':

Access logs are streamed to standard out and as such they can be viewed using the oc logs command. Error logs are stored in the /tmp/error_log file, which can be viewed using the oc rsh command to access the container.

Hot deployment allows you to quickly make and deploy changes to your application without having to generate a new S2I build. In order to immediately pick up changes made in your application source code, you must run your built image with the OPCACHE_REVALIDATE_FREQ=0 environment variable.

For example, see the oc new-app command. You can use the oc env command to update environment variables of existing objects.

To change your source code in a running pod, use the oc rsh command to enter the container:

$ oc rsh <pod_id>

After you enter into the running container, your current directory is set to /opt/app-root/src, where the source code is located.

OpenShift Online includes example templates to deploy a sample CakePHP application or a sample Laravel application. Each template builds and deploys a sample application on PHP 7.0 with a MySQL database using a persistent volume for storage.

The sample CakePHP application can be built and deployed using the rhscl/php-70-rhel7 image with the following command:

$ oc new-app --template=cakephp-mysql-persistent

The sample Laravel application can be built and deployed using the rhscl/php-70-rhel7 image with the following command:

$ oc new-app --template=laravel-mysql-persistent

OpenShift Online provides S2I enabled Python images for building and running Python applications. The Python S2I builder image assembles your application source with any required dependencies to create a new image containing your Python application. This resulting image can be run either by OpenShift Online or by Docker.

Currently, OpenShift Online provides versions 2.7, 3.3, 3.4, and 3.5 of Python.

RHEL 7 images are available through the Red Hat Registry:

$ docker pull registry.access.redhat.com/rhscl/python-27-rhel7
$ docker pull registry.access.redhat.com/openshift3/python-33-rhel7
$ docker pull registry.access.redhat.com/rhscl/python-34-rhel7
$ docker pull registry.access.redhat.com/rhscl/python-35-rhel7

You can use these images through the python image stream.

S2I produces ready-to-run images by injecting source code into a container and letting the container prepare that source code for execution. It performs the following steps:

See S2I Build Process for a detailed overview of the build process.

The Python image supports a number of environment variables which can be set to control the configuration and behavior of the Python runtime.

To set these environment variables as part of your image, you can place them into a .s2i/environment file inside your source code repository, or define them in the environment section of the build configuration’s sourceStrategy definition.

You can also set environment variables to be used with an existing image when creating new applications, or by updating environment variables for existing objects such as deployment configurations.

Hot deployment allows you to quickly make and deploy changes to your application without having to generate a new S2I build. If you are using Django, hot deployment works out of the box.

To enable hot deployment while using Gunicorn, ensure you have a Gunicorn configuration file inside your repository with the reload option set to true. Specify your configuration file using the APP_CONFIG environment variable. For example, see the oc new-app command. You can use the oc set env command to update environment variables of existing objects.

To change your source code in a running pod, use the oc rsh command to enter the container:

$ oc rsh <pod_id>

After you enter into the running container, your current directory is set to /opt/app-root/src, where the source code is located.

OpenShift Online includes an example template to deploy a sample Django application. This template builds and deploys the sample application on Python 3.5 with a PostgreSQL database using a persistent volume for storage.

The sample application can be built and deployed using the rhscl/python-35-rhel7 image with the following command:

$ oc new-app --template=django-psql-persistent

OpenShift Online provides S2I enabled Ruby images for building and running Ruby applications. The Ruby S2I builder image assembles your application source with any required dependencies to create a new image containing your Ruby application. This resulting image can be run either by OpenShift Online or by Docker.

Currently, OpenShift Online provides versions 2.0, 2.2, and 2.3 of Ruby.

RHEL 7 images are available through the Red Hat registry:

$ docker pull registry.access.redhat.com/openshift3/ruby-20-rhel7
$ docker pull registry.access.redhat.com/rhscl/ruby-22-rhel7
$ docker pull registry.access.redhat.com/rhscl/ruby-23-rhel7

You can use these images through the ruby image stream.

S2I produces ready-to-run images by injecting source code into a container and letting the container prepare that source code for execution. It performs the following steps:

See S2I Build Process for a detailed overview of the build process.

The Ruby image supports a number of environment variables which can be set to control the configuration and behavior of the Ruby runtime.

To set these environment variables as part of your image, you can place them into a .s2i/environment file inside your source code repository, or define them in the environment section of the build configuration’s sourceStrategy definition.

You can also set environment variables to be used with an existing image when creating new applications, or by updating environment variables for existing objects such as deployment configurations.

Hot deployment allows you to quickly make and deploy changes to your application without having to generate a new S2I build. The method for enabling hot deployment in this image differs based on the application type.

Ruby on Rails Applications

For Ruby on Rails application, run the built Rails application with the RAILS_ENV=development environment variable passed to the running pod. For an existing deployment configuration, you can use the oc set env command:

$ oc set env dc/rails-app RAILS_ENV=development

Other Types of Ruby Applications (Sinatra, Padrino, etc.)

For other types of Ruby applications, your application must be built with a gem that can reload the server every time a change to the source code is made inside the running container. Those gems are:

In order to be able to run your application in development mode, you must modify the S2I run script so that the web server is launched by the chosen gem, which checks for changes in the source code.

After you build your application image with your version of the S2I run script, run the image with the RACK_ENV=development environment variable. For example, see the oc new-app command. You can use the oc set env command to update environment variables of existing objects.

To change your source code in a running pod, use the oc rsh command to enter the container:

$ oc rsh <pod_id>

After you enter into the running container, your current directory is set to /opt/app-root/src, where the source code is located.

OpenShift Online includes an example template to deploy a sample Rails application. This template builds and deploys the sample application on Ruby 2.3 with a PostgreSQL database using a persistent volume for storage.

The sample application can be built and deployed using the rhscl/ruby-23-rhel7 image with the following command:

$ oc new-app --template=rails-pgsql-persistent

S2I builder images normally include assemble and run scripts, but the default behavior of those scripts may not be suitable for all users. This topic covers a few approaches for customizing the behavior of an S2I builder that includes default scripts.

Typically, builder images provide their own version of the S2I scripts that cover the most common use-cases. If these scripts do not fulfill your needs, S2I provides a way of overriding them by adding custom ones in the .s2i/bin directory. However, by doing this you are completely replacing the standard scripts. In some cases this is acceptable, but in other scenarios you may prefer to execute a few commands before (or after) the scripts while retaining the logic of the script provided in the image. In this case, it is possible to create a wrapper script that executes custom logic and delegates further work to the default script in the image.

To determine the location of the scripts inside of the builder image, look at the value of io.openshift.s2i.scripts-url label. Use docker inspect:

$ docker inspect --format='{{ index .Config.Labels "io.openshift.s2i.scripts-url" }}' openshift/wildfly-100-centos7
image:///usr/libexec/s2i

You inspected the openshift/wildfly-100-centos7 builder image and found out that the scripts are in the /usr/libexec/s2i directory.

With this knowledge, invoke any of these scripts from your own by wrapping its invocation.

#!/bin/bash
echo "Before assembling"

/usr/libexec/s2i/assemble
rc=$?

if [ $rc -eq 0 ]; then
    echo "After successful assembling"
else
    echo "After failed assembling"
fi

exit $rc

The example shows a custom assemble script that prints the message, executes standard assemble script from the image and prints another message depending on the exit code of the assemble script.

When wrapping the run script, you must use exec for invoking it to ensure signals are handled properly. Unfortunately, the use of exec also precludes the ability to run additional commands after invoking the default image run script.

#!/bin/bash
echo "Before running application"
exec /usr/libexec/s2i/run