openshift/source-to-image
1
0
Fork 0
mirror of https://github.com/openshift/source-to-image.git synced 2026-02-05 12:44:54 +01:00
Code Issues Releases Activity

Some rewrites and clarifications

Browse Source 
Conflicts:
	docs/builder_image.md
	pkg/create/templates/test.go
This commit is contained in:
Ian Miell
2015-06-05 21:28:34 +01:00
committed by ewolinetz
parent f410b40a39
commit d0ebbbf829
3 changed files with 69 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
docs/builder_image.md
View File

@@ -1,8 +1,9 @@
# sti builder image requirements
The main advantage of using sti for building reproducible docker images is ease of use
for developers. To meet that criteria you, as a builder image author, should be aware
of the two basic requirements for the best possible sti performance, these are:
The main advantage of using sti for building reproducible docker images is ease
of use for developers. To meet that criteria you, as a builder image author,
should be aware of the two basic requirements for the best possible sti
performance. These are:
* [required image contents](#required-image-contents)
* [sti scripts](#sti-scripts)
@@ -10,31 +11,30 @@ of the two basic requirements for the best possible sti performance, these are:
# Required image contents
The build process consists of three fundamental elements which are combined into
final docker image. These three are: sources, scripts and builder image. During the
The build process consists of three fundamental elements which are combined into the
final docker image. These are: source code, sti scripts, and the builder image. During the
build process sti must place sources and scripts inside that builder image. To do
so sti creates a tar file containing the two and then streams that file into the
builder image. Before executing the `assemble` script, sti untars that file and places
its contents into the destination specified with either the `--destination` flag or `io.s2i.destination`
label from the builder image (default destination is `/tmp`). For this
to happen your image must supply the tar archiving utility (command `tar` available in `$PATH`)
and a command line interpreter (command `/bin/sh`). Doing so will allow your image to
use the fastest possible build path, because in all other cases when either
`tar` or `/bin/sh` are not available, sti build will be forced to perform an additional
docker build to put both sources and scripts inside the image and only then run the
usual sti build procedure (sti will do this automatically if tar or /bin/sh are not found).
See the following diagram for how build workflow looks like:
its contents into the destination specified with the `--destination` flag or the value of
the `io.s2i.destination` label set in the builder image (the default destination is `/tmp`).
If your image does not have either `tar` or `/bin/sh` the sti build will perform an additional
docker build to place the source code and scripts into an appropriate image and then run
the normal sti build.
The following diagram illustrates the build workflow:
![sti workflow](./sti-flow.png "sti workflow")
\* Run build's responsibility is to untar the sources, scripts and artifacts (if such
exist) and invoke the `assemble` script. If this is the second run (due to catching any `tar`/`/bin/sh` related
errors) it's responsibility is only to invoke the `assemble` script, since both scripts and sources are already there.
\* Run build's responsibility is to untar the sources, scripts and (optionally) artifacts
and invoke the `assemble` script. If this is the second run after any previous runs with
`tar`/`/bin/sh` errors, it will only run the `assemble` script, since both the source and
scripts are already present.
# sti scripts
`sti` expects you, as the builder image author, to supply the following scripts:
`sti` expects you (the builder image author) to supply the following scripts:
* required:
* [assemble](#assemble)
@@ -45,9 +45,8 @@ errors) it's responsibility is only to invoke the `assemble` script, since both
* [test/run](#test/run)
All of the scripts can be written in any programming language, as long as the scripts
are executable inside the builder image. STI supports multiple options providing
`assemble`/`run`/`save-artifacts` scripts. All of these locations are checked on
each build in the following order:
are executable inside the builder image. The build searches the following locations for
these scripts in the following order:
1. A script found at the `--scripts-url` URL
1. A script found in the application source `.sti/bin` directory
@@ -56,23 +55,26 @@ each build in the following order:
Both the `io.openshift.s2i.scripts-url` label specified in the image and `--scripts-url` flag
can take one of the following forms:
* `image://path_to_scripts_dir` - absolute path inside the image to a directory where the STI scripts are located
* `file://path_to_scripts_dir` - relative or absolute path to a directory on the host where the STI scripts are located
* `http(s)://path_to_scripts_dir` - URL to a directory where the STI scripts are located
* `image://path_to_scripts_dir` - absolute path inside the image
* `file://path_to_scripts_dir` - relative or absolute path on the host machine
* `http(s)://path_to_scripts_dir` - URL to a directory
**NOTE**: In the case where the scripts are already placed inside the image (using `--scripts-url`
or `io.openshift.s2i.scripts-url` with value `image:///path/in/image`) then setting `--destination`
or `io.openshift.s2i.destination` label applies only to sources and artifacts.
<<<<<<< HEAD
**NOTE**: In the case where the scripts are already placed inside the image (ie when
using `--scripts-url` flag or the `io.openshift.s2i.scripts-url` with the format
`image:///path/in/image`), then the `--destination` flag or the `io.openshift.s2i.destination`
label applies only to sources and artifacts.
## assemble
The `assemble` script is responsible for building the application artifacts from source
and placing them into appropriate directories inside the image. The workflow for `assemble` is:
and placing them into the appropriate directories inside the image. The workflow for the
`assemble` script is:
1. Restore build artifacts (in case you want to support incremental builds, make sure
to define [save-artifacts](#save-artifacts)) as well.
1. Place the application source in the desired destination.
1. Build application artifacts.
1. Restore build artifacts (in case you want to support incremental builds (if using this,
make sure you define [save-artifacts](#save-artifacts)) as well.
1. Place the application source code in the appropriate location.
1. Build any application artifacts.
1. Install the artifacts into locations appropriate for running.
#### Example `assemble` script:
@@ -115,7 +117,7 @@ The `run` script is responsible for executing your application.
## save-artifacts
The `save-artifacts` script is responsible for gathering all the dependencies into a tar file and streaming it to the standard output. The existance of this can speed up the following build processes (eg. for Ruby - gems installed by Bundler, for Java - `.m2` contents, etc.).
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 existance of this can speed up the following build processes.
#### Example `save-artifacts` script:
@@ -133,8 +135,8 @@ popd
## usage
The `usage` script is for you, as the builder image author, to inform the user
how to properly use your image.
The `usage` script is for you (as the builder image author) to inform the user
how to use your image.
#### Example `usage` script:
@@ -150,17 +152,17 @@ EOF
## test/run
The `test/run` script is for you, as the builder image author, to create a simple
process to checks if the image is working correctly. The proposed flow of that process
should be following:
The `test/run` script is for you (as the builder image author) to create a simple
process to check whether the image is working correctly. The workflow of that process
should be the following:
1. Build the image.
1. Run the image to verify `usage` script.
1. Run `sti build` to verify `assemble` script.
1. (optional) Run `sti build` once more to verify `save-artifacts` script and
1. Run the image to verify the `usage` script.
1. Run the `sti build` to verify `assemble` script.
1. (Optional) Run the `sti build` once more to verify `save-artifacts` script and
`assemble`'s restore artifacts functionality.
1. Run the image to verify the test application is working.
**NOTE** The suggested place to put your test application which should be built by your
**NOTE** The suggested place to put your test application built by your
`test/run` script is `test/test-app` in your image repository, see
[sti create](https://github.com/openshift/source-to-image/blob/master/docs/cli.md#sti-create).

20
pkg/create/templates/scripts.go
View File

@@ -4,9 +4,9 @@ const AssembleScript = `
#!/bin/bash -e
#
# STI assemble script for the '{{.ImageName}}' image.
# The 'assemble' script build your application source.
# The 'assemble' script builds your application source ready to run.
#
# For more informations see the documentation:
# For more information refer to the documentation:
# https://github.com/openshift/source-to-image/blob/master/docs/builder_image.md
#
@@ -16,7 +16,7 @@ if [ "$1" = "-h" ]; then
exec /usr/local/sti/usage
fi
# Restore artifacts from the previous build (if exists).
# Restore artifacts from the previous build (if they exist).
#
if [ "$(ls /tmp/artifacts/ 2>/dev/null)" ]; then
echo "---> Restoring build artifacts"
@@ -27,17 +27,16 @@ echo "---> Installing application source"
cp -Rf /tmp/src/. ./
echo "---> Building application from source"
# TODO: Add build steps for your application, for example npm install or
# bundle install, etc...
# TODO: Add build steps for your application, eg npm install, bundle install
`
const RunScript = `
#!/bin/bash -e
#
# STI run script for the '{{.ImageName}}' image.
# The run script execute the server that runs your application.
# The run script executes the server that runs your application.
#
# For more informations see the documentation:
# For more information see the documentation:
# https://github.com/openshift/source-to-image/blob/master/docs/builder_image.md
#
@@ -47,7 +46,7 @@ exec <start your server here>
const UsageScript = `
#!/bin/bash -e
cat <<EOF
This is a STI {{.ImageName}} image:
This is an STI {{.ImageName}} image:
To use it, install STI: https://github.com/openshift/source-to-image
Sample invocation:
@@ -64,10 +63,9 @@ const SaveArtifactsScript = `
#
# STI save-artifacts script for the '{{.ImageName}}' image.
# The save-artifacts script streams a tar archive to standard output.
# The archive contains files and folder you want to move from a previous build
# to a new build.
# The archive contains the files and folders you want to re-use in the next build.
#
# For more informations see the documentation:
# For more information see the documentation:
# https://github.com/openshift/source-to-image/blob/master/docs/builder_image.md
#
# tar cf - <list of files and folders>

22
pkg/create/templates/test.go
View File

@@ -3,10 +3,10 @@ package templates
const TestRunScript = `
#!/bin/bash
#
# The 'run' performs a simple test that verifies that STI image.
# The main focus here is to excersise the STI scripts.
# The 'run' performs a simple test that verifies the STI image.
# The main focus here is to exercise the STI scripts.
#
# For more informations see the documentation:
# For more information see the documentation:
# https://github.com/openshift/source-to-image/blob/master/docs/builder_image.md
#
# IMAGE_NAME specifies a name of the candidate image used for testing.
@@ -19,7 +19,7 @@ image_dir=$(readlink -zf ${test_dir}/..)
scripts_url="file://${image_dir}/.sti/bin"
cid_file=$(mktemp -u --suffix=.cid)
# Since we built the candidate image locally, we don't want STI attempt to pull
# Since we built the candidate image locally, we don't want STI to attempt to pull
# it from Docker hub
sti_args="--force-pull=false -s ${scripts_url}"
@@ -47,6 +47,16 @@ prepare() {
echo "ERROR: The image ${IMAGE_NAME} must exist before this script is executed."
exit 1
fi
<<<<<<< HEAD
=======
# TODO: The STI build requires that the application is a valid git repository. We
# should remove this restriction in the future when a file:// is used.
pushd ${test_dir}/test-app >/dev/null
git init
git config user.email "build@localhost" && git config user.name "builder"
git add -A && git commit -m "Sample commit"
popd >/dev/null
>>>>>>> e86b0ad... Some rewrites and clarifications
run_sti_build
}
@@ -81,7 +91,7 @@ wait_for_cid() {
local result=1
while [ $attempt -le $max_attempts ]; do
[ -f $cid_file ] && break
echo "Waiting for container start..."
echo "Waiting for container to start..."
attempt=$(( $attempt + 1 ))
sleep $sleep_time
done
@@ -127,7 +137,7 @@ check_result $?
# Verify that the HTTP connection can be established to test application container
run_test_application &
# Wait for the container to write it's CID file
# Wait for the container to write its CID file
wait_for_cid
test_connection