Fun with Static Site Generators and Travis


Overview

If you use a static website generator, then you may be aware of the pain that goes into getting everything automated and pushed out to github pages on each commit.

The manual workflow goes something like this:

  1. code your site using asciidoc/markdown/haml/sass/less/etc
  2. preprocessor (or build) generates static site (locally on your machine)
  3. copy static site to your local gh-pages or username.github.com repo/branch
  4. git push new site
  5. done

Now, with a little scripting we can have:

  1. code your site using asciidoc/markdown/haml/sass/less/etc
  2. git push to source repo
  3. done (with so many other cool features at our fingertips)

Most preprocessor tools do have some kind of built in function for this workflow, but when you need to take it to a finer grained level and leverage services on the CI server, then this is what must be done.

With our new workflow, we let Travis CI do the work for us in a bash script. This opens the door to automation greatness for many other things like testing and asset uploads. As you will see at the end of this article, we add a simple PhantomJS script to test how each new commit loads (over time) in a web browser - giving us a baseline for site performance.

This post is going to review the basics of setting up your github OAuth token, encryption with travis, and finally pushing your website to github pages with an automated travisci build. We’ll top it all off with running loadreport.js after each check in to understand how a single commit can affect site performance. So let’s go…

Github hosting setup

If you’re unfamiliar with github pages or how to host your own top-level domain (yourdomain.com) under your github account, then read this, then this first.

Github, Travis, and OAuth

First off, you must login to Travis CI with your github username and enable the travis service hook on the repository you wish to automate. For me, this is where my haml/sass/etc… source is located. travis Next, we’ll create an OAuth token for your repository access :

Pluck the “token”: string value from the generated json and encrypt it. Pro tip: this token is basically the same thing as your password. So don’t push it out to a public repository.

To encrypt, we must install the travis gem and encrypt the token string from above with: ..this will create a string in your console and we’ll paste it below, so keep it close by…

Now, we can create the gh-pages branch for this repository following these instructions. This gh-pages branch can host your generated site or artifacts. Since I have a TLD mapped to my wesleyhales.github.com repository, I’m using the gh-pages branch under my source account for load testing reports. For my blog, I’m mapping a domain name over by simply forwarding a TLD like wesleyhales.com, with an A record pointing to 204.232.175.78. Then I added a CNAME file to the repo so github DNS knows where to forward to.


The Build Config

Finally, we’re ready to update our .travis.yml. Awestruct is a ruby based preprocessor, so this project is setup with the travis ruby config (above).

Note the before_script and script configs:

before_script runs the awestruct build and then the post_build.sh script. post_build.sh pushes our newly generated public facing website to github pages. This is where github kindly serves up our static content at username.github.com (for free).

And finally, script will run gh-pages-report.sh. This allows us to run loadreport.js and send the generated report to our source gh-pages branch. Travis CI provides an instance of phantomjs during our build, so all we have to do is call it. This is basically a build report (or artifact from the build). It measures how long it takes our site to load after each commit is made. This gives us a baseline for measuring performance.


##The Results

The source for this blog you are reading is stored on github here. When I do a git push, everything is automatically built with travis and pushed again to the github repo that is specially named to handle the mapping of my TLD (wesleyhales.com) to my username on github.

Since I have 2 repositories, one for the preprocessor source and the other for the TLD mapping, I’m using the gh-pages branch on my source repository for reporting. With PhantomJS and loadreport.js, I run a test on every commit to see how I affected my sites loading performance. The results of this test are automatically pushed and I can view them here.

From a UI polish perspective, I have a ton left to do. But the concept stays the same for any build. Use it to build and push out project documentation along with other reports and assets. I’d eventually like to write a script to do a diff on only test the pages that were changed on the commit.