Overhaul of Source-to-Image

Updating README(s), templates, and examples

Author: coreydaley

README.md

@@ -233,12 +233,12 @@ You can start using `s2i` right away (see [releases](https://github.com/openshif
 with the following test sources and publicly available images:
 
 ```
-$ s2i build https://github.com/pmorie/simple-ruby openshift/ruby-20-centos7 test-ruby-app
+$ s2i build https://github.com/openshift/ruby-hello-world openshift/ruby-23-centos7 test-ruby-app
 $ docker run --rm -i -p :8080 -t test-ruby-app
 ```
 
 ```
-$ s2i build https://github.com/bparees/openshift-jee-sample openshift/wildfly-100-centos7 test-jee-app
+$ s2i build --ref=7.1.x --context-dir=helloworld https://github.com/jboss-developer/jboss-eap-quickstarts openshift/wildfly-101-centos7 test-jee-app
 $ docker run --rm -i -p :8080 -t test-jee-app
 ```
 

cmd/s2i/main.go

@@ -269,6 +269,7 @@ func newCmdCreate() *cobra.Command {
 			b := create.New(args[0], args[1])
 			b.AddSTIScripts()
 			b.AddDockerfile()
+			b.AddReadme()
 			b.AddTests()
 		},
 	}

docs/cli.md

@@ -146,11 +146,11 @@ Example: data posted will be in the form:
 
 #### Example Usage
 
-Build a Ruby application from a Git source, using the official `ruby-20-centos7` builder
+Build a Ruby application from a Git source, using the official `ruby-23-centos7` builder
 image, the resulting image will be named `ruby-app`:
 
 ```
-$ s2i build https://github.com/mfojtik/sinatra-app-example openshift/ruby-20-centos7 ruby-app
+$ s2i build https://github.com/openshift/ruby-hello-world openshift/ruby-23-centos7 ruby-app
 ```
 
 Build a Node.js application from a local directory, using a local image, the resulting
@@ -167,19 +167,19 @@ Use this method only for development or local testing.
 
 **NOTE**: All your changes have to be committed by `git` in order to build them with S2I.
 
-Build a Java application from a Git source, using the official `openshift/wildfly-100-centos7`
+Build a Java application from a Git source, using the official `openshift/wildfly-101-centos7`
 builder image but overriding the scripts URL from local directory.  The resulting
 image will be named `java-app`:
 
 ```
-$ s2i build --scripts-url=file://s2iscripts https://github.com/bparees/openshift-jee-sample openshift/wildfly-100-centos7 java-app
+$ s2i build --scripts-url=file://s2iscripts --ref=7.1.x --context-dir=kitchensink https://github.com/jboss-developer/jboss-eap-quickstarts openshift/wildfly-101-centos7 java-app
 ```
 
 Build a Ruby application from a Git source, specifying `ref`, and using the official
-`ruby-20-centos7` builder image.  The resulting image will be named `ruby-app`:
+`ruby-23-centos7` builder image.  The resulting image will be named `ruby-app`:
 
 ```
-$ s2i build --ref=my-branch https://github.com/mfojtik/sinatra-app-example openshift/ruby-20-centos7 ruby-app
+$ s2i build --ref=my-branch https://github.com/openshift/ruby-hello-world openshift/ruby-23-centos7 ruby-app
 ```
 
 ***NOTE:*** If the ref is invalid or not present in the source repository then the build will fail.
@@ -188,7 +188,7 @@ Build a Ruby application from a Git source, overriding the scripts URL from a lo
 and specifying the scripts and sources be placed in `/opt` directory:
 
 ```
-$ s2i build --scripts-url=file://s2iscripts --destination=/opt https://github.com/mfojtik/sinatra-app-example openshift/ruby-20-centos7 ruby-app
+$ s2i build --scripts-url=file://s2iscripts --destination=/opt https://github.com/openshift/ruby-hello-world openshift/ruby-23-centos7 ruby-app
 ```
 
 # s2i rebuild
@@ -232,9 +232,9 @@ $ s2i usage <builder image> [flags]
 
 #### Example Usage
 
-Print the official `ruby-20-centos7` builder image usage:
+Print the official `ruby-23-centos7` builder image usage:
 ```
-$ s2i usage openshift/ruby-20-centos7
+$ s2i usage openshift/ruby-23-centos7
 ```
 
 

examples/README.md

@@ -1,12 +1,13 @@
+
 # nginx-centos7
-# Here you can use whatever image base is relevant for your application.
+# Here you can use whatever base image 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>
+MAINTAINER Your Name <your.name@example.com>
 
-# Export the environment variable that provides information about the application.
-# Replace this with the according version for your application.
+# Export an environment variable that provides information about the application version.
+# Replace this with the version for your application.
 ENV NGINX_VERSION=1.6.3
 
 # Set the labels that are used for OpenShift to describe the builder image.
@@ -18,18 +19,30 @@ LABEL io.k8s.description="Nginx Webserver" \
     # (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  && \
+# Install the nginx web server package and clean the yum cache
+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).
+# Change the default port for nginx 
+# Required if you plan on running images as a non-root user).
 RUN sed -i 's/80/8080/' /etc/nginx/nginx.conf
+RUN sed -i 's/user nginx;//' /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/"]
+COPY ./s2i/bin/ /usr/libexec/s2i
+
+RUN chown -R 1001:1001 /opt/app-root
+RUN chown -R 1001:1001 /usr/share/nginx
+RUN chown -R 1001:1001 /var/log/nginx
+RUN chown -R 1001:1001 /var/lib/nginx
+RUN touch /run/nginx.pid
+RUN chown -R 1001:1001 /run/nginx.pid
+
+USER 1001
+
+# Set the default port for applications built using this image
+EXPOSE 8080
 
 # Modify the usage script in your application dir to inform the user how to run
 # this image.

examples/nginx-app/save-artifacts

@@ -0,0 +1,11 @@
+
+IMAGE_NAME = nginx-centos7
+
+.PHONY: build
+build:
+	docker build -t $(IMAGE_NAME) .
+
+.PHONY: test
+test:
+	docker build -t $(IMAGE_NAME)-candidate .
+	IMAGE_NAME=$(IMAGE_NAME)-candidate test/run

examples/nginx-app/test/index.html

@@ -0,0 +1,82 @@
+
+# Creating a basic S2I builder image  
+
+## Getting started  
+
+### Files and Directories  
+| File                   | Required? | Description                                                  |
+|------------------------|-----------|--------------------------------------------------------------|
+| Dockerfile             | Yes       | Defines the base builder image                               |
+| s2i/bin/assemble       | Yes       | Script that builds the application                           |
+| s2i/bin/usage          | No        | Script that prints the usage of the builder                  |
+| s2i/bin/run            | Yes       | Script that runs the application                             |
+| s2i/bin/save-artifacts | No        | Script for incremental builds that saves the built artifacts |
+| test/run               | No        | Test script for the builder image                            |
+| test/test-app          | Yes       | Test application source code                                 |
+
+#### Dockerfile
+Create a *Dockerfile* that installs all of the necessary tools and libraries that are needed to build and run our application.  This file will also handle copying the s2i scripts into the created image.
+
+#### S2I scripts
+
+##### assemble
+Create an *assemble* script that will build our application, e.g.:
+- build python modules
+- bundle install ruby gems
+- setup application specific configuration
+
+The script can also specify a way to restore any saved artifacts from the previous image.   
+
+##### run
+Create a *run* script that will start the application. 
+
+##### save-artifacts (optional)
+Create a *save-artifacts* script which allows a new build to reuse content from a previous version of the application image.
+
+##### usage (optional) 
+Create a *usage* script that will print out instructions on how to use the image.
+
+##### Make the scripts executable 
+Make sure that all of the scripts are executable by running *chmod +x s2i/bin/**
+
+#### Create the builder image
+The following command will create a builder image named nginx-centos7 based on the Dockerfile that was created previously.
+```
+docker build -t nginx-centos7 .
+```
+The builder image can also be created by using the *make* command since a *Makefile* is included.
+
+Once image has finished building, the command *s2i usage nginx-centos7* will print out the help info that was defined in the *usage* script.
+
+#### Testing the builder image
+The builder image can be tested using the following commands:
+```
+docker build -t nginx-centos7-candidate .
+IMAGE_NAME=nginx-centos7-candidate test/run
+```
+The builder image can also be tested by using the *make test* command since a *Makefile* is included.
+
+#### Creating the application image
+The application image combines the builder image with your applications source code, which is served using whatever application is installed via the *Dockerfile*, compiled using the *assemble* script, and run using the *run* script.
+The following command will create the application image:
+```
+s2i build test/test-app nginx-centos7 nginx-centos7-app
+---> Building and installing application from source...
+```
+Using the logic defined in the *assemble* script, s2i will now create an application image using the builder image as a base and including the source code from the test/test-app directory. 
+
+#### Running the application image
+Running the application image is as simple as invoking the docker run command:
+```
+docker run -d -p 8080:8080 nginx-centos7-app
+```
+The application, which consists of a simple static web page, should now be accessible at  [http://localhost:8080](http://localhost:8080).
+
+#### Using the saved artifacts script
+Rebuilding the application using the saved artifacts can be accomplished using the following command:
+```
+s2i build --incremental=true test/test-app nginx-centos7 nginx-app
+---> Restoring build artifacts...
+---> Building and installing application from source...
+```
+This will run the *save-artifacts* script which includes the custom code to backup the currently running application source, rebuild the application image, and then re-deploy the previously saved source using the *assemble* script.

examples/nginx-app/Dockerfile renamed to examples/nginx-centos7/Dockerfile

@@ -16,13 +16,16 @@ 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`
+
+#if [ "$(ls /tmp/artifacts/ 2>/dev/null)" ]; then
+#  echo "---> Restoring build artifacts..."
+#  mv /tmp/artifacts/* <your directory here>
+#fi
+
+# Override the 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/index.html /usr/share/nginx/html/index.html
+mv /tmp/src/* /usr/share/nginx/html/

examples/nginx-centos7/Makefile

@@ -7,5 +7,5 @@
 
 # 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-centos7/README.md

@@ -0,0 +1,10 @@
+#!/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
+#
+#tar cf - <your files here>

examples/nginx-app/assemble renamed to examples/nginx-centos7/s2i/bin/assemble

@@ -5,9 +5,9 @@ To use it, install S2I: https://github.com/openshift/source-to-image
 
 Sample invocation:
 
-s2i build test/ nginx-centos7 nginx-app
+s2i build test/test-app nginx-centos7 nginx-centos7-app
 
 You can then run the resulting image via:
-docker run -d -p 8080:8080 nginx-app
+docker run -d -p 8080:8080 nginx-centos7-app
 and see the test via http://localhost:8080
 EOF