Thursday, September 26, 2013

OpenShift Primer - an example for hosting your awstruct presentations in the cloud

It has never been easier to combine excellent cloud and JBoss technology, like Ruby, that a nifty presentation tool called impress.js, a site generation tooling known as awestruct, and cloud hosting from OpenShift to dazzle at your next presentation.

Introduction

The example I am going to take you through will eventually look just like this site, where you find some of my presentations for the last hear, deployed in a Ruby based OpenShift cloud instance, written using impress.js, and generated by awestruct.

Note that you can browse through the presentations, use the arrows provided in the bottom right corner to walk through the slides, embed your site and presentations anywhere as it is HTML (just use an iframe), and that it is automatically available on all mobile devices without any more adjustments from your side.



Getting started

You will need Git, Ruby, some editor, an OpenShift account, and awestruct installed, you know the basics. I am not going to walk through all of this with you, but assume you can follow these components getting started guides.

What I have done is put together a quickstart to get your site as shown above up and running, which is then a template for adding in your very own presentations. It is giving you a head start, to save some time. Follow along as I walk you through putting this together on your own, first from the web admin console from OpenShift, then from the command line with OpenShift tooling (rhc).

OpenShift web console
You will need to login to OpenShift (http://openshift.com) with your user and create a ruby 1.9 cartridge (not the older ones you might see listed there). Just name it presos and leave the rest to default settings.
Ruby 1.9 cartridge creation.
You will be presented with a getting started screen, with half way down the page instructions for cloning the repository of the instance you just created. You will need to open a console and clone this into your local machine:

$ git clone ssh://5242ecxxxxxxxxx0000aa@presos-inthe.rhcloud.com/~/git/presos.git/

Now change into the presos directory and we will be copying into your repository, the setup I have ready for you in my repository (https://github.com/eschabell/openshift-presos-awstruct/tree/v0.3). Run the following commands.

$ cd presos
$ git remote add upstream -m master git://github.com/eschabell/openshift-presos-awstruct.git
$ git pull -s recursive -X theirs upstream master
$ git push

This will pull down my code into your project, merge the results, then you push it up to your OpenShift instance. Watch the console output as it merges in the new code, installs the required awestruct dependencies, kick starts the server, and you are ready to check out your project online at http://presos-$yourdomain.rhcloud.com.

Command line tooling
Once you have installed the OpenShift command line tooling (just a gem install rhc command for unix based machines), you can do the folowing to get your ruby instance setup and populated with my quickstart project.

$ rhc app create -a presos -t ruby-1.9 --from-code=https://github.com/eschabell/openshift-presos-awstruct.git

This will pull down my code into your project, merge the results, then you push it up to your OpenShift instance. Watch the console output as it merges in the new code, installs the required awestruct dependencies, kick starts the server, and you are ready to check out your project online at http://presos-$yourdomain.rhcloud.com.

Bring it to life

You will notice that the site you are looking at is found in presos/lib/*, here you will need to place your own presentations. Each presentation is represented by a .haml file. This is used to generate the eventual .html file.

$ cat judcon2013_rockstar.html.haml 
---
layout: judconbase
---

.slides
  %section.title(data-state="judcon2013" )
    .title-information
      %h2 Do you want
      %h4 to be a
      %h2 JBoss Rock Star
      %h5
    .title-author
      Eric D. Schabell
      %br
        JBoss Technology Evangelist (Integration & BPM)
      %a{ :href=>"http://twitter.com/ericschabell"}@ericschabell

  %section(data-state="judcon2013" )
    .title-information
    %h1 What does it take?

If we take a closer look at the rockstar presentation haml file, we see that it starts with a layout referencing a base file, in this case called judconbase. We find this is just an included haml file locating in the _layouts directory. Review this for things you might want to adjust for your presentation, but you will note a line that is important which links to a css file where we will set up any images we want to use.

%link{ :rel=>'stylesheet', :type=>'text/css', :href=>"#{site.base_url}/css/theme/judcon.css", :id=>'theme'}

Then you will find a .slides line that starts the slides, here we show only two slides, which are defined using markdown. The data-state attribute is a link to the css file we mentioned above, where if you look there you will find the images used in the slides setup to display as a background, cover, or somewhere inside the slide canvas area.

The easiest way to determine how your changes are affecting the layout of your slides is to run the awestruct command from the lib directory and in daemon mode. This will provide a local server for you to access at http://localhost:4242, and it is auto updated each save of a file in the lib directory.

$ cd presos/lib
$ awestruct -d

By default the build that awestruct is creating is for localhost, but you can adjust the file in presos/lib/_config/site.yml to have several profiles. Just run awestruct with the -P flag and provide one of your profiles to generate a new target site in _site.

Code, deploy, enjoy

The motto is code, deploy, enjoy! I hope this article provides a bit of a helping hand to get you started in pushing your presentations online.