Tuesday, August 12, 2014

Create a static site with Hakyll, Github and Travis CI

"Static sites are fast, secure, easy to deploy, and manageable using version control." So states the webpage for Hakyll, a great way to set up a static site or blog. It allows you to write blog posts by simply editing markdown in git, all the while having access to delicious Haskell for deeper customizations.

You can configure things to let you write blog posts directly on Github's interface and use Travis CI to deploy your changes. Most day-to-day blogging will not require using Haskell at all or even having the Haskell environment installed on the blogger's machine.

I'll show you how to set everything up, including an optimized Travis config that can deploy changes in less than a minute. There is some existing information online about doing this sort of thing, but it's all outdated in one way or another.

We'll be using Github Pages to serve the final assets. I'll assume you're making a static site for a Github organization called myorg and want it to live at myorg.io.

Installation

  1. Create a Github organization. E.g. myorg
  2. Create a project myorg/myorg.github.io
  3. The master branch will be repeatedly overwritten and committed later on by Travis, so you won't make any edits there directly. For now add a file to the root of the master branch called CNAME containing the string myorg.io
  4. Create two A records in the DNS for myorg.io pointing at 192.30.252.153 and 192.30.252.154 respectively.
  5. Generate the base Hakyll project.
  6. Create an orphan source branch in your git repo and copy the generated files there.
  7. You (and Travis) will use cabal to run the site builder, so create a myorg.cabal:
  8. Reuse the cabal sandbox you created earlier:
  9. Keep build artifacts out of git by adding these lines to .gitignore
  10. Run your new site locally to see that it works!
  11. Create .travis.yml and add the following boilerplate:
  12. Generate a Github auth token.
  13. Set encrypted environment variables to allow Travis to commit to the master branch
  14. Commit all the files.
  15. Enable Travis for your repo. Instructions here.
  16. Push the source branch to Github.
  17. Watch the deploy progress at https://travis-ci.org/myorg/myorg.github.io
Now you can create and edit blog posts right in Github and your changes get deployed automatically.

(optional) Generating a custom cabal sandbox for Travis


You can use my shared cabal sandbox on Travis as done above, or you can build your own. It's a little trickier. Use this Travis config as a start. It takes advantage of post-build deployment to S3.

No comments:

Post a Comment