openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 12:46:18 +01:00
Code Issues Releases Activity

OSDOCS-999 Bring forward S2I content

Browse Source
This commit is contained in:
bmcelvee
2020-11-16 17:48:27 -05:00
committed by openshift-cherrypick-robot
parent 8facf073e0
commit 3efa99d019
40 changed files with 1198 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
_topic_map.yml
View File

@@ -1393,6 +1393,10 @@ Topics:
File: images-other-jenkins
- Name: Jenkins agent
File: images-other-jenkins-agent
- Name: Source-to-image
File: using-s21-images
- Name: Customizing source-to-image images
File: customizing-s2i-images
---
Name: Applications
Dir: applications

69
_unused_topics/images-s2i-java-build-deploy-applications.adoc Normal file
View File

@@ -0,0 +1,69 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-s2i-java-build-deploy-applications_{context}"]
= Building and deploying Java applications
The same source-to-image (S2I) builder image can be used to build a Java application from source or from binary artifacts.
[id="images-s2i-java-build-deploy-applications-source_{context}"]
== Building and Deploying from Source
The Java S2I builder image can be used to build an application from source by running `oc new-app` against a source repository.
.Procedure
. To build an application from source, run `oc new-app` against a source repository. For example:
+
[source,terminal]
----
$ oc new-app registry.redhat.io/redhat-openjdk-18/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` by entering the following command:
+
[source,terminal]
----
$ oc new-app registry.redhat.io/redhat-openjdk-18/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:
+
[source,terminal]
----
$ oc new-app registry.redhat.io/redhat-openjdk-18/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'
----
[id="images-s2i-java-build-deploy-applications-bianary_{context}"]
== Building and deploying from binary artifacts
The Java S2I builder image can be used to build an application using binary
artifacts that you provide.
.Procedure
. Create a new binary build using the `oc new-build` command:
+
[source,terminal]
----
$ oc new-build --name=<application-name> registry.redhat.io/redhat-openjdk-18/openjdk18-openshift --binary=true
----
+
. Start a build using the `oc start-build` command, specifying the path to
the binary artifacts on your local machine:
+
[source,terminal]
----
$ oc start-build <application-name> --from-dir=/path/to/artifacts --follow
----
+
. Enter the `oc new-app` command to create an application:
+
[source,terminal]
----
$ oc new-app <application-name>
----

35
_unused_topics/images-s2i-java-configuration.adoc Normal file
View File

@@ -0,0 +1,35 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-s2i-java-configuration_{context}"]
= Configuring source-to-image for Java
By default, the Java source-to-image (S2I) builder image uses Maven to build the project with the following goals and options:
[source,bash]
----
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. 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:
.Java Environment Variables
[options="header"]
|===
|Variable name |Description
|`ARTIFACT_DIR`
|The relative path to the target where JAR files are created for multi-module builds.
|`JAVA_MAIN_CLASS`
|The main class to use as the argument to Java. This can also be specified in the _`s2i/environment` file as a Maven property inside the project, `docker.env.Main`.
|`MAVEN_ARGS`
|The arguments that are passed to the mvn command.
|===

23
_unused_topics/images-s2i-java-pulling-images.adoc Normal file
View File

@@ -0,0 +1,23 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-s2i-java-pulling-images_{context}"]
= Pulling images for Java
The Red Hat Enterprise Linux (RHEL) 8 image is available through the Red Hat Registry.
.Procedure
. To pull the RHEL 8 image, enter the following command:
[source,terminal]
----
$ podman pull registry.redhat.io/redhat-openjdk-18/openjdk18-openshift
----
To use this image on {product-title}, you can either access it directly from the Red Hat Registry or push it into your {product-title} container image registry. Additionally, you can create an image stream that points to the image, either in your container image registry or at the external location.
////
Your {product-title} resources can then reference the link:https://github.com/jboss-openshift/application-templates/blob/master/jboss-image-streams.json[image stream definition].
////

50
_unused_topics/images-s2i-nodejs-pulling-images.adoc Normal file
View File

@@ -0,0 +1,50 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-s2i-nodejs-pulling-images_{context}"]
= Pulling images for Node.js
//These images come in two options:
//* RHEL 8
//* CentOS 7
//*RHEL 8 Based Images*
The RHEL 8 images are available through the Red Hat Registry.
.Procedure
* To pull the RHEL 8 image, enter the following command for the version of Node.js you want:
+
.Node.js `12`
[source,terminal]
----
$ podman pull registry.redhat.io/rhscl/nodejs-12-rhel7:latest
----
+
.Node.js `10`
[source,terminal]
----
$ podman pull registry.redhat.io/rhscl/nodejs-10-rhel7:latest
----
////
*CentOS 7 Based Image*
This image is available on link:quay.io[Quay.io].
.Procedure
* To pull the CentOS 7 image, enter the following command:
+
[source,terminal]
----
$ podman pull openshift/nodejs-010-centos7
----
////
To use these images, you can either access them directly from registry.redhat.io, or push them into your {product-title} image registry. Additionally, you can create an image stream that points to the image, either in your container image registry or at the external location. Your {product-title} resources can then reference the
image stream.

16
_unused_topics/images-using-images-s2i-java.adoc Normal file
View File

@@ -0,0 +1,16 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-java_{context}"]
= Java overview
{product-title} provides a source-to-image (S2I) builder image for building Java applications. This builder image takes your application source or binary artifacts, builds the source using Maven if a 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 {product-title}.
The builder image is intended for use with link:https://maven.apache.org[Maven]-based Java standalone projects that are run with main class.
[discrete]
== Additional resources
* Find additional information and examples in the link:https://access.redhat.com/documentation/en-us/red_hat_jboss_middleware_for_openshift/3/html-single/red_hat_java_s2i_for_openshift/[Red Hat JBoss Middleware] documentation.

35
_unused_topics/images-using-images-s2i-nodejs-configuration.adoc Normal file
View File

@@ -0,0 +1,35 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-nodejs-configuration_{context}"]
= Configuring source-to-image for Node.js
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 source-to-image (S2I) build configuration or in the `.s2i/environment` file to make them available to the build steps.
====
.Development Mode Environment Variables
[cols="3a,6a",options="header"]
|===
| Variable name | Description
|`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 are downloaded from the mirror link during the build process.
|===

28
_unused_topics/images-using-images-s2i-nodejs-hot-deploying.adoc Normal file
View File

@@ -0,0 +1,28 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-nodejs-hot-deploying_{context}"]
= Hot deploying for Node.js
Hot deployment allows you to quickly make and deploy changes to your application without having to generate a new source-to-image (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.
====
.Procedure
* To change the source code of a running pod, open a remote shell into the container:
+
[source,terminal]
----
$ oc rsh <pod_id>
----
+
Entering into a running container changes your current directory to `/opt/app-root/src`, where the source code is located.

9
_unused_topics/images-using-images-s2i-nodejs.adoc Normal file
View File

@@ -0,0 +1,9 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-nodejs_{context}"]
= Node.js overview
{product-title} provides source-to-image (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 {product-title} or by a container runtime.

44
_unused_topics/images-using-images-s2i-perl-configuration.adoc Normal file
View File

@@ -0,0 +1,44 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-perl-configuration_{context}"]
= Configuring source-to-image for Perl
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 source-to-image (S2I) build configuration or in the `.s2i/environment` file to make them available to the build steps.
====
.Perl Environment Variables
[cols="4a,6a",options="header"]
|===
|Variable name |Description
|`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 disabled.
|`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 disabled.
|`HTTPD_START_SERVERS`
|The https://httpd.apache.org/docs/2.4/mod/mpm_common.html#startservers[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.
|===
//Verify` oc log` is still valid.

28
_unused_topics/images-using-images-s2i-perl-hot-deploying.adoc Normal file
View File

@@ -0,0 +1,28 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-perl-hot-deploying_{context}"]
= Hot deploying for Perl
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`. 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.
====
.Procedure
. To change your source code in a running pod, use the `oc rsh` command to enter the container:
+
[source,terminal]
----
$ 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.

50
_unused_topics/images-using-images-s2i-perl-pulling-images.adoc Normal file
View File

@@ -0,0 +1,50 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-perl-pulling-images_{context}"]
= Pulling images for Perl
//Images comes in two options:
//* RHEL 8
//* CentOS 7
// *RHEL 8 Based Images*
The RHEL 8 images are available through the Red Hat Registry.
.Procedure
* To pull the RHEL 8 image, enter the following command for the version of Perl you want:
+
.Perl `5.26`
[source,terminal]
----
$ podman pull registry.redhat.io/rhscl/perl-526-rhel7:latest
----
+
.Perl `5.30`
[source,terminal]
----
$ podman pull registry.redhat.io/rhscl/perl-530-rhel7:latest
----
////
*CentOS 7 Based Image*
A CentOS image for Perl 5.16 is available on link:quay.io[Quay.io].
.Procedure
* To pull the CentOS 7 image, enter the following command:
+
[source,terminal]
----
$ podman pull openshift/perl-516-centos7
----
////
To use these images, you can either access them directly from registry.redhat.io, or push them into your {product-title} image registry. Additionally, you can create an image stream that points to the image, either in your container image registry or at the external location. Your {product-title} resources can then reference the
image stream.

13
_unused_topics/images-using-images-s2i-perl.adoc Normal file
View File

@@ -0,0 +1,13 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-perl_{context}"]
= Perl overview
{product-title} provides source-to-image (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 {product-title} or by a container runtime.
[id="images-using-images-s2i-perl-accessing-logs_{context}"]
== 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.

116
_unused_topics/images-using-images-s2i-php-configuration.adoc Normal file
View File

@@ -0,0 +1,116 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-php-configuration_{context}"]
= Configuring source-to-image for PHP
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 source-to-image (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:
.PHP Environment Variables
[cols="4a,6a,6a",options="header"]
|===
|Variable Name |Description |Default
|`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:
.Additional PHP settings
[cols="3a,6a,1a",options="header"]
|===
|Variable Name |Description |Default
|`OPCACHE_MEMORY_CONSUMPTION`
|The link:http://php.net/manual/en/book.opcache.php[OPcache] shared memory
storage size.
|`16M`
|`OPCACHE_REVALIDATE_FREQ`
|How often to check script time stamps for updates, in seconds. `0` results in
link:http://php.net/manual/en/book.opcache.php[OPcache] checking for updates on
every request.
|`2`
|===
You can also override the entire directory used to load the PHP configuration by setting:
.Additional PHP settings
[cols="3a,6a",options="header"]
|===
| Variable Name | Description
|`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`:
.Composer Environment Variables
[cols="4a,6a",options="header"]
|===
|Variable Name |Description
|`COMPOSER_MIRROR`
|Set this variable to use a custom Composer repository mirror URL to download required packages during the build process.
Note: This only affects packages listed in `composer.json`.
|===
[id="images-using-images-s2i-php-apache-configuration_{context}"]
== 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.

27
_unused_topics/images-using-images-s2i-php-hot-deploying.adoc Normal file
View File

@@ -0,0 +1,27 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-hot-deploying_{context}"]
= Hot deploying for PHP
Hot deployment allows you to quickly make and deploy changes to your application without having to generate a new source-to-image (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.
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.
====
.Procedure
. To change your source code in a running pod, use the `oc rsh` command to enter the container:
+
[source,terminal]
----
$ 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.

55
_unused_topics/images-using-images-s2i-php-pulling-images.adoc Normal file
View File

@@ -0,0 +1,55 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-php-pulling-images_{context}"]
= Pulling images for PHP
//These images come in two options:
//* RHEL 8
//* CentOS 7
The RHEL 8 images are available through the Red Hat Registry.
.Procedure
* To pull the RHEL 8 image, enter the following command for the version of PHP you want:
.PHP `7.2`
[source,terminal]
----
$ podman pull registry.redhat.io/ubi8/php-72:latest
----
+
.PHP `7.3`
[source,terminal]
----
$ podman pull registry.redhat.io/rhscl/php-73-rhel7:latest
----
////
*CentOS 7 Based Images*
CentOS images for PHP 5.5 and 5.6 are available on link:quay.io[Quay.io].
.Procedure
* To pull the CentOS 7 image, enter the following command for the version of Node.js you want:
+
.PHP `5.5`
[source,terminal]
----
$ podman pull openshift/php-55-centos7
----
+
.PHP `5.6`
[source,terminal]
----
$ podman pull openshift/php-56-centos7
----
////
To use these images, you can either access them directly from registry.redhat.io, or push them into your {product-title} image registry. Additionally, you can create an image stream that points to the image, either in your container image registry or at the external location. Your {product-title} resources can then reference the
image stream.

14
_unused_topics/images-using-images-s2i-php.adoc Normal file
View File

@@ -0,0 +1,14 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-php_{context}"]
= PHP overview
{product-title} provides source-to-image (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 {product-title} or by a container runtime.
[id="images-using-images-s2i-php-accessing-logs_{context}"]
== 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.

48
_unused_topics/images-using-images-s2i-python-configuration.adoc Normal file
View File

@@ -0,0 +1,48 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-python-configuration_{context}"]
= Configuring source-to-image for Python
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 source-to-image (S2I) build configuration or in the `.s2i/environment` file to make them available to the build steps.
====
.Python Environment Variables
[cols="4a,6a",options="header"]
|===
|Variable name |Description
|`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`.
|`APP_CONFIG`
|This variable indicates the path to a valid Python file with a http://docs.gunicorn.org/en/latest/configure.html[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 http://docs.gunicorn.org/en/stable/settings.html#workers[workers]. By default, this is set to the number of available cores times 4.
|===

28
_unused_topics/images-using-images-s2i-python-hot-deploying.adoc Normal file
View File

@@ -0,0 +1,28 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-python-hot-deploying_{context}"]
= Hot deploying
Hot deployment allows you to quickly make and deploy changes to your application without having to generate a new source-to-image (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 https://gunicorn-docs.readthedocs.org/en/latest/settings.html#reload[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.
====
. Procedure
To change your source code in a running pod, use the `oc rsh` command to enter the container:
+
[source,terminal]
----
$ 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.

75
_unused_topics/images-using-images-s2i-python-pulling-images.adoc Normal file
View File

@@ -0,0 +1,75 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-python-pulling-images_{context}"]
= Pulling images for Python
//These images come in two options:
//* RHEL 8
//* CentOS 7
//*RHEL 8 Based Images*
The RHEL 8 images are available through the Red Hat Registry.
.Procedure
* To pull the RHEL 7 image, enter the following command for the version of Python you want:
+
.Python `2.7`
[source,terminal]
----
$ podman pull egistry.redhat.io/rhscl/python-27-rhel7:latest
----
+
.Python `3.6`
[source,terminal]
----
$ podman pull registry.redhat.io/ubi8/python-36:latest
----
+
.Python `3.8`
[source,terminal]
----
$ podman pull registry.redhat.io/rhscl/python-38-rhel7:latest
----
////
*CentOS 7 Based Images*
These images are available on link:quay.io[Quay.io].
.Procedure
* To pull the CentOS 7 image, enter the following command for the version of Python you want:
+
.Python `2.7`
[source,terminal]
----
$ podman pull centos/python-27-centos7
----
+
.Python `3.3`
[source,terminal]
----
$ podman pull openshift/python-33-centos7
----
+
.Python `3.4`
[source,terminal]
----
$ podman pull centos/python-34-centos7
----
+
.Python `3.5`
[source,terminal]
----
$ podman pull centos/python-35-centos7
----
////
To use these images, you can either access them directly from registry.redhat.io, or push them into your {product-title} image registry. Additionally, you can create an image stream that points to the image, either in your container image registry or at the external location. Your {product-title} resources can then reference the
image stream.

9
_unused_topics/images-using-images-s2i-python.adoc Normal file
View File

@@ -0,0 +1,9 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-python_{context}"]
= python overview
{product-title} provides source-to-image (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 {product-title} or by a container runtime.

43
_unused_topics/images-using-images-s2i-ruby-configuration.adoc Normal file
View File

@@ -0,0 +1,43 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-ruby-configuration_{context}"]
= Configuring source-to-image for Ruby
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 source-to-image (S2I) build configuration or in the `.s2i/environment` file to make them available to the build steps.
====
.Ruby Environment Variables
[cols="4a,6a",options="header"]
|===
|Variable name |Description
|`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. This environment variable is only available for Ruby 2.2+ images.
|===

50
_unused_topics/images-using-images-s2i-ruby-hot-deploying.adoc Normal file
View File

@@ -0,0 +1,50 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-ruby-hot-deploying_{context}"]
== Hot deploying for Ruby
Hot deployment allows you to quickly make and deploy changes to your application without having to generate a new source-to-image (S2I) build. The method for enabling hot deployment in this image differs based on the application type.
*Ruby on Rails applications*
.Procedure
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:
+
[source,terminal]
----
$ oc set env dc/rails-app RAILS_ENV=development
----
*Other Types of Ruby applications such as Sinatra or Padrino*
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:
* Shotgun
* Rerun
* Rack-livereload
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, you can use 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.
====
.Procedure
. To change your source code in a running pod, use the `oc rsh` command to enter the container:
+
[source,terminal]
----
$ 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.

69
_unused_topics/images-using-images-s2i-ruby-pulling-images.adoc Normal file
View File

@@ -0,0 +1,69 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-ruby-pulling-images_{context}"]
= Pulling images for Ruby
//These images come in two options:
//* RHEL 8
//* CentOS 7
//*RHEL 8 Based Images*
The RHEL 8 images are available through the Red Hat Registry.
.Procedure
* To pull the RHEL 8 image, enter the following command for the version of Ruby you want:
+
.Ruby `2.5`
[source,terminal]
----
$ podman pull registry.redhat.io/rhscl/ruby-25-rhel7:latest
----
+
.Ruby `2.6`
[source,terminal]
----
$ podman pull registry.redhat.io/rhscl/ruby-26-rhel7:latest
----
+
.Ruby `2.7`
[source,terminal]
----
$ podman pull registry.redhat.io/rhscl/ruby-27-rhel7:latest
----
////
*CentOS 7 Based Images*
These images are available on link:quay.io[Quay.io].
.Procedure
* To pull the CentOS 7 image, enter the following command for the version of Ruby you want:
+
.Ruby `2.0`
[source,terminal]
----
$ podman pull openshift/ruby-20-centos7
----
+
.Ruby `2.2`
[source,terminal]
----
$ podman pull openshift/ruby-22-centos7
----
+
.Ruby `2.3`
[source,terminal]
----
$ podman pull centos/ruby-23-centos7
----
////
To use these images, you can either access them directly from registry.redhat.io, or push them into your {product-title} image registry. Additionally, you can create an image stream that points to the image, either in your container image registry or at the external location. Your {product-title} resources can then reference the
image stream.

9
_unused_topics/images-using-images-s2i-ruby.adoc Normal file
View File

@@ -0,0 +1,9 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="images-using-images-s2i-ruby_{context}"]
= Ruby overview
{product-title} provides source-to-image (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 {product-title} or by a container runtime.

17
_unused_topics/using-images-source-to-image-java.adoc Normal file
View File

@@ -0,0 +1,17 @@
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="using-images-source-to-image"]
= Java
include::modules/common-attributes.adoc[]
:context: using-images-source-to-image
toc::[]
This topic includes information on the source-to-image (S2I) supported Java images available for {product-title} users.
//Add link to Build -> S21 following updates
include::modules/images-using-images-s2i-java.adoc[leveloffset=+1]
include::modules/images-s2i-java-pulling-images.adoc[leveloffset=+1]
include::modules/images-s2i-build-process-overview.adoc[leveloffset=+1]
include::modules/images-s2i-java-configuration.adoc[leveloffset=+1]
include::modules/images-s2i-java-build-deploy-applications.adoc[leveloffset=+1]

17
_unused_topics/using-images-source-to-image-nodejs.adoc Normal file
View File

@@ -0,0 +1,17 @@
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="using-images-source-to-image-nodejs"]
= Node.js
include::modules/common-attributes.adoc[]
:context: using-images-source-to-image-nodejs
toc::[]
This topic includes information on the source-to-image (S2I) supported Node.js images available for {product-title} users.
//Add link to Build -> S21 following updates
include::modules/images-using-images-s2i-nodejs.adoc[leveloffset=+1]
include::modules/images-s2i-nodejs-pulling-images.adoc[leveloffset=+1]
include::modules/images-s2i-build-process-overview.adoc[leveloffset=+1]
include::modules/images-using-images-s2i-nodejs-configuration.adoc[leveloffset=+1]
include::modules/images-using-images-s2i-nodejs-hot-deploying.adoc[leveloffset=+1]

17
_unused_topics/using-images-source-to-image-perl.adoc Normal file
View File

@@ -0,0 +1,17 @@
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="using-images-source-to-image-perl"]
= Perl
include::modules/common-attributes.adoc[]
:context: using-images-source-to-image-perl
toc::[]
This topic includes information on the source-to-image (S2I) supported Perl images available for {product-title} users.
//Add link to Build -> S21 following updates
include::modules/images-using-images-s2i-perl.adoc[leveloffset=+1]
include::modules/images-using-images-s2i-perl-pulling-images.adoc[leveloffset=+1]
include::modules/images-s2i-build-process-overview.adoc[leveloffset=+1]
include::modules/images-using-images-s2i-perl-configuration.adoc[leveloffset=+1]
include::modules/images-using-images-s2i-perl-hot-deploying.adoc[leveloffset=+1]

17
_unused_topics/using-images-source-to-image-php.adoc Normal file
View File

@@ -0,0 +1,17 @@
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="using-images-source-to-image-php"]
= PHP
include::modules/common-attributes.adoc[]
:context: using-images-source-to-image-php
toc::[]
This topic includes information on the source-to-image (S2I) supported PHP images available for {product-title} users.
//Add link to Build -> S21 following updates
include::modules/images-using-images-s2i-php.adoc[leveloffset=+1]
include::modules/images-using-images-s2i-php-pulling-images.adoc[leveloffset=+1]
include::modules/images-s2i-build-process-overview.adoc[leveloffset=+1]
include::modules/images-using-images-s2i-php-configuration.adoc[leveloffset=+1]
include::modules/images-using-images-s2i-php-hot-deploying.adoc[leveloffset=+1]

17
_unused_topics/using-images-source-to-image-python.adoc Normal file
View File

@@ -0,0 +1,17 @@
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="using-images-source-to-image-python"]
= Python
include::modules/common-attributes.adoc[]
:context: using-images-source-to-image-python
toc::[]
This topic includes information on the source-to-image (S2I) supported Python images available for {product-title} users.
//Add link to Build -> S21 following updates
include::modules/images-using-images-s2i-python.adoc[leveloffset=+1]
include::modules/images-using-images-s2i-python-pulling-images.adoc[leveloffset=+1]
include::modules/images-s2i-build-process-overview.adoc[leveloffset=+1]
include::modules/images-using-images-s2i-python-configuration.adoc[leveloffset=+1]
include::modules/images-using-images-s2i-python-hot-deploying.adoc[leveloffset=+1]

17
_unused_topics/using-images-source-to-image-ruby.adoc Normal file
View File

@@ -0,0 +1,17 @@
// * Unused. Can be removed by 4.9 if still unused. Request full peer review for the module if it’s used.
[id="using-images-source-to-image-ruby"]
= Ruby
include::modules/common-attributes.adoc[]
:context: using-images-source-to-image-ruby
toc::[]
This topic includes information on the source-to-image (S2I) supported Ruby images available for {product-title} users.
//Add link to Build -> S21 following updates
include::modules/images-using-images-s2i-ruby.adoc[leveloffset=+1]
include::modules/images-using-images-s2i-ruby-pulling-images.adoc[leveloffset=+1]
include::modules/images-s2i-build-process-overview.adoc[leveloffset=+1]
include::modules/images-using-images-s2i-ruby-configuration.adoc[leveloffset=+1]
include::modules/images-using-images-s2i-ruby-hot-deploying.adoc[leveloffset=+1]

18
modules/images-create-s2i-build.adoc
View File

@@ -1,6 +1,7 @@
// Module included in the following assemblies:
//
//* builds/build-strategies.adoc
// * openshift_images/create-images.adoc
[id="images-create-s2i-build_{context}"]
= Understanding the source-to-image build process
@@ -11,19 +12,4 @@ The build process consists of the following three fundamental elements, which ar
* Source-to-image (S2I) scripts
* Builder image
During the build process, S2I must place sources and scripts inside the builder image. To do so, S2I creates a `tar` file that contains the sources and scripts, then streams that file into the builder image. Before executing the `assemble` script, S2I un-tars that file and places its contents into the location specified by the `io.openshift.s2i.destination` label from the builder image, with the default location being the `/tmp` directory.
For this process to happen, your image must supply the `tar` archiving utility, the `tar` command available in `$PATH`, and the command line interpreter, the
`/bin/sh` command. This allows your image to use the fastest possible build path. If the `tar` or `/bin/sh` command is not available, the `s2i build` process is forced to automatically perform an additional container build to put both the sources and the scripts inside the image, and only then run the usual build.
////
See the following diagram for the basic S2I build workflow:
.Build Workflow
image::s2i-flow.png[S2I workflow]
Run build's responsibility is to un-tar the sources, scripts and artifacts
(if such exist) and invoke the `assemble` script. If this is the second run
(after catching `tar` or `/bin/sh` not found error) it is responsible only
for invoking `assemble` script, since both scripts and sources are already there.
////
S2I generates a Dockerfile with the builder image as the first `FROM` instruction. The Dockerfile generated by S2I is then passed to Buildah.

51
modules/images-create-s2i-scripts.adoc
View File

@@ -1,6 +1,7 @@
// Module included in the following assemblies:
//
//* builds/build-strategies.adoc
// * openshift_images/create-images.adoc
[id="images-create-s2i-scripts_{context}"]
= How to write source-to-image scripts
@@ -17,7 +18,7 @@ Both the `io.openshift.s2i.scripts-url` label specified in the image and the scr
* `$$file:///path_to_scripts_dir$$`: relative or absolute path to a directory on the host where the S2I scripts are located.
* `http(s)://path_to_scripts_dir`: URL to a directory where the S2I scripts are located.
.S2I Scripts
.S2I scripts
[cols="3a,8a",options="header"]
|===
@@ -26,7 +27,7 @@ Both the `io.openshift.s2i.scripts-url` label specified in the image and the scr
|`assemble`
|The `assemble` script builds the application artifacts from a source and places them into appropriate directories inside the image. This script is required. The workflow for this script is:
. Restore build artifacts. If you want to support incremental builds, make sure to define `save-artifacts` as well. This is optional.
. Optional: Restore build artifacts. If you want to support incremental builds, make sure to define `save-artifacts` as well.
. Place the application source in the desired location.
. Build the application artifacts.
. Install the artifacts into locations appropriate for them to run.
@@ -54,15 +55,18 @@ These dependencies are gathered into a `tar` file and streamed to the standard o
. Optional: Run `s2i build` again to verify the `save-artifacts` and `assemble` scripts save and restore artifacts functionality.
. Run the image to verify the test application is working.
[NOTE]
====
The suggested location to put the test application built by your `test/run` script is the `test/test-app` directory in your image repository.
====
|===
== Example S2I Scripts
*Example S2I scripts*
The following example S2I scripts are written in Bash. Each example assumes its `tar` contents are unpacked into the `/tmp/s2i` directory.
.`assemble` script:
[source,terminal]
[source,bash]
----
#!/bin/bash
@@ -83,9 +87,8 @@ make install
popd
----
.`run` script:
[source,terminal]
[source,bash]
----
#!/bin/bash
@@ -93,8 +96,9 @@ popd
/opt/application/run.sh
----
.`save-artifacts` script:
[source,terminal]
[source,bash]
----
#!/bin/bash
@@ -104,11 +108,10 @@ if [ -d deps ]; then
tar cf - deps
fi
popd
----
.`usage` script:
[source,terminal]
[source,bash]
----
#!/bin/bash
@@ -119,32 +122,10 @@ https://github.com/openshift/source-to-image
EOF
----
////
== Using Images with ONBUILD Instructions
The `ONBUILD` instructions can be found in many official container images. For
example:
* Ruby
* Node.js
* Python
See the link:https://docs.docker.com/engine/reference/builder/#onbuild[Docker
documentation] for more information on `ONBUILD`.
Upon startup, S2I detects whether the builder image contains `sh` and `tar` binaries
which are necessary for the S2I process to inject build inputs. If the builder image
does not contain these prerequisites, it will attempt to instead perform a container build
to layer the inputs. If the builder image includes `ONBUILD` instructions, S2I
will instead fail the build because the `ONBUILD` instructions would be executed
during the layering process, and that equates to performing a generic container
build which is less secure than an S2I build and requires explicit permissions.
Therefore you should ensure that your S2I builder image either does not contain
`ONBUILD` instructions, or ensure that it has the necessary `sh` and `tar` binary
prerequisites.
.Additional resources
* link:https://blog.openshift.com/create-s2i-builder-image/[S2I Image Creation Tutorial]
////
* See the link:https://docs.docker.com/engine/reference/builder/#onbuild[Docker
documentation] for more information on `ONBUILD`.
////

3
modules/images-create-s2i.adoc
View File

@@ -1,10 +1,11 @@
// Module included in the following assemblies:
//
// * builds/build-strategies.adoc
// * openshift_images/create-images.adoc
[id="images-create-s2i_{context}"]
= Creating images from source code with source-to-image
Source-to-image (S2I) is a framework that makes it easy to write images that take application source code as an input and produce a new image that runs the assembled application as output.
The main advantage of using S2I for building reproducible container images is the ease of use for developers. As a builder image author, you must understand two basic concepts in order for your images to provide the best possible S2I performance, the build process and S2I scripts.
The main advantage of using S2I for building reproducible container images is the ease of use for developers. As a builder image author, you must understand two basic concepts in order for your images to provide the best S2I performance, the build process and S2I scripts.

15
modules/images-s2i-build-process-overview.adoc Normal file
View File

@@ -0,0 +1,15 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/using-images-source-to-image.adoc
[id="images-s2i-build-process-overview_{context}"]
= Source-to-image build process overview
Source-to-image (S2I) produces ready-to-run images by injecting source code into a container that prepares that source code to be run. It performs the following steps:
. Runs the `FROM <builder image>` command
. Copies the source code to a defined location in the builder image
. Runs the assemble script in the builder image
. Sets the run script in the builder image as the default command
Buildah then creates the container image.

21
modules/images-test-s2i.adoc
View File

@@ -2,7 +2,7 @@
// * openshift_images/create-images.adoc
[id="images-test-s2i_{context}"]
= Testing S2I images
= About testing source-to-image images
As an Source-to-Image (S2I) builder image author, you can test your S2I image
locally and use the {product-title} build system for automated testing and
@@ -18,8 +18,9 @@ The goal of testing an S2I image is to make sure that all of these described
commands work properly, even if the base container image has changed or the tooling
used by the commands was updated.
[id="testing-requirements_{context}"]
[id="images-test-s2i-testing-requirements_{context}"]
== Understanding testing requirements
The standard location for the `test` script is `test/run`. This script is
invoked by the {product-title} S2I image builder and it could be a simple Bash
script or a static Go binary.
@@ -35,8 +36,9 @@ it you need a sample application source to verify that the source successfully
transforms into a runnable container image. The sample application should be simple,
but it should exercise the crucial steps of `assemble` and `run` scripts.
[id="generating-scripts-and-tools_{context}"]
[id="images-test-s2i-generating-scripts-and-tools_{context}"]
== Generating scripts and tools
The S2I tooling comes with powerful generation tools to speed up the process of
creating a new S2I image. The `s2i create` command produces all the necessary S2I
scripts and testing tools along with the `Makefile`:
@@ -54,8 +56,7 @@ useful, but it provides a good starting point to begin developing.
The `test/run` script produced by the `s2i create` command requires that the sample application sources are inside the `test/test-app` directory.
====
ifndef::openshift-online[]
[id="testing-locally_{context}"]
[id="images-test-s21-testing-locally_{context}"]
== Testing locally
The easiest way to run the S2I image tests locally is to use the generated
`Makefile`.
@@ -78,9 +79,9 @@ test:
IMAGE_NAME=$(IMAGE_NAME)-candidate test/run
----
[id="basic-testing-workflow_{context}"]
[id="images-test-s21-basic-testing-workflow_{context}"]
== Basic testing workflow
The `test` script assumes you have already built the image you want to
test. If required, first build the S2I image. Run one of the following commands:
@@ -149,12 +150,12 @@ Running these steps is generally enough to tell if the builder image is
working as expected.
[id="using-openshift-for-building-the-image_{context}"]
[id="images-test-s21-using-openshift-for-building-the-image_{context}"]
== Using {product-title} for building the image
Once you have a `Dockerfile` and the other artifacts that make up your new
S2I builder image, you can put them in a git repository and use {product-title}
to build and push the image. Simply define a Docker build that points
to build and push the image. Define a Docker build that points
to your repository.
If your {product-title} instance is hosted on a public IP address, the build can

60
modules/images-using-customizing-s2i-images-scripts-embedded.adoc Normal file
View File

@@ -0,0 +1,60 @@
// Module included in the following assemblies:
//
// * openshift_images/using_images/customizing-s2i-images.adoc
[id="images-using-customizing-s2i-images-scripts-embedded_{context}"]
= Invoking scripts embedded in an image
Builder images provide their own version of the source-to-image (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, replacing the scripts is acceptable, but, in other scenarios, you can run a few commands before or after the scripts while retaining the logic of the script provided in the image. To reuse the standard scripts, you can create a wrapper script that runs custom logic and delegates further work to the default scripts in the image.
.Procedure
. Look at the value of the `io.openshift.s2i.scripts-url` label to determine the location of the scripts inside of the builder image:
+
[source,terminal]
----
$ podman inspect --format='{{ index .Config.Labels "io.openshift.s2i.scripts-url" }}' wildfly/wildfly-centos7
----
+
.Example output
[source,terminal]
----
image:///usr/libexec/s2i
----
+
You inspected the `wildfly/wildfly-centos7` builder image and found out that the scripts are in the `/usr/libexec/s2i` directory.
+
. Create a script that includes an invocation of one of the standard scripts wrapped in other commands:
+
.`.s2i/bin/assemble` script
[source,bash]
----
#!/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
----
+
This example shows a custom assemble script that prints the message, runs the standard assemble script from the image, and prints another message depending on the exit code of the assemble script.
+
[IMPORTANT]
====
When wrapping the run script, you must use `exec` for invoking it to ensure signals are handled properly. The use of `exec` also precludes the ability to run additional commands after invoking the default image run script.
====
+
.`.s2i/bin/run` script
[source,bash]
----
#!/bin/bash
echo "Before running application"
exec /usr/libexec/s2i/run
----

5
openshift_images/create-images.adoc
View File

@@ -17,8 +17,9 @@ include::modules/images-create-guidelines.adoc[leveloffset=+1]
include::modules/images-create-guide-general.adoc[leveloffset=+2]
include::modules/images-create-guide-openshift.adoc[leveloffset=+2]
include::modules/images-create-metadata.adoc[leveloffset=+1]
include::modules/images-create-s2i.adoc[leveloffset=+1]
include::modules/images-create-s2i-build.adoc[leveloffset=+2]
include::modules/images-create-s2i-scripts.adoc[leveloffset=+2]
//Testing may have to move
include::modules/images-test-s2i.adoc[leveloffset=+1]

8
openshift_images/using_images/customizing-s2i-images.adoc Normal file
View File

@@ -0,0 +1,8 @@
[id="customizing-s2i-images"]
= Customizing source-to-image images
include::modules/common-attributes.adoc[]
:context: customizing-s2i-images
Source-to-image (S2I) builder images include assemble and run scripts, but the default behavior of those scripts is not suitable for all users. You can customize the behavior of an S2I builder that includes default scripts.
include::modules/images-using-customizing-s2i-images-scripts-embedded.adoc[leveloffset=+1]

32
openshift_images/using_images/using-s21-images.adoc Normal file
View File

@@ -0,0 +1,32 @@
[id="using-s21-images"]
= Source-to-image
include::modules/common-attributes.adoc[]
:context: using-s21-images
toc::[]
You can use the link:https://access.redhat.com/documentation/en-us/red_hat_software_collections/3/html-single/using_red_hat_software_collections_container_images/index[Red Hat Software Collections] images as a foundation for applications that rely on specific runtime environments such as Node.js, Perl, or Python. Special versions of some of these runtime base images are referred to as Source-to-Image (S2I) images. With S2I images, you can insert your code into a base image environment that is ready to run that code.
S2I images include:
* Java
* Node.js
* Perl
* PHP
* Python
* Ruby
S2I images are available for you to use directly from the {product-title} web UI by selecting *Catalog* -> *Developer Catalog*.
S2I images are also available though the xref:../../openshift_images/configuring-samples-operator.adoc#configuring-samples-operator[Configuring the Cluster Samples Operator].
include::modules/images-s2i-build-process-overview.adoc[leveloffset=+1]
[id="additional-resources_using-s21-images"]
== Additional resources
* For instructions on using the Cluster Samples Operator, see the xref:../../openshift_images/configuring-samples-operator.adoc#configuring-samples-operator[Configuring the Cluster Samples Operator].
* For more information on S2I builds, see the xref:../../cicd/builds/build-strategies.adoc#builds-strategy-s2i-build_build-strategies[builds strategy documentation on S2I builds].
* For troubleshooting assistance for the S2I process, see xref:../../support/troubleshooting/troubleshooting-s2i.adoc#troubleshooting-s2i[Troubleshooting the Source-to-Image process].
* For an overview of creating images with S2I, see xref:../../openshift_images/create-images.adoc#images-create-s2i_create-images[Creating images from source code with source-to-image].
* For an overview of testing S2I images, see xref:../../openshift_images/create-images.adoc#images-test-s2i_create-images[About testing S2I images].