thumbnail

Signed-off-by: Doug Davis <[email protected]>

README.md

@@ -1,50 +1,79 @@
-# Samples for IBM Cloud Code Engine
+# Tutorials and Samples for IBM Cloud Code Engine
 
-This repository contains samples for how to use
-[IBM Cloud Code Engine](https://cloud.ibm.com/codeengine).
+This respository is split into two types of educational material: Tutorials
+and Samples.
 
-These samples are designed such that they should be able to be fully built
-and used by anyone. Unless otherwise noted the overall pattern that will be
-followed is:
+Tutorials are meant to be complete end-to-end scenarios designed
+to teach you about [Code Engine](https://ibm.com/cloud/code-engine) as if you
+have limited knowledge of Cloud Native technologies. Each provides a
+step-by-step guide walking you through the process of deploying a certain
+type of workload - explaining, in detail, each step in the process. The goal
+is to not simply have you copy-n-paste each command but rather to understand
+the "whys" of what's going on so you can apply what you've learned to one
+of your own projects.
 
-- a `build` script shows how each container image used in the sample is built.
-  By default, the script will push the image to the `ibmcom` namespace on
-  DockerHub, so to use this yourself you'll need to set the `REGISTRY`
-  environment variable to your own registry and/or namespace. Also, you
-  MUST use a registry that allows for anonymous/public downloads of your
-  images, since as of now (to keep the scripts simple) they do not deal
-  with private registry access tokens by default.
-  - However, if you do decide to push your images into a registry that
-    is private, you'll need to modify the `run` scripts to specify the
-	`--registry-secret` option on the app and job creation commands to point
-	to your secret that includes the registry credentials.
-- a `run` script will execute the sample. Most will also include logic to
-  verify the output to ensure everything is working as expected. As with
-  `build`, it will default to using the `ibmcom` container images, so to use
-  your own you'll need to set the `REGISTRY` environment variable.
-  This means that you should be able to just execute `run` without running
-  `build` first, and it'll just use the pre-built images from `ibmcom`.
-  - invoking `run clean` should clean up from any previous execution without
-    re-running the sample.
+Samples are meant to be "quick-start" tasks that help developers
+perform one very specific task. They do not include extra verbose help text
+or explanations, rather they are designed for people who have a basic
+understanding of Cloud Native technologies and want a quick reminder of how
+to perform a certain task in the Code Engine environment. Most samples will
+be relatively small so that it can be re-used easily and integrated into a
+larger use-case.
+
+### Getting Started
 
-Most samples will try to be relatively small to focus on one particular
-task so that it can be re-used easily and integrated into a larger use-case.
+#### Cloud Shell
 
-It is assumed that the following are installed:
+The easiest way to run these are via the
+[IBM Cloud Shell](https://cloud.ibm.com/shell). Simply open up a new Cloud
+Shell, clone the repository (`git clone https://github.com/IBM/CodeEngine`)
+and then `cd` into the directory of interest.
+
+To ensure you have the latest versions of each CLI plugin, run:
+```
+$ ic plugin update --all --force
+```
+
+#### Your Own Machine
+
+If you choose to use your own machine, then the following need to be installed:
 - [IBM Cloud command line (`ibmcloud`)](https://cloud.ibm.com/docs/cli/reference/ibmcloud?topic=cloud-cli-getting-started)
 - [Code Engine plugin (`ce`)](https://cloud.ibm.com/codeengine/cli)
 - [Cloud Object Storage plugin (`cos`)](https://cloud.ibm.com/docs/cloud-object-storage-cli-plugin)
   for samples which use IBM Cloud Object Storage
-- [`docker`](https://docker.io/) if you choose to build the images yourself
+- [`docker`](https://docker.io/) if you choose to build the images yourself.
+  For novices, skip this.
+
+As with the Cloud Shell option, clone the repository
+(`git clone https://github.com/IBM/CodeEngine`) and then `cd` into the
+directory of interest.
+
+#### Let's go!
+
+Most of the material in here assumes you aleady have a Code Engine
+[project](https://cloud.ibm.com/docs/codeengine#term-summary) already created.
+If you do not, go ahead and create one like this:
 
-It is also assumed that you have a Code Engine project already created and
-selected, e.g.:
 ```
 $ ibmcloud ce project create --name demos
 ```
 
+With that, `cd` into the directory of interest, and read the README to see how
+to get started.
+
+## Tutorials
+
+- [Thumbnail Generator](thumbnail)<br>
+  Walks through the complete growth path of an application from the prototype
+  stage through to production - demonstrating how to switch from an in-app
+  processor to one where the data is persisted and processed via an
+  event-driven architecture.
+
 ## Samples
 
+The samples are grouped by the main category of functionality that it
+is demonstrating.
+
 #### Apps
 - [hello](hello)<br>
   Very basic "hello world!" type of application written in Node.js. Start here!
@@ -128,9 +157,35 @@ $ ibmcloud ce project create --name demos
 - [secrets-vol](secrets-vol)<br>
   Shows how to define and inject a Secret as a volume into an Application.
 
-## Resources
+## Layout of the repository
+
+These are designed such that they should be able to be fully built
+and used by anyone. Unless otherwise noted the overall pattern that will be
+followed is:
+
+- a `build` script shows how each container image used in the sample is built.
+  By default, the script will push the image to the `ibmcom` namespace on
+  DockerHub, so to use this yourself you'll need to set the `REGISTRY`
+  environment variable to your own registry and/or namespace. Also, you
+  MUST use a registry that allows for anonymous/public downloads of your
+  images, since as of now (to keep the scripts simple) they do not deal
+  with private registry access tokens by default.
+  - However, if you do decide to push your images into a registry that
+    is private, you'll need to modify the `run` scripts to specify the
+	`--registry-secret` option on the app and job creation commands to point
+	to your secret that includes the registry credentials.
+- a `run` script will execute the sample. Most will also include logic to
+  verify the output to ensure everything is working as expected. As with
+  `build`, it will default to using the `ibmcom` container images, so to use
+  your own you'll need to set the `REGISTRY` environment variable.
+  This means that you should be able to just execute `run` without running
+  `build` first, and it'll just use the pre-built images from `ibmcom`.
+  - invoking `run clean` should clean up from any previous execution without
+    re-running the sample.
+
+## Additional Resources
 
-- [IBM Cloud Code Engine](https://cloud.ibm.com/codeengine)
+- [IBM Cloud Code Engine](https://ibm.com/cloud/code-engine)
 - For questions/comments join us on Slack:<br>
   [Register](https://cloud.ibm.com/kubernetes/slack) |
   [Login](https://ibm-cloud-success.slack.com/) and join us on the

app-n-job/build

@@ -2,6 +2,7 @@
 
 # Env Vars:
 # REGISTRY: name of the image registry/namespace to store the images
+# NOCACHE: set this to "--no-cache" to turn off the Docker build cache
 #
 # NOTE: to run this you MUST set the REGISTRY environment variable to
 # your own image registry/namespace otherwise the `docker push` commands
@@ -12,7 +13,7 @@ set -ex
 export REGISTRY=${REGISTRY:-ibmcom}
 
 # Build the image
-docker build -t ${REGISTRY}/app-n-job .
+docker build ${NOCACHE} -t ${REGISTRY}/app-n-job .
 
 # And push it
 docker push ${REGISTRY}/app-n-job

app2job/build

@@ -2,6 +2,7 @@
 
 # Env Vars:
 # REGISTRY: name of the image registry/namespace to store the images
+# NOCACHE: set this to "--no-cache" to turn off the Docker build cache
 #
 # NOTE: to run this you MUST set the REGISTRY environment variable to
 # your own image registry/namespace otherwise the `docker push` commands
@@ -12,9 +13,9 @@ set -ex
 export REGISTRY=${REGISTRY:-ibmcom}
 
 # First build the app's image and push it
-docker build -t ${REGISTRY}/a2j-app -f Dockerfile.app .
+docker build ${NOCACHE} -t ${REGISTRY}/a2j-app -f Dockerfile.app .
 docker push ${REGISTRY}/a2j-app
 
 # Now build the job's
-docker build -t ${REGISTRY}/a2j-job -f Dockerfile.job .
+docker build ${NOCACHE} -t ${REGISTRY}/a2j-job -f Dockerfile.job .
 docker push ${REGISTRY}/a2j-job

bin/clean

@@ -5,14 +5,16 @@
 cd $(dirname $0)/..
 
 set -e
+
+rm -f run-all.out run-fail.out *.fail *.out
+
 for file in `find . -name run | sort` ; do
   dir=`dirname $file`
   dir=${dir:2}  # remove leading ./
 
   # Skip this dir 'cause we're asked or if it's to be run sequentially
   [[ -e ${dir}/.SKIP ]] && echo "Skipping $dir " && continue
 
-  # Run the sample with whatever REGISTRY we're pointing to
   echo "> $dir"
   (
     cd $dir

bin/run-all-parallel

@@ -45,6 +45,7 @@ set -e
     dir=${dir:2}  # remove leading ./
 
     # Only process samples that are meant to be run sequentially
+    [[ -e ${dir}/.SKIP ]] && continue
     [[ ! -e ${dir}/.SEQ ]] && continue
 
     # Run the sample with whatever REGISTRY we're pointing to

bin/run-tutorial

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+set -e -o pipefail
+[[ "$1" == "clean" ]] && CLEAN="true"
+
+while read -u 3 line ; do
+  line="$prev$line"
+  if [[ "$line" == *"\\" ]]; then
+    prev="${line: -2}"
+    continue
+  fi
+  prev=""
+
+  [[ "$line" != "\$"* && "$line" != "[//]:"* ]] && continue
+
+  if [[ "$line" == "[//]: "* ]]; then
+    line=${line:6}
+
+	[[ "$line" == "clean" ]] && FOUND_CLEAN="true" && set +e && continue
+
+	if [[ "$CLEAN" == "" || "$FOUND_CLEAN" != "" ]]; then
+      env | sort > origenv
+      eval $line || { echo "Failed: $line" ; exit 1 ; }
+      set +e ; env | sort | diff origenv - | grep -v '^[0-9]\+a' ; set -e
+	  echo
+	fi
+  else
+    if [[ "$CLEAN" == "" || "$FOUND_CLEAN" != "" ]]; then
+      line=${line:2}
+      echo -n '$' $line" "
+      test -n "$PAUSE" && { read -sn 1 a; [[ "$a" == "r" ]] && PAUSE=""; }; echo
+	  eval $line 2>&1 | ( ( [[ "$line" == "export"* ]] && cat ) || tee out )
+      echo
+	  [[ "$line" == "exit"* ]] && exit 0
+	fi
+  fi
+done  3< README.md
+rm -f out origenv dog

bind-app/build

@@ -2,6 +2,7 @@
 
 # Env Vars:
 # REGISTRY: name of the image registry/namespace to store the images
+# NOCACHE: set this to "--no-cache" to turn off the Docker build cache
 #
 # NOTE: to run this you MUST set the REGISTRY environment variable to
 # your own image registry/namespace otherwise the `docker push` commands
@@ -12,5 +13,5 @@ set -ex
 export REGISTRY=${REGISTRY:-ibmcom}
 
 # First build the app's image and push it
-docker build -t ${REGISTRY}/bind-app -f Dockerfile .
+docker build ${NOCACHE} -t ${REGISTRY}/bind-app -f Dockerfile .
 docker push ${REGISTRY}/bind-app

bind-app/run

@@ -39,8 +39,8 @@ ibmcloud ce app bind --name ba-app --service-instance ba-db
 curl -fs ${URL} | tee out
 [[ "${PIPESTATUS[0]}" == "0" ]]
 
-if ! grep VCAP_SERVICES out > /dev/null ; then
-  echo "Missing VCAP_SERVICES in App's env vars"
+if ! grep CE_SERVICES out > /dev/null ; then
+  echo "Missing CE_SERVICES in App's env vars"
   exit 1
 fi
 

bind-job/build

@@ -2,6 +2,7 @@
 
 # Env Vars:
 # REGISTRY: name of the image registry/namespace to store the images
+# NOCACHE: set this to "--no-cache" to turn off the Docker build cache
 #
 # NOTE: to run this you MUST set the REGISTRY environment variable to
 # your own image registry/namespace otherwise the `docker push` commands
@@ -12,5 +13,5 @@ set -ex
 export REGISTRY=${REGISTRY:-ibmcom}
 
 # First build the app's image and push it
-docker build -t ${REGISTRY}/bind-job -f Dockerfile .
+docker build ${NOCACHE} -t ${REGISTRY}/bind-job -f Dockerfile .
 docker push ${REGISTRY}/bind-job

bind-job/job.go

@@ -7,13 +7,13 @@ import (
 )
 
 func main() {
-	// Pretty print the VCAP_SERVICES
-	services := os.Getenv("VCAP_SERVICES")
+	// Pretty print the CE_SERVICES
+	services := os.Getenv("CE_SERVICES")
 	data := json.RawMessage{}
 	json.Unmarshal([]byte(services), &data)
 	data, _ = json.MarshalIndent(data, "  ", "  ")
 	services = string(data)
 
 	fmt.Printf("Hello from a job - my index is: %s\n", os.Getenv("JOB_INDEX"))
-	fmt.Printf("\nAnd my VCAP_SERVICES is:\n  %s\n", services)
+	fmt.Printf("\nAnd my CE_SERVICES is:\n  %s\n", services)
 }

bind-job/run

@@ -42,8 +42,8 @@ ibmcloud ce jobrun submit --name myrun --job bj-job --wait
 # Now look at a view of the logs to make sure it worked
 ibmcloud ce jobrun logs --instance myrun-1-0 | tee out
 
-if ! grep VCAP_SERVICES out > /dev/null ; then
-  echo "Missing VCAP_SERVICES in App's env vars"
+if ! grep CE_SERVICES out > /dev/null ; then
+  echo "Missing CE_SERVICES in App's env vars"
   exit 1
 fi
 

cecli/build

@@ -2,6 +2,7 @@
 
 # Env Vars:
 # REGISTRY: name of the image registry/namespace to store the images
+# NOCACHE: set this to "--no-cache" to turn off the Docker build cache
 #
 # NOTE: to run this you MUST set the REGISTRY environment variable to
 # your own image registry/namespace otherwise the `docker push` commands
@@ -12,7 +13,7 @@ set -ex
 export REGISTRY=${REGISTRY:-ibmcom}
 
 # Build the image
-docker build -t ${REGISTRY}/cecli .
+docker build ${NOCACHE} -t ${REGISTRY}/cecli .
 
 # And push it
 docker push ${REGISTRY}/cecli

configmaps-env/build

@@ -2,6 +2,7 @@
 
 # Env Vars:
 # REGISTRY: name of the image registry/namespace to store the images
+# NOCACHE: set this to "--no-cache" to turn off the Docker build cache
 #
 # NOTE: to run this you MUST set the REGISTRY environment variable to
 # your own image registry/namespace otherwise the `docker push` commands
@@ -12,7 +13,7 @@ set -ex
 export REGISTRY=${REGISTRY:-ibmcom}
 
 # Build the image
-docker build -t ${REGISTRY}/ce-config-env .
+docker build ${NOCACHE} -t ${REGISTRY}/ce-config-env .
 
 # And push it
 docker push ${REGISTRY}/ce-config-env

configmaps-vol/build

@@ -2,6 +2,7 @@
 
 # Env Vars:
 # REGISTRY: name of the image registry/namespace to store the images
+# NOCACHE: set this to "--no-cache" to turn off the Docker build cache
 #
 # NOTE: to run this you MUST set the REGISTRY environment variable to
 # your own image registry/namespace otherwise the `docker push` commands
@@ -12,7 +13,7 @@ set -ex
 export REGISTRY=${REGISTRY:-ibmcom}
 
 # Build the image
-docker build -t ${REGISTRY}/ce-config-vol .
+docker build ${NOCACHE} -t ${REGISTRY}/ce-config-vol .
 
 # And push it
 docker push ${REGISTRY}/ce-config-vol

cos-event/build

@@ -2,6 +2,7 @@
 
 # Env Vars:
 # REGISTRY: name of the image registry/namespace to store the images
+# NOCACHE: set this to "--no-cache" to turn off the Docker build cache
 #
 # NOTE: to run this you MUST set the REGISTRY environment variable to
 # your own image registry/namespace otherwise the `docker push` commands
@@ -12,7 +13,7 @@ set -ex
 export REGISTRY=${REGISTRY:-ibmcom}
 
 # Build the image
-docker build -t ${REGISTRY}/cos-listen .
+docker build ${NOCACHE} -t ${REGISTRY}/cos-listen .
 
 # And push it
 docker push ${REGISTRY}/cos-listen