blog-rekahsoft-ca/README.org

Source Code for #! Lambda Slang

• Features
• Tools
• License
• Guix Development Environment
  • Start Development Environment
  • Build Site
  • Clean Site
  • Watch
  • Deploy Site
  • Test
• Writing a Blog Post
• Deploying
• Known Issues

#! Lambda Slang is the personal technical blog of Collin Doering, built using software that respects our freedoms.

Features

• Single Page Application (SPA)
• Utilizes CSS 3
• Uses HTML5 Application Cache for offline viewing of website

Tools

The creation of this website was made possible by the following open source tools and libraries:

• Hakyll is used to generate site from static files
• Clay is used for CSS pre-processing
• Skeleton is used for CSS boilerplate
• MathJax is used for rendering mathematics
• JQuery and JQuery-address are used for various DOM manipulations
• Inkscape and the Gimp were used to create various images/artwork
• Gnu Free Fonts, specifically FreeMono is used as main font
• Gnu Emacs because there is no place like home; and no greater editor!

License

Simply put, you're welcome to use the code used to generate this site though there are a few restrictions:

• Any images and artwork that embody the likeness of "#! Lambda Slang" are not to be distributed or used and are strictly copyright
• The content of pages and posts can be used with attribution, providing you aren't making money off of it

Various licenses (GPLv3, Creative Commons BY-NC-SA License, and Creative Commons BY-NC-ND License) are deployed dependent on which part of the site is in question. Please see the LICENSE file for full details.

TODO Guix Development Environment

Guix is used to manage dependencies for this project.

A simple wrapper script site is provided that also takes care of building the static site and offering access to hakyll commands.

Start Development Environment

The development environment is defined by the following files:

channels.scm

Specifically defines a set of available software, their versions and their build recipe.

guix.scm

Defines the package for this site, blog-rekahsoft-ca.

manifest.scm

Defines packages required for development of this site.

  guix time-machine -C channels.scm -- shell -CN -E LANG -E TERM -E PS1 -Df guix.scm -m manifest.scm

This uses the guix time-machine feature to ensure the development environment is reproducible by supplying a set of guix channels, effectively pinning all software versions used. The guix shell command is used within the time-machine to start a development environment in a container (-C), which shares the hosts network namespace (-N). The environment variable LANG is passed into the container to ensure locales work as expected; without this, site building will fail! Additionally, the environment variable TERM is passed into the container to ensure the development shell behaves correctly. Finally, -Df guix.scm indicates that development dependencies of the blog-rekahsoft-ca package should be included in the environment and -m manifest.scm ensures that extra tools for development are included as well.

Build Site

  site build

Clean Site

  site clean

Watch

  site watch

Deploy Site

  site deploy

Test

  site test

Writing a Blog Post

  guix time-machine -C channels.scm -- shell -CN -E LANG

Deploying

Terraform is used to deploy this site. Its configuration files are located in ./infra. Three workspaces are currently available, including:

• default (unused)
• staging
• production

For example, this is how to deploy the production version of the site:

  cd infra
  terraform workspace select production
  terraform plan --var-file=production.tfvars --out local.plan
  terraform apply local.plan

Known Issues

If you have an issue while browsing my blog please file a issue in the blog-rekahsoft-ca issue tracker.