<commit_before>= STI Requirements
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:

toc::[]

== Overview
The main advantage of using STI for building reproducible Docker images is the ease of use for developers. As a builder image author, you must be aware of the two basic requirements for the best possible STI performance: the required image contents and STI scripts.

== Required Image Contents
The build process consists of three fundamental elements which are combined into a final Docker image:

- sources
- STI scripts
- builder image

During the build process, STI must place sources and scripts inside the builder image. To do so, STI creates a tar file that contains the sources and scripts, then streams that file into the builder image. Before executing the `sti assemble` script, STI untars that file and places its contents into the location specified with the `--location` flag or the `STI_LOCATION` environment variable from the builder image, with the default location being the [filename]#/tmp# directory.

For this tar process to happen, your image must supply the tar archiving utility (the `tar` command available in [filename]#$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 `sti build` script is forced to automatically perform an additional Docker build to put both the sources and the scripts inside the image, and only then run the usual `sti build` procedure.

See the following diagram for the basic STI build workflow:

.Build workflow
image::sti-flow.png[STI workflow]

////
* Run build's responsibility is to untar the sources, scripts and artifacts (if such exist) and invoke `assemble` script. If this is second run (after catching `tar`/`/bin/sh` error) it's responsible only for invoking `assemble` script, since both scripts and sources are already there.
////

== STI Scripts
You can supply the following scripts to STI:

* link:#assemble[`assemble`] (required)
* link:#run[`run`] (required)
* link:#save-artifacts[`save-artifacts`] (optional)
* link:#usage[`usage`] (optional)

You can write the scripts in any programming language as long as the scripts are executable inside the builder image.

NOTE: The examples in the following sections are written in Bash and it is assumed all tar contents are unpacked into the [filename]#/tmp/sti# directory.

[[assemble]]
*`assemble`*

The `assemble` script builds the application artifacts from source and places them into appropriate directories inside the image. The workflow for the `assemble` script is:

. Restore build artifacts. If you want to support incremental builds, make sure to define link:#save-artifacts[`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.

.Example `assemble` script:
====

----
#!/bin/bash<commit_msg>Note about OnBuild STI strategy<commit_after>= STI Requirements
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:

toc::[]

== Overview
The main advantage of using STI for building reproducible Docker images is the ease of use for developers. As a builder image author, you must be aware of the two basic requirements for the best possible STI performance: the required image contents and STI scripts.

== Required Image Contents
The build process consists of three fundamental elements which are combined into a final Docker image:

- sources
- STI scripts
- builder image

During the build process, STI must place sources and scripts inside the builder image. To do so, STI creates a tar file that contains the sources and scripts, then streams that file into the builder image. Before executing the `sti assemble` script, STI untars that file and places its contents into the location specified with the `--location` flag or the `STI_LOCATION` environment variable from the builder image, with the default location being the [filename]#/tmp# directory.

For this tar process to happen, your image must supply the tar archiving utility (the `tar` command available in [filename]#$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 `sti build` script is forced to automatically perform an additional Docker build to put both the sources and the scripts inside the image, and only then run the usual `sti build` procedure.

See the following diagram for the basic STI build workflow:

.Build workflow
image::sti-flow.png[STI workflow]

////
* Run build's responsibility is to untar the sources, scripts and artifacts (if such exist) and invoke `assemble` script. If this is second run (after catching `tar`/`/bin/sh` error) it's responsible only for invoking `assemble` script, since both scripts and sources are already there.
////

== Using ONBUILD Docker images with STI

The ONBUILD instructions can be found in many "official" Docker images. For example:

https://registry.hub.docker.com/u/library/ruby
https://registry.hub.docker.com/u/library/node
https://registry.hub.docker.com/u/library/python

For more details about how ONBUILD works, visit
https://docs.docker.com/reference/builder/#onbuild.

The STI has a different strategy when the Docker image with ONBUILD instructions
is used as a builder image for the application source code.

During the STI build, all ONBUILD instructions are executed in order they were
defined in the builder image Dockerfile. The STI scripts are not required for
this strategy, but they can be used as a supplementary scripts to existing
ONBUILD instructions.

Many official Docker images that use ONBUILD does not declare the image CMD or
ENTRYPOINT and for that, STI needs to know how to run your application.
There are two ways how to define the ENTRYPOINT. First way is to include the 'run'
script in your application root folder. STI will then recognize it and set it as
the application image ENTRYPOINT. Second way is to use the STI scripts. If you
provide the URL from where the STI can fetch the scripts, the STI 'run' script
will be then set as an image ENTRYPOINT. If the STI scripts location also
include the 'assemble' script, this script is execute as last instruction of the
Docker build.

== STI Scripts

You can supply the following scripts to STI:

* link:#assemble[`assemble`] (required)
* link:#run[`run`] (required)
* link:#save-artifacts[`save-artifacts`] (optional)
* link:#usage[`usage`] (optional)

You can write the scripts in any programming language as long as the scripts are executable inside the builder image.

NOTE: The examples in the following sections are written in Bash and it is assumed all tar contents are unpacked into the [filename]#/tmp/sti# directory.

[[assemble]]
*`assemble`*

The `assemble` script builds the application artifacts from source and places them into appropriate directories inside the image. The workflow for the `assemble` script is:

. Restore build artifacts. If you want to support incremental builds, make sure to define link:#save-artifacts[`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.

.Example `assemble` script:
====

----
#!/bin/bash
{'fraction_non_alphanumeric': 0.0689609177004135, 'fraction_numerical': 0.0, 'mean_word_length': 4.693242217160212, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2824336', 'n_tokens_mistral': 1974, 'n_tokens_neox': 1866, 'n_words': 1067}