:toc: macro = Hexboard UI

Container vizualization for link:http://openshift.com/[OpenShift⁠ platformV3]. As featured in the link:https://www.youtube.com/watch?v=wWNVpFibayA&t=26m48s[Red⁠ Hat Summit 2015 - JBoss Keynote demo]

toc::[]

= Basic Setup

To get started, you'll need an OpenShiftV3 environment with a valid user account. This project also expects the link:https://github.com/openshift/origin/tree/master/examples/image-streams[basic⁠ set of openshift builder images] to have been installed under the openshift namespace.

You can create your own OpenShiftV3 environment in Amazon EC2 using the link:https://github.com/2015-Middleware-Keynote/demo-ansible[demo-ansible⁠] playbook.

To create your own local OpenShift VM with Vagrant, see link:https://www.openshift.org/vm/[openshift.org/vm/⁠].

== Authentication [source, bash]

oc login

After logging in, run oc whoami using the -t flag to fetch your cli tool's oauth access_token. You will need this token to give the hexboard access to the kubernetes core services API:

[source, bash]

oc whoami -t

== Create a project Create a project to house this application:

[source, bash]

oc new-project hexboard

Launch this project in a single step by running:

[source, bash]

oc new-app -f https://raw.githubusercontent.com/2015-Middleware-Keynote/hexboard/master/app_template.json⁠ -p ACCESS_TOKEN=$(oc whoami -t)

You can also install the template into your current project, which will make it easier to launch using the web console:

[source, bash]

oc create -f https://raw.githubusercontent.com/2015-Middleware-Keynote/hexboard/master/app_template.json⁠

Or, create each service individually:

[source, bash]

oc new-app -l servicegroup=sketchpod openshift/nodejshttp://github.com/2015-Middleware-Keynote/sketchpod⁠ oc new-app -e "ACCESS_TOKEN=${ACCESS_TOKEN}" openshift/nodejshttp://github.com/2015-Middleware-Keynote/hexboard⁠

Then, check the results:

[source, bash]

oc get builds -w

= Builds

Docker image builds can be initiated by navigating to the "Builds" tab in the V3 web console. Click on the Start Build button for each service.

You can also initiate the builds from the command line:

[source, bash]

oc start-build hexboard oc start-build sketchpod

Watch the progress:

[source, bash]

oc get pods -w

= Routing

In order to view the hexboard, you'll need to expose your service by setting up a Route. The optional --hostname flag allows you to create a custom route to an existing service:

[source, bash]

oc expose svc/hexboard --hostname=

Make sure this route is addressable from wherever you are running your browser (an /etc/hosts entry in your client may be required).

Excluding the --hostname flag should generate a default route that automatically takes advantage of your cluster's wildcard DNS (if available):

[source, bash]

oc expose svc/hexboard

Now, try listing your existing routes:

[source, bash]

oc get route

= Configuration

The service configuration is provided via environment variables. These configs can be set while loading a project from a template via the web console or via the oc process command.

You can also add environment keys to an existing deployment config using the oc env command. Setting new configuration details will trigger a deployment to distribute your changes (if needed).

API Access Token

To set the requiredACCESS_TOKEN config, follow the instructions in the above link:#authentication[Authentication] section, using your own ACCESS_TOKEN value in the following example:

[source, bash]

oc env dc/hexboard ACCESS_TOKEN=$(oc whoami -t)

Admin Controls

For access to to the hexboard's Admin UI controls ('push random sketches', 'clear sketches', and 'pick random winners' features), you'll need to supply matching ADMIN_TOKENs on the server, and on your client device.

Set a server-side ADMIN_TOKEN:

[source, bash]

oc env dc/hexboard ADMIN_TOKEN="${ADMIN_TOKEN}"

You'll need to set the same token in your browser to reveal the Admin UI controls. Visit "http://YOUR_HEXBOARD/?admin=YOUR_ADMIN_TOKEN" to add administrative UI controls to your browser.

Winner Count

The number of winning sketches is now adjustable via the WINNER_COUNT environment variable. The default value is ten winners.

You can set the number of winning sketch submissions to three by running the following:

[source, bash]

oc env dc/hexboard WINNER_COUNT=3

Hexboard Size

The number of pods in the hexboard can be controlled by setting the HEXBOARD_SIZE environment variable: [options="header"] |=== | HEXBOARD_SIZE | # of pods | | xlarge | 1026 | "keynote" sized | large | 513 | major league | medium | 266 | cluster pro | small | 108 | multi machine party | xsmall | 63 | fun sized | tiny | 32 | large laptop allocation | micro | 24 | medium laptop allocation | nano | 12 | small laptop allocation |===

[source, bash]

oc env dc/hexboard HEXBOARD_SIZE= oc get pods -w

NOTE: setting an environment variable triggers a new deployment, so watch the oc get pods -w output to see when the deployment is complete.

= Scaling Animations of falling hexagons are triggered as the number of pods is scaled. To scale the number of hexagons (either up or down) run the command:

[source, bash]

oc scale dc/sketchpod --replicas=

After scaling up, try submitting sketches by visiting the hexboard's bundled mobile web submission form, at http://your-hexboard-hostname/mobile/.

= Auto-Recovery After scaling up, the hexboard provides a nice way to visualize Kubernetes' support for auto-healing the containerized environments.

You can show this functionality by deleting a group of pods. This example makes it easy find and delete five pods:

[source, bash]

oc delete pod $(oc get pods | grep ^sketchpod | grep -v build | cut -f1 -s -d' ' | sort -R | head -n 5 | tr '\n' ' ')

WARNING: There is a link:https://github.com/2015-Middleware-Keynote/hexboard/issues/30[known⁠ issue] that may cause display errors when pods are deleted.

Workaround: Instead of showing autorecovery on the hexboard, show this feature using the OpenShift web console. Your project Overview page's view modes (list, topographical) both nicely illustrate how this feature works.

= Local Development

== Pre-Requisutes

• node.js (installed globally)
• gulp.js (installed globally)

== Installation

Execute the following commands in your local clone of this repository: [source, bash]

npm install

== Run the hexboard locally

Run gulp in it's own terminal, providing environment variables that reference an available OpenShift cluster where your sketchpod service back-ends will be hosted and scaled:

[source, bash]

PORT=8081 PROXY="localhost:1080" ACCESS_TOKEN="${ACCESS_TOKEN}" OPENSHIFT_SERVER="localhost:8443" NAMESPACE=hexboard gulp

= Cleanup

To delete all sketchpods using a labelselector, try this:

[source, bash]

oc delete all -l servicegroup=sketchpod

You can clean out the entire contents of the hexboard project by running the following:

[source, bash]

oc delete all --all -n hexboard

TIP: Be careful to verify that you have logged into the correct server, and have selected the correct project before running this command!

Or, delete the entire project and any included resources:

[source, bash]

oc delete project hexboard