An Introduction
Hello, my name is Dan, I’m a server developer here at Assurant Labs, and it’s my pleasure to welcome you to our new public site and blog. I recently had the opportunity to, along with Matt– one of the designers here, work on a complete overhaul of our public site. This overhaul encompassed everything from a full visual update to a fundamental change in the way that we’ll be developing, maintaining, and deploying changes to this site going forward. Today I’ll be walking through some of our reasoning behind this new approach, and giving a broad overview of the technologies that came into play between the initial idea and the site you see before you today in this post.
I’m also kicking off our new initiative to keep this blog up to date with insights we’ve gleaned working on a whole host of projects across as many platforms. We’ve got a bunch of great posts lined up, so be sure to stay tuned.
Let’s get started.
Going Off the Rails
I am, primarily, a Rails developer. While I spend my time working on a variety of projects in various capacities, at the end of the day most of my time is spent working in our core server project, which orchestrates the API communication with devices, administrative tools for user & device management, and integrations with various external services. This made it spectacularly easy for me to work on our old public site.
Rails is many things, good and bad, but one of its biggest strengths is its productivity.
As job listings came and went, and copy revisions needed to be integrated, it was easy enough for myself or other Rails developers to update what needed to be updated as part of our daily routine. Over time, a fairly robust series of partials, and routing logic had been constructed that made these changes trivial, which for a long time was good enough. However, where it was lacking was an ability for non-Rails developers, or even non-developer members of our team to add or update content.
Rails is many things, good and bad, but one of its biggest weaknesses is (at least to a Rails outsider) its magic.
The same “magic” that makes Rails so productive to people initiated in its ways makes it nigh unmanageable to somebody who hasn’t devoted time to the teachings of DHH. The combination of a somewhat opaque correlation between content’s location on the site and its location in the project, with the legwork that goes into having to update dependencies for an infrequently used project meant that only Rails developers were able to make the needed changes in a proportionate amount of time. Since the public site only made up a small fraction of the Rails project, Rails developer time was usually tied up elsewhere. Like everything else, a project at rest tends to stay at rest, so it was only infrequently that the site was updated.
Additionally, code reviews, staging environment deployments, and all of the other measures we take to ensure that any code that makes it to production has been properly vetted often held up relatively minor changes to the public site that needed a spelling check and grammatical proofread at most.
A Stevensonian Solution
Upon evaluating our choices of platform for the website redesign, it seemed that there were two clear options. The first would be to implement, or adapt a CMS solution into our existing project. Given the relatively small time frame in which we hoped to have the new site running, this wasn’t a particularly viable option. There are plenty of gems that purport to offer a fool-proof drop-in solution, but in my experience they tend to be flexible enough to get 90% of the way to your desired outcome before becoming completely intractable.
The other option, the one that we wound up using, is Jekyll.
I’m not going to spend too much time here describing what Jekyll is, their documentation does a pretty good job of that itself, but the important takeaway is that it is a static site generator with a robust templating engine, and the ability to expand functionality with gems in an “entirely compatible with my Rubyist tendencies” sort of way.
I was very quickly able to assemble the skeleton of our new project, and set up the “dynamic” elements– this blog, and our job listings section (we’re hiring, make sure to check them out) with Jekyll’s collections. It was then just a matter of filling out the layout (based on Bootstrap, as all fast-paced web projects are obligated to be), setting up an integration strategy that would allow us to quickly iterate and see results immediately, and provisioning the web tier of our application such that this new site could replace our previous one with minimal disturbance (probably a topic best served by its own blog post).
Jekyll integrates very nicely with Github, which we already use for all of our version control needs, and we briefly considered simply hosting our new project on Github Pages, but in the end we decided to serve the site from an S3 bucket. GH Pages seems like a mostly reliable and sane option should you choose to host there, but the added reliability of AWS combined with the ability to easily integrate with Cloudfront to serve all of the gorgeous (I might also be a hobbyist photographer) images you see on this site biased our decision in Amazon’s direction.
Always Be Integrating (Continuously)
My main goal/ not-so-secret plan going into this project was that anybody in the company who wanted to contribute a blog post or update a job listing should be able to do so without the need for a crash course in git, a walkthrough of homebrew, or really any knowledge of Jekyll at all. We already use Markdown for our internal documentation and a few other projects, so Jekyll’s ability to turn a folder of markdown files into a blog was a perfect fit.
Through Github’s web interface, files can be edited or created entirely without any command line knowledge, and automatically submitted as a pull request to the project. We follow a well-defined branching strategy documented here which is well understood by all of our engineers, but the web interface provides a very low friction way for anybody to add a post or amend a listing that only requires cursory examination by a maintainer of the project.
We use TeamCity to build our various projects and run their corresponding test suites, so it was a very minor modification to add a build configuration that, upon a change to master re-built the Jekyll site, and used the AWS CLI to synchronize the newly built site with S3 and invalidate caches on Cloudfront as needed.
Taken as a whole, this means that a blog post can be written on Github, a pull request with it’s contents opened, a review performed, the code merged, and the post deployed to the broader world all without needing to launch the terminal. Obviously people who are comfortable doing so can still write their posts in their editor of choice, committing with the CLI or GUI they’re most comfortable with, but the door has been opened to allow those without that familiarity to contribute just as effectively as Rails developers, or our engineering team as a whole.
In Conclusion
This project was a lot of fun. Jekyll wound up, at least as far as we’ve been able to tell one week in, being a perfect solution to our problem. This site was able to be developed in a very short time frame, to allow maintenance and contribution at a rate and breadth that one implemented within the confines of our Rails project couldn’t have without serious expenditure of time and effort, and facilitated a fantastic new design that will hopefully last us far into the future (which, at the rate Internet trends change, will probably be sometime mid-April).
As you can tell, I’ve got no shortage of things to say about this project, and while I didn’t anticipate writing quite this much when I began the post, I somehow haven’t quite run out of things to say– so there may be more posts forth-coming. In the mean time feel free to check out the rest of the site, or get in touch with us if there’s anything you’d like to add, ask, or correct. Thanks for sticking with me if you’ve made it this far, and I hope you like the new site!