Minimal s2i builder image tutorial

README.md

@@ -14,7 +14,6 @@ Interested in learning more? Read on!
 
 Want to just get started now? Check out the [instructions](#getting-started).
 
-
 # Philosophy
 
 1. Simplify the process of application source + builder image -> usable image for most use cases (the
@@ -29,6 +28,8 @@ Want to just get started now? Check out the [instructions](#getting-started).
 
 # Anatomy of a builder image
 
+See a practical tutorial on how to create a builder image [here](examples/TUTORIAL.md)
+
 Creating builder images is easy. `s2i` looks for you to supply the following scripts to use with an
 image:
 

examples/README.md

@@ -0,0 +1,50 @@
+Creating a basic S2I builder image  
+---
+
+### Getting started  
+
+Directory skeleton:  
+
+* `Dockerfile` – standard Dockerfile where we’ll define the base builder image.  
+* `assemble` - responsible for building the application.  
+* `run` - responsible for running the application.  
+* `save-artifacts` - optional script for incremental builds that save built artifacts.  
+* `usage` - optional script responsible for printing the usage of the builder.  
+
+The first step is to create a `Dockerfile` that installs all the necessary tools and libraries that are needed to build and run our application.  
+You can find an example of the Dockerfile [`here`](nginx-app/Dockerfile).   
+
+The next step is to create an `assemble` script that will, for example, build python modules, bundle install our required components or setup application specific configuration based on the logic we define in it. We can specify a way to restore any saved artifacts from the previous image. In [`this`](nginx-app/assemble) example it will only copy our index.html over the default one.  
+
+Now we can create our `run` script that will start the application. You can see an example [`here`](nginx-app/run).
+
+Optionally we can also specify a `save-artifacts` script, which allows a new build to reuses content from a previous version of the application image.
+An example can be found [`here`](nginx-app/save-artifacts).  
+
+We can provide some help to the user on how to use it as a base for an application image via the `usage` script. An example can be found [`here`](nginx-app/usage).
+
+The next step is to create the builder image. In the nginx-app directory issue `docker build -t nginx-centos7 .`  
+This will create a builder image from the current Dockerfile.
+
+Once the builder image is done, the user can issue `s2i usage nginx-centos7` which will print out the help info that was defined in our `usage` script.
+
+The next step is to create `the application image`. We will create this with the content from the source directory `test` from this repo. In this source directory we have only one file for this example, `index.html`.
+
+```
+s2i build test/ nginx-centos7 nginx-app
+---> Building and installing application from source...
+```
+All the logic defined previously in the `assemble` script will now be executed thus compiling your assets or setting up application specific configuration.
+
+Running the application image is as simple as invoking the docker run command:
+`docker run -d -p 8080:8080 nginx-app`
+
+Now you should be able to access a static web page served by our newly created application image on [http://localhost:8080](http://localhost:8080).
+
+If we want to rebuild the application with the saved artifacts, then we can do:
+```
+s2i build --incremental=true test/ nginx-centos7 nginx-app
+---> Restoring build artifacts...
+---> Building and installing application from source...
+```
+This will run the `save-artifacts` script that has the code which will save your artifacts from the previously built application image, and then inject those artifacts into the new image according to the logic you specified in the `assemble` script. 

examples/nginx-app/Dockerfile

@@ -0,0 +1,36 @@
+# nginx-centos7
+# Here you can use whatever image base is relevant for your application.
+FROM centos:centos7
+
+# Here you can specify the maintainer for the image that you're building
+MAINTAINER Victor Palade <ipalade@redhat.com>
+
+# Export the environment variable that provides information about the application.
+# Replace this with the according version for your application.
+ENV NGINX_VERSION=1.6.3
+
+# Set the labels that are used for Openshift to describe the builder image.
+LABEL io.k8s.description="Nginx Webserver" \
+    io.k8s.display-name="Nginx 1.6.3" \
+    io.openshift.expose-services="8080:http" \
+    io.openshift.tags="builder,webserver,html,nginx" \
+    # this label tells s2i where to find its mandatory scripts
+    # (run, assemble, save-artifacts)
+    io.openshift.s2i.scripts-url="image:///usr/libexec/s2i"
+
+# Install our Nginx package and clean the yum cache so that we don't have any
+# cached files waste space.
+RUN yum install -y epel-release  && \
+    yum install -y --setopt=tsflags=nodocs nginx && \
+    yum clean all
+
+# We will change the default port for nginx (It's required if you plan on
+# running images as non-root user).
+RUN sed -i 's/80/8080/' /etc/nginx/nginx.conf
+
+# Copy the S2I scripts to /usr/libexec/s2i since we set the label that way
+COPY  ["run", "assemble", "save-artifacts", "usage", "/usr/libexec/s2i/"]
+
+# Modify the usage script in your application dir to inform the user how to run
+# this image.
+CMD ["/usr/libexec/s2i/usage"]

examples/nginx-app/assemble

@@ -0,0 +1,28 @@
+#!/bin/bash -e
+#
+# S2I assemble script for the 'nginx-centos7' image.
+# The 'assemble' script builds your application source so that it is ready to run.
+#
+# For more information refer to the documentation:
+#	https://github.com/openshift/source-to-image/blob/master/docs/builder_image.md
+#
+
+if [[ "$1" == "-h" ]]; then
+	# If the 'nginx-centos7' assemble script is executed with '-h' flag,
+	# print the usage.
+	exec /usr/libexec/s2i/usage
+fi
+
+# Restore artifacts from the previous build (if they exist).
+# We set them here just for show, but you will need to set this up with your logic
+# according to the application directory that you chose.
+if [ "$(ls /tmp/artifacts/ 2>/dev/null)" ]; then
+  echo "---> Restoring build artifacts..."
+  mv /tmp/artifacts/* /usr/share/nginx/html/
+fi
+# Override our default nginx index.html file.
+# This is what we consider in this example `installing the application`
+# here you can go ahead an replace this with the actual building of python modules,
+# bundle install, and anything else you need.
+echo "---> Building and installing application from source..."
+cp -Rf /tmp/src/test/index.html /usr/share/nginx/html/index.html

examples/nginx-app/run

@@ -0,0 +1,11 @@
+#!/bin/bash -e
+# The run script executes the server that runs your application.
+#
+# For more information see the documentation:
+#	https://github.com/openshift/source-to-image/blob/master/docs/builder_image.md
+#
+
+# We will turn off daemonizing for the nginx process so that the container
+# doesn't exit after the process runs.
+# We will also specify the default port on which it should listen.
+exec /usr/sbin/nginx -g "daemon off;"

examples/nginx-app/save-artifacts

@@ -0,0 +1,16 @@
+#!/bin/sh -e
+#
+# S2I save-artifacts script for the 'nginx-centos7' image.
+# The save-artifacts script streams a tar archive to standard output.
+# The archive contains the files and folders you want to re-use in the next build.
+#
+# For more information see the documentation:
+#	https://github.com/openshift/source-to-image/blob/master/docs/builder_image.md
+#
+# Replace this with any logic that you need in order to save all of your built artifacts from
+# your application so they can be reused in a future build to save time.
+touch /tmp/artifact
+cd /tmp
+# the final step of the assemble script is to stream a tar of the artifacts to be saved, to stdout.
+# This tar stream will be received by s2i and used as an input to the build
+tar cf - artifact

examples/nginx-app/test/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+  <meta charset="utf-8">
+  <title>openshift/source-to-image tutorial</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta name="description" content="source-to-image tutorial example page">
+</head>
+  <body>
+    <h1>Hello World</h1>
+  </body>
+</html>

examples/nginx-app/usage

@@ -0,0 +1,13 @@
+#!/bin/bash -e
+cat <<EOF
+This is the nginx-centos7 S2I image:
+To use it, install S2I: https://github.com/openshift/source-to-image
+
+Sample invocation:
+
+s2i build test/ nginx-centos7 nginx-app
+
+You can then run the resulting image via:
+docker run -d -p 8080:8080 nginx-app
+and see the test via http://localhost:8080
+EOF