Red Hat Training

A Red Hat training course is available for OpenShift Container Platform

Chapter 2. Source-to-Image (S2I)

2.1. Overview

This topic group includes information on the different S2I (Source-to-Image) supported images available for OpenShift Container Platform users.

2.2. .NET Core

2.2.1. Benefits of Using .NET Core

.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 Container Platform via certified containers. .NET Core offers:

  • The ability to follow a microservices-based approach, where some components are built with .NET and others with Java, but all can run on a common, supported platform in Red Hat Enterprise Linux and OpenShift Container Platform.
  • The capacity to more easily develop new .NET Core workloads on Windows; customers are able to deploy and run on either Red Hat Enterprise Linux or Windows Server.
  • A heterogeneous data center, where the underlying infrastructure is capable of running .NET applications without having to rely solely on Windows Server.
  • Access to many of the popular development frameworks such as .NET, Java, Ruby, and Python from within OpenShift Container Platform.

2.2.2. Supported Versions

  • .NET Core version 1.0
  • .NET Core version 1.1
  • Supported on Red Hat Enterprise Linux (RHEL) 7 and OpenShift Container Platform versions 3.3 and later

2.2.3. Images

Image stream definitions for the .NET Core on RHEL S2I image are now added during OpenShift Container Platform installations.

The RHEL 7 images are available through Red Hat’s subscription registry using: 

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

To use these images, you can either access them directly from these image registries, or push them into your OpenShift Container Platform Docker registry. Additionally, you can create an image stream that points to the image, either in your Docker registry or at the external location. Your OpenShift Container Platform resources can then reference the image stream definition.

2.2.4. Configuration

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

Note

You must set environment variables that control build behavior in the S2I build configuration or in the .s2i/environment file in order to make them available to the build steps.

Table 2.1. NET Core Environment Variables

Variable NameDescriptionDefault

DOTNET_STARTUP_PROJECT

Used to select the project to run. This must be the folder in the source repository containing project.json.

.

DOTNET_PUBLISH

Used to control whether the application should be built by executing dotnet build or dotnet publish. To publish the application, set the value to true. It is recommended to publish your application.

For backwards compatibility, the default is false.

In the next major release, this variable will be removed and the builder will always publish the application.

DOTNET_ASSEMBLY_NAME

Used to select the assembly to run. This must not include the .dll extension. Set this to the output assembly name specified in project.json (name, buildOptions/outputName). For project.json, the assembly name defaults to the project.json parent folder. When project.json is at the context-dir, the parent folder name will be src. So, by default, this generates a src.dll assembly. Setting DOTNET_ASSEMBLY_NAME will cause:

  • The assembly to be <DOTNET_ASSEMBLY_NAME>.dll
  • The application sources to be in subfolder DOTNET_ASSEMBLY_NAME in the deployed container.

The name of the DOTNET_STARTUP_PROJECT folder.

DOTNET_RESTORE_SOURCES

Used to specify the space-separated list of NuGet package sources used during the restore operation. This overrides all of the sources specified in the NuGet.config file.

Unset

DOTNET_NPM_TOOLS

Used to specify a list of NPM packages to install before building the application.

Unset

DOTNET_TEST_PROJECTS

Used to specify the space-separated list of test projects to run. This must be folders containing project.json. dotnet test is invoked for each folder.

Unset

DOTNET_CONFIGURATION

Used to run the application in Debug or Release mode. This value should be either Release or Debug.

Release

ASPNETCORE_URLS

This variable is set to http://*:8080 to configure ASP.NET Core to use the port exposed by the image. It is not recommended to change this.

http://*:8080

2.2.5. Quickly Deploying Applications from .NET Core Source

Important

The .NET image stream must first be installed. If you ran a standard installation, the image stream will be present.

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

$ oc new-app registry.access.redhat.com/dotnet/dotnetcore-10-rhel7~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-1.0 --context-dir=app
$ oc new-app registry.access.redhat.com/dotnet/dotnetcore-11-rhel7~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-1.1 --context-dir=app
Note

The oc new-app command can detect .NET Core source starting in OpenShift Container Platform 3.3.

2.2.6. .NET Core Templates

Important

The .NET image templates and the .NET images streams must first be installed. If you ran a standard installation, the templates and image streams will be present. This can be checked with: 

$ (oc get -n openshift templates; oc get -n openshift is) | grep dotnet

OpenShift Container Platform includes templates for the .NET Core images to help easily deploy a sample application.

The .NET Core sample application running on dotnet/dotnetcore-10-rhel7 can be deployed with: 

$ oc new-app --template dotnet-example

The .NET Core sample application running on dotnet/dotnetcore-11-rhel7 can be deployed with: 

$ oc new-app --template dotnet-example -p DOTNET_IMAGE_STREAM_TAG=dotnet:1.1 -p SOURCE_REPOSITORY_REF=dotnetcore-1.1

The .NET Core MusicStore application using PostgreSQL as database can be deployed with: 

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

2.3. Node.js

2.3.1. Overview

OpenShift Container Platform 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 Container Platform or by Docker.

2.3.2. Versions

Currently, OpenShift Container Platform provides versions 0.10 and 4 of Node.js.

2.3.3. Images

These images come in two flavors, depending on your needs:

  • RHEL 7
  • CentOS 7

RHEL 7 Based Images

The 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

CentOS 7 Based Image

This image is available on Docker Hub: 

$ docker pull openshift/nodejs-010-centos7

To use these images, you can either access them directly from these image registries, or push them into your OpenShift Container Platform Docker registry. Additionally, you can create an image stream that points to the image, either in your Docker registry or at the external location. Your OpenShift Container Platform resources can then reference the ImageStream. You can find example image stream definitions for all the provided OpenShift Container Platform images.

2.3.4. Configuration

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.

Note

Environment variables that control build behavior must be set as part of the s2i build configuration or in the .s2i/environment file to make them available to the build steps.

Table 2.2. Development Mode Environment Variables

Variable nameDescription

DEV_MODE

When set to true, enables hot deploy and opens the debug port. Additionally, indicates to tooling that the image is in development mode. Default is false.

DEBUG_PORT

The debug port. Only valid if DEV_MODE is set to true. Default is 5858.

NPM_MIRROR

The custom NPM registry mirror URL. All NPM packages will be downloaded from the mirror link during the build process.

2.3.5. Hot Deploying

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.

Warning

Only use the DEV_MODE=true environment variable while developing or debugging. Using this in your production environment is not recommended.

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.

2.4. Perl

2.4.1. Overview

OpenShift Container Platform 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 Container Platform or by Docker.

2.4.2. Versions

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

2.4.3. Images

Images comes in two flavors, depending on your needs:

  • RHEL 7
  • CentOS 7

RHEL 7 Based Images

The 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

CentOS 7 Based Image

A CentOS image for Perl 5.16 is available on Docker Hub: 

$ docker pull openshift/perl-516-centos7

To use these images, you can either access them directly from these image registries or push them into your OpenShift Container Platform Docker registry. Additionally, you can create an image stream that points to the image, either in your Docker registry or at the external location. Your OpenShift Container Platformt resources can then reference the ImageStream. You can find example image stream definitions for all the provided OpenShift Container Platform images.

2.4.4. Configuration

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.

Note

Environment variables that control build behavior must be set as part of the s2i build configuration or in the .s2i/environment file to make them available to the build steps.

Table 2.3. Perl Environment Variables

Variable nameDescription

ENABLE_CPAN_TEST

When set to true, this variable installs all the cpan modules and runs their tests. By default, the testing of the modules is turned off.

CPAN_MIRROR

This variable specifies a mirror URL which cpanminus uses to install dependencies. By default, this URL is not specified.

PERL_APACHE2_RELOAD

Set this to true to enable automatic reloading of modified Perl modules. By default, automatic reloading is turned off.

HTTPD_START_SERVERS

The StartServers directive sets the number of child server processes created on startup. Default is 8.

HTTPD_MAX_REQUEST_WORKERS

Number of simultaneous requests that will be handled by Apache. The default is 256, but it will be automatically lowered if memory is limited.

2.4.5. Accessing Logs

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.

2.4.6. Hot Deploying

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.

Warning

You should only use this option while developing or debugging; it is not recommended to turn this on in your production environment.

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.

2.5. PHP

2.5.1. Overview

OpenShift Container Platform 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 Container Platform or by Docker.

2.5.2. Versions

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

2.5.3. Images

These images come in two flavors, depending on your needs:

  • RHEL 7
  • CentOS 7

RHEL 7 Based Images

The 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

CentOS 7 Based Images

CentOS images for PHP 5.5 and 5.6 are available on Docker Hub: 

$ docker pull openshift/php-55-centos7
$ docker pull openshift/php-56-centos7

To use these images, you can either access them directly from these image registries or push them into your OpenShift Container Platform Docker registry. Additionally, you can create an image stream that points to the image, either in your Docker registry or at the external location. Your OpenShift Container Platform resources can then reference the image stream.

You can find example image stream definitions for all the provided OpenShift Container Platform images.

2.5.4. Configuration

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.

Note

Environment variables that control build behavior must be set as part of the s2i build configuration or in the .s2i/environment file to make them available to the build steps.

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

Table 2.4. PHP Environment Variables

Variable NameDescriptionDefault

ERROR_REPORTING

Informs PHP of the errors, warnings, and notices for which you would like it to take action.

E_ALL & ~E_NOTICE

DISPLAY_ERRORS

Controls if and where PHP outputs errors, notices, and warnings.

ON

DISPLAY_STARTUP_ERRORS

Causes any display errors that occur during PHP’s startup sequence to be handled separately from display errors.

OFF

TRACK_ERRORS

Stores the last error/warning message in $php_errormsg (boolean).

OFF

HTML_ERRORS

Links errors to documentation that is related to the error.

ON

INCLUDE_PATH

Path for PHP source files.

.:/opt/openshift/src:/opt/rh/php55/root/usr/share/pear

SESSION_PATH

Location for session data files.

/tmp/sessions

DOCUMENTROOT

Path that defines the document root for your application (for example, /public).

/

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

Table 2.5. Additional PHP settings

Variable NameDescriptionDefault

OPCACHE_MEMORY_CONSUMPTION

The OPcache shared memory storage size.

16M

OPCACHE_REVALIDATE_FREQ

How often to check script time stamps for updates, in seconds. 0 results in OPcache checking for updates on every request.

2

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

Table 2.6. Additional PHP settings

Variable NameDescription

PHPRC

Sets the path to the php.ini file.

PHP_INI_SCAN_DIR

Path to scan for additional .ini configuration files

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

Table 2.7. Composer Environment Variables

Variable NameDescriptionCOMPOSER_MIRROR

2.5.4.1. Apache Configuration

If the DocumentRoot of the application is nested in the source directory /opt/openshift/src, you can provide your own .htaccess file to override the default Apache behavior and specify how application requests should be handled. The .htaccess file must be located at the root of the application source.

2.5.5. Accessing Logs

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.

2.5.6. Hot Deploying

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.

Warning

You should only use this option while developing or debugging; it is not recommended to turn this on in your production environment.

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.

2.6. Python

2.6.1. Overview

OpenShift Container Platform 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 Container Platform or by Docker.

2.6.2. Versions

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

2.6.3. Images

These images come in two flavors, depending on your needs:

  • RHEL 7
  • CentOS 7

RHEL 7 Based Images

The 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

CentOS 7 Based Images

These images are available on Docker Hub: 

$ docker pull centos/python-27-centos7
$ docker pull openshift/python-33-centos7
$ docker pull centos/python-34-centos7
$ docker pull centos/python-35-centos7

To use these images, you can either access them directly from these image registries or push them into your OpenShift Container Platform Docker registry. Additionally, you can create an image stream that points to the image, either in your Docker registry or at the external location. Your OpenShift Container Platform resources can then reference the ImageStream. You can find example image stream definitions for all the provided OpenShift Container Platform images.

2.6.4. Configuration

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.

Note

Environment variables that control build behavior must be set as part of the s2i build configuration or in the .s2i/environment file to make them available to the build steps.

Table 2.8. Python Environment Variables

Variable nameDescription

APP_FILE

This variable specifies the file name passed to the python interpreter which is responsible for launching the application. This variable is set to app.py by default.

APP_MODULE

This variable specifies the WSGI callable. It follows the pattern $(MODULE_NAME):$(VARIABLE_NAME), where the module name is a full dotted path and the variable name refers to a function inside the specified module. If you use setup.py for installing the application, then the module name can be read from that file and the variable defaults to application. There is an example setup-test-app available.

APP_CONFIG

This variable indicates the path to a valid Python file with a gunicorn configuration.

DISABLE_COLLECTSTATIC

Set it to a nonempty value to inhibit the execution of manage.py collectstatic during the build. Only affects Django projects.

DISABLE_MIGRATE

Set it to a nonempty value to inhibit the execution of manage.py migrate when the produced image is run. Only affects Django projects.

PIP_INDEX_URL

Set this variable to use a custom index URL or mirror to download required packages during build process. This only affects packages listed in the requirements.txt file.

WEB_CONCURRENCY

Set this to change the default setting for the number of workers. By default, this is set to the number of available cores times 4.

2.6.5. Hot Deploying

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.

Warning

You should only use this option while developing or debugging; it is not recommended to turn this on in your production environment.

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.

2.7. Ruby

2.7.1. Overview

OpenShift Container Platform 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 Container Platform or by Docker.

2.7.2. Versions

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

2.7.3. Images

These images come in two flavors, depending on your needs:

  • RHEL 7
  • CentOS 7

RHEL 7 Based Images

The 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

CentOS 7 Based Images

These images are available on Docker Hub: 

$ docker pull openshift/ruby-20-centos7
$ docker pull openshift/ruby-22-centos7
$ docker pull centos/ruby-23-centos7

To use these images, you can either access them directly from these image registries or push them into your OpenShift Container Platform Docker registry. Additionally, you can create an image stream that points to the image, either in your Docker registry or at the external location. Your OpenShift Container Platform resources can then reference the ImageStream. You can find example image stream definitions for all the provided OpenShift Container Platform images.

2.7.4. Configuration

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.

Note

Environment variables that control build behavior must be set as part of the s2i build configuration or in the .s2i/environment file to make them available to the build steps.

Table 2.9. Ruby Environment Variables

Variable nameDescription

RACK_ENV

This variable specifies the environment within which the Ruby application is deployed; for example, production, development, or test. Each level has different behavior in terms of logging verbosity, error pages, and ruby gem installation. The application assets are only compiled if RACK_ENV is set to production; the default value is production.

RAILS_ENV

This variable specifies the environment within which the Ruby on Rails application is deployed; for example, production, development, or test. Each level has different behavior in terms of logging verbosity, error pages, and ruby gem installation. The application assets are only compiled if RAILS_ENV is set to production. This variable is set to ${RACK_ENV} by default.

DISABLE_ASSET_COMPILATION

When set to true, this variable disables the process of asset compilation. Asset compilation only happens when the application runs in a production environment. Therefore, you can use this variable when assets have already been compiled.

PUMA_MIN_THREADS, PUMA_MAX_THREADS

This variable indicates the minimum and maximum number of threads that will be available in Puma's thread pool.

PUMA_WORKERS

This variable indicates the number of worker processes to be launched in Puma’s clustered mode (when Puma runs more than two processes). If not explicitly set, the default behavior sets PUMA_WORKERS to a value that is appropriate for the memory available to the container and the number of cores on the host.

RUBYGEM_MIRROR

Set this variable to use a custom RubyGems mirror URL to download required gem packages during the build process. Note: This environment variable is only available for Ruby 2.2+ images.

2.7.5. Hot Deploying

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.

Warning

You should only use this option while developing or debugging; it is not recommended to turn this on in your production environment.

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.