a new Docker image for the application. The result is then ready to use with `docker run`.
The basic flow is:
1. Start with a ruby builder image which contains ruby, bundler, rake, apache, gcc, etc, all of which are needed to install and run ruby code.
1. Launch a container using the builder image and injects the provided source code into a working directory within the container.
1. The container then transforms that source code into the appropriate runnable setup - in this case, by installing dependencies and moving the source code into a directory where Apache has been preconfigured to look for a Ruby application.
1. Commit the new container and set the image entrypoint to be a script (provided by the builder image) that will start Apache to host the Ruby application.
There are two primary patterns when building images:
* Produce an application image which includes all development/build tooling used to assemble the application as well as the runtime environment needed to execute the application.
* Produce an application image which only contains the final runnable application and the runtime environment.
The first pattern is appropriate for dynamic languages which typically need the same tools for building as execution. The second can be used for compiled languages such as Java when it is undesirable to include build tools such as `javac` and `maven` in the runtime image. Including build tools in the application image results in a self-contained image which can fully reproduce the application using the exact tools that originally created it. More sophisticated flows make it possible to separate those two images into one image containing build inputs, build tools, and built artifacts and another image containing the built artifacts (provided as "source") and the runtime environment.
1. Allow users to build new application images in a controlled, secure, restricted environment
## Codified Image Construction Patterns
### Image flexibility
S2I scripts can be written to inject application code into almost any existing Docker image, taking advantage of the existing image ecosystem.
### Speed
With S2I, the assemble process can perform a large number of complex operations without creating a new layer at each step, resulting in a fast process. In addition, S2I scripts can be written to re-use artifacts stored in a previous version of the application image, rather than having to download or build them each time the build is run.
### Patchability
S2I allows you to rebuild the application in a consistent way if an underlying image needs a patch due to a security issue.
### Operational security
Building an arbitrary Dockerfile exposes the host system to root privilege escalation. This can be exploited by a malicious user because the entire Docker build process is run as a user with Docker privileges. S2I restricts the operations that can be performed as a root user and can run user
supplied build scripts as a non-root user. Furthermore, operations teams can supply whitelisted builder images which will not perform
arbitrary actions such as installing random packages or downloading content from untrusted sources.
### Ecosystem
S2I encourages a shared ecosystem of images where you can leverage best practices for your applications and build processes.
See a practical tutorial on how to create a builder image [here](examples/README.md) and read [this](https://github.com/openshift/source-to-image/blob/master/docs/builder_image.md) for a detailed description of the requirements and scripts along with examples of builder images.
Filtering the contents of the source tree is possible if the user supplies a
`.s2iignore` file in the root directory of the source repository, where `.s2iignore` contains regular
expressions that capture the set of files and directories you want filtered from the image s2i produces.
Specifically:
1. Specify one rule per line, with each line terminating in `\n`.
1. Filepaths are appended to the absolute path of the root of the source tree (either the local directory supplied, or the target destination of the clone of the remote source repository s2i creates).
1. Wildcards and globbing (file name expansion) leverage Go's `filepath.Match` and `filepath.Glob` functions.
1. Search is not recursive. Subdirectory paths must be specified (though wildcards and regular expressions can be used in the subdirectory specifications).
1. If the first character is the `#` character, the line is treated as a comment.
1. If the first character is the `!`, the rule is an exception rule, and can undo candidates selected for filtering by prior rules (but only prior rules).
Here are some examples to help illustrate:
With specifying subdirectories, the `*/temp*` rule prevents the filtering of any files starting with `temp` that are in any subdirectory that is immediately (or one level) below the root directory.
And the `*/*/temp*` rule prevents the filtering of any files starting with `temp` that are in any subdirectory that is two levels below the root directory.
Next, to illustrate exception rules, first consider the following example snippet of a `.s2iignore` file:
`README.md`, if filtered by any prior rules, but then put back in by `!README.md`, would be filtered, and not part of the resulting image s2i produces. Since `*.md` follows `!README.md`, `*.md` takes precedence.
Running into some issues and need some advice debugging? Peruse [here](https://github.com/openshift/source-to-image/blob/master/docs/debugging-s2i.md) for some tips.
