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 Enterprise users.
2.2. Node.js
2.2.1. Overview
OpenShift Enterprise 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 Enterprise or by Docker.
2.2.2. Versions
Currently, OpenShift Enterprise provides versions 0.10 and 4 of Node.js.
2.2.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 Enterprise 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 Enterprise resources can then reference the ImageStream. You can find example image stream definitions for all the provided OpenShift Enterprise images.
2.2.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.
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.
| Variable name | Description |
|---|---|
|
|
When set to |
|
|
The debug port. Only valid if |
|
| The custom NPM registry mirror URL. All NPM packages will be downloaded from the mirror link during the build process. |
2.2.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.
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.3. Ruby
2.3.1. Overview
OpenShift Enterprise 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 Enterprise or by Docker.
2.3.2. Versions
Currently, OpenShift Enterprise provides versions 2.0, 2.2, and 2.3 of Ruby.
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/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 Enterprise 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 Enterprise resources can then reference the ImageStream. You can find example image stream definitions for all the provided OpenShift Enterprise images.
2.3.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.
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.
| Variable name | Description |
|---|---|
|
|
This variable specifies the environment within which the Ruby application is deployed; for example, |
|
|
This variable specifies the environment within which the Ruby on Rails application is deployed; for example, |
|
|
When set to |
|
| This variable indicates the minimum and maximum number of threads that will be available in Puma's thread pool. |
|
|
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 |
|
| 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.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. 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.
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.4. Perl
2.4.1. Overview
OpenShift Enterprise 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 Enterprise or by Docker.
2.4.2. Versions
Currently, OpenShift Enterprise 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 Enterprise 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 Enterpriset resources can then reference the ImageStream. You can find example image stream definitions for all the provided OpenShift Enterprise 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.
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.
| Variable name | Description |
|---|---|
|
|
When set to |
|
| This variable specifies a mirror URL which cpanminus uses to install dependencies. By default, this URL is not specified. |
|
|
Set this to |
|
| The StartServers directive sets the number of child server processes created on startup. Default is 8. |
|
| 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.
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 Enterprise 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 Enterprise or by Docker.
2.5.2. Versions
Currently, OpenShift Enterprise 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 Enterprise 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 Enterprise resources can then reference the image stream.
You can find example image stream definitions for all the provided OpenShift Enterprise 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.
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:
| Variable Name | Description | Default |
|---|---|---|
|
| Informs PHP of the errors, warnings, and notices for which you would like it to take action. | E_ALL & ~E_NOTICE |
|
| Controls if and where PHP outputs errors, notices, and warnings. | ON |
|
| Causes any display errors that occur during PHP’s startup sequence to be handled separately from display errors. | OFF |
|
|
Stores the last error/warning message in | OFF |
|
| Links errors to documentation that is related to the error. | ON |
|
| Path for PHP source files. | .:/opt/openshift/src:/opt/rh/php55/root/usr/share/pear |
|
| Location for session data files. | /tmp/sessions |
|
| 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:
| Variable Name | Description | Default |
|---|---|---|
|
| The OPcache shared memory storage size. | 16M |
|
| 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:
| Variable Name | Description |
|---|---|
|
| Sets the path to the php.ini file. |
|
| 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':
| Variable Name | Description | COMPOSER_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.
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 Enterprise 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 Enterprise or by Docker.
2.6.2. Versions
Currently, OpenShift Enterprise 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 Enterprise 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 Enterprise resources can then reference the ImageStream. You can find example image stream definitions for all the provided OpenShift Enterprise 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.
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.
| Variable name | Description |
|---|---|
|
| 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. |
|
|
This variable specifies the WSGI callable. It follows the pattern |
|
| This variable indicates the path to a valid Python file with a gunicorn configuration. |
|
|
Set it to a nonempty value to inhibit the execution of |
|
|
Set it to a nonempty value to inhibit the execution of |
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.
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.
