github.com/openshift/source-to-image@v1.4.1-0.20240516041539-bf52fc02204e/docs/builder_image.md (about)

     1  # s2i builder image requirements
     2  
     3  The main advantage of using s2i for building reproducible docker images is ease
     4  of use for developers. To meet that criteria you, as a builder image author,
     5  should be aware of the two basic requirements for the best possible s2i
     6  performance. These are:
     7  
     8  * [required image contents](#required-image-contents)
     9  * [s2i scripts](#s2i-scripts)
    10  
    11  
    12  # Required image contents
    13  
    14  The build process consists of three fundamental elements which are combined into the
    15  final docker image. These are: source code, s2i scripts, and the builder image. During the
    16  build process s2i must place sources and scripts inside that builder image. To do
    17  so s2i creates a tar file containing the two and then streams that file into the
    18  builder image. Before executing the `assemble` script, s2i untars that file and places
    19  its contents into the destination specified with either the `--destination` flag or the value of
    20  the `io.openshift.s2i.destination` label set in the builder image (the default destination is `/tmp`).
    21  If your image does not have either `tar` or `/bin/sh` the s2i build will perform an additional
    22  docker build to place the source code and scripts into an appropriate image and then run
    23  the normal s2i build.
    24  
    25  The following diagram illustrates the build workflow:
    26  
    27  ![s2i workflow](./sti-flow.png "s2i workflow")
    28  
    29  \* Run build's responsibility is to untar the sources, scripts and (optionally) artifacts
    30  and invoke the `assemble` script. If this is the second run after any previous runs with
    31  `tar`/`/bin/sh` errors, it will only run the `assemble` script, since both the source and
    32  scripts are already present.
    33  
    34  
    35  # s2i scripts
    36  
    37  `s2i` expects you (the builder image author) to supply the following scripts:
    38  
    39  * required:
    40      * [assemble](#assemble)
    41      * [run](#run)
    42  * optional:
    43      * [save-artifacts](#save-artifacts)
    44      * [usage](#usage)
    45      * [test/run](#testrun)
    46  
    47  All of the scripts can be written in any programming language, as long as the scripts
    48  are executable inside the builder image. The build searches the following locations for
    49  these scripts in the following order:
    50  
    51  1. A script found at the `--scripts-url` URL
    52  1. A script found in the application source `.s2i/bin` directory
    53  1. A script found at the default image URL (`io.openshift.s2i.scripts-url` label)
    54  
    55  Both the `io.openshift.s2i.scripts-url` label specified in the image and `--scripts-url` flag
    56  can be supplied in any of the following forms to indicate where the scripts are located:
    57  
    58  * `image://path_to_scripts_dir` - absolute path inside the image
    59  * `file://path_to_scripts_dir` - relative or absolute path on the host machine
    60  * `http(s)://path_to_scripts_dir` - URL to a directory
    61  
    62  **NOTE**: In the case where the scripts are already placed inside the image (ie when
    63  using `--scripts-url` flag or the `io.openshift.s2i.scripts-url` with the format
    64  `image:///path/in/image`), then the `--destination` flag or the `io.openshift.s2i.destination`
    65  label applies only to sources and artifacts.
    66  
    67  ## assemble
    68  
    69  The `assemble` script is responsible for building the application artifacts from source
    70  and placing them into the appropriate directories inside the image. The workflow for the
    71  `assemble` script is:
    72  
    73  1. Restore build artifacts (in case you want to support incremental builds (if using this,
    74     make sure you define [save-artifacts](#save-artifacts)) as well.
    75  1. Place the application source code in the appropriate location.
    76  1. Build any application artifacts.
    77  1. Install the artifacts into locations appropriate for running.
    78  
    79  In the case you need to assemble the Image using a different user than the runtime user defined 
    80  in ``USER`` directive of Dockerfile, you can achive this by the following ways:
    81  
    82  1. use the `--assemble-user` in cmd line
    83  1. use the label `io.openshift.s2i.assemble-user`
    84  
    85  
    86  #### Example `assemble` script:
    87  
    88  **NOTE**: All the examples are written in [Bash](http://www.gnu.org/software/bash/)
    89  and it is assumed that the tar contents unpack into the `/tmp` directory.
    90  
    91  ```
    92  #!/bin/bash
    93  
    94  # restore build artifacts
    95  if [ "$(ls /tmp/artifacts/ 2>/dev/null)" ]; then
    96      mv /tmp/artifacts/* $HOME/.
    97  fi
    98  
    99  # move the application source
   100  mv /tmp/s2i/src $HOME/src
   101  
   102  # build application artifacts
   103  pushd ${HOME}
   104  make all
   105  
   106  # install the artifacts
   107  make install
   108  popd
   109  ```
   110  
   111  ## run
   112  
   113  The `run` script is responsible for executing your application.
   114  
   115  #### Example `run` script:
   116  
   117  ```
   118  #!/bin/bash
   119  
   120  # run the application
   121  /opt/application/run.sh
   122  ```
   123  
   124  ## save-artifacts
   125  
   126  The `save-artifacts` script is responsible for gathering all the dependencies into a tar file and streaming it to the standard output (eg. for Ruby - gems installed by Bundler, for Java - `.m2` contents, etc.).  The existence of this can speed up the following build processes.  Note: it is critical that the `save-artifacts` script output only include the tar stream output and nothing else.  This is handled by redirecting output to /dev/null in the sample script below.
   127  
   128  #### Example `save-artifacts` script:
   129  
   130  ```
   131  #!/bin/bash
   132  
   133  # Besides the tar command, all other output to standard out must 
   134  # be surpressed.  Otherwise, the tar stream will be corrupted.
   135  pushd ${HOME} >/dev/null
   136  if [ -d deps ]; then
   137      # all deps contents to tar stream
   138      tar cf - deps
   139  fi
   140  popd >/dev/null
   141  
   142  ```
   143  
   144  ## usage
   145  
   146  The `usage` script is for you (as the builder image author) to inform the user
   147  how to use your image.
   148  
   149  #### Example `usage` script:
   150  
   151  ```
   152  #!/bin/bash
   153  
   154  # inform the user how to use the image
   155  cat <<EOF
   156  This is a S2I sample builder image, to use it, install
   157  https://github.com/openshift/source-to-image
   158  EOF
   159  ```
   160  
   161  ## test/run
   162  
   163  The `test/run` script is for you (as the builder image author) to create a simple
   164  process to check whether the image is working correctly. The workflow of that process
   165  should be the following:
   166  
   167  1. Build the image.
   168  1. Run the image to verify the `usage` script.
   169  1. Run the `s2i build` to verify `assemble` script.
   170  1. (Optional) Run the `s2i build` once more to verify `save-artifacts` script and
   171     `assemble`'s restore artifacts functionality.
   172  1. Run the image to verify the test application is working.
   173  
   174  **NOTE** The suggested place to put your test application built by your
   175  `test/run` script is `test/test-app` in your image repository, see
   176  [s2i create](https://github.com/openshift/source-to-image/blob/master/docs/cli.md#s2i-create).
   177  
   178  # Additional steps
   179  ## OpenShift support
   180  If you are intending to use this image with [OpenShift](https://github.com/openshift/origin), review and follow the OpenShift [image creation guidelines](https://docs.okd.io/latest/openshift_images/create-images.html).