openshift-docs/modules/images-create-s2i-scripts.adoc

// Module included in the following assemblies:
//* assembly/openshift_images
// include::<path>/images-create-s2i-scripts.adoc[leveloffset=+1]
//* assembly/builds/build-strategies.adoc

[id="images-create-s2i-scripts_{context}"]
= Writing s2i scripts

You can write S2I scripts in any programming language, as long as the scripts are
executable inside the builder image. S2I supports multiple options providing
`assemble`/`run`/`save-artifacts` scripts. All of these locations are checked on
each build in the following order:

. A script specified in the BuildConfig
. A script found in the application source `.s2i/bin` directory
. A script found at the default image URL (`io.openshift.s2i.scripts-url` label)

Both the `io.openshift.s2i.scripts-url` label specified in the image and the
script specified in a `BuildConfig` can take one of the following forms:

* `image:///path_to_scripts_dir` - absolute path inside the image to a directory where the S2I scripts are located
* `$$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
[cols="3a,8a",options="header"]
|===

|Script |Description

|*_assemble_*
(required)
|The *_assemble_* script builds the application artifacts from a source
and places them into appropriate directories inside the image. The workflow for
this script is:

. Restore build artifacts. If you want to support incremental builds, make sure to define *_save-artifacts_* as well (optional).
. Place the application source in the desired location.
. Build the application artifacts.
. Install the artifacts into locations appropriate for them to run.

|*_run_*
(required)
|The *_run_* script executes your application.

|*_save-artifacts_*
(optional)
|The *_save-artifacts_* script gathers all dependencies that can speed up the
build processes that follow. For example:

- For Ruby, *gems* installed by Bundler.
- For Java, *.m2* contents.

These dependencies are gathered into a tar file and streamed to the standard
output.

|*_usage_*
(optional)
|The *_usage_* script allows you to inform the user how to properly use your
image.

|*_test/run_*
(optional)
|The *_test/run_* script allows you to create a simple process to check if the
image is working correctly. The proposed flow of that process is:

. Build the image.
. Run the image to verify the *_usage_* script.
. Run `s2i build` to verify the *_assemble_* script.
. Run `s2i build` again to verify the *_save-artifacts_* and *_assemble_* scripts save and restore artifacts functionality. (optional)
. 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.
See the https://github.com/openshift/source-to-image/blob/master/docs/cli.md#sti-create[S2I documentation]
for more information.
|===

== 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:
====

----
#!/bin/bash

# restore build artifacts
if [ "$(ls /tmp/s2i/artifacts/ 2>/dev/null)" ]; then
    mv /tmp/s2i/artifacts/* $HOME/.
fi

# move the application source
mv /tmp/s2i/src $HOME/src

# build application artifacts
pushd ${HOME}
make all

# install the artifacts
make install
popd
----
====

.`run` script:
====

----
#!/bin/bash

# run the application
/opt/application/run.sh
----
====

.*_save-artifacts_* script:
====

----
#!/bin/bash

pushd ${HOME}
if [ -d deps ]; then
    # all deps contents to tar stream
    tar cf - deps
fi
popd

----
====

.`usage` script:
====

----
#!/bin/bash

# inform the user how to use the image
cat <<EOF
This is a S2I sample builder image, to use it, install
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]
////