blog-rekahsoft-ca/README.org

#+TITLE: Source Code for [[http://www.blog.rekahsoft.ca][#! Lambda Slang]]
#+AUTHOR: Collin J. Doering

#+BEGIN_EXPORT html
<p><a href="https://ci.home.rekahsoft.ca/rekahsoft/blog-rekahsoft-ca"><img src="https://ci.home.rekahsoft.ca/api/badges/rekahsoft/blog-rekahsoft-ca/status.svg" alt="Build Status"></a></p>
#+END_EXPORT

#+begin_abstract
[[http://www.blog.rekahsoft.ca][#! Lambda Slang]] is the personal technical blog of *Collin Doering*, built using software that
[[https://www.gnu.org/philosophy/free-sw.html][respects our freedoms]].
#+end_abstract

* Features

- [[http://en.wikipedia.org/wiki/Single-page_application][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:

- [[http://jaspervdj.be/hakyll/][Hakyll]] is used to generate site from static files
- [[http://fvisser.nl/clay/][Clay]] is used for CSS pre-processing
- [[http://www.getskeleton.com/][Skeleton]] is used for CSS boilerplate
- [[http://www.mathjax.org/][MathJax]] is used for rendering mathematics
- [[http://jquery.com][JQuery]] and [[https://github.com/asual/jquery-address][JQuery-address]] are used for various DOM manipulations
- [[http://inkscape.org/][Inkscape]] and the [[http://www.gimp.org/][Gimp]] were used to create various images/artwork
- [[http://www.gnu.org/software/freefont/][Gnu Free Fonts]], specifically *FreeMono* is used as main font
- [[http://www.gnu.org/software/emacs/][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 ([[https://www.gnu.org/licenses/gpl.html][GPLv3]], [[http://creativecommons.org/licenses/by-nc-sa/4.0/][Creative Commons BY-NC-SA License]], and [[http://creativecommons.org/licenses/by-nc-nd/4.0/][Creative Commons BY-NC-ND
License]]) are deployed dependent on which part of the site is in question. Please see the
[[./LICENSE][LICENSE]] file for full details.

* TODO Guix Development Environment
:PROPERTIES:
:header-args:  :session *vterm blog-rekahsoft-ca* :results none
:END:

[[https://guix.gnu.org/][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][channels.scm]] :: Specifically defines a set of available software, their versions and their build recipe.
- [[./guix.scm][guix.scm]] :: Defines the package for this site, ~blog-rekahsoft-ca~.
- [[./manifest.scm][manifest.scm]] :: Defines packages required for development of this site.

#+begin_src sh
  guix time-machine -C channels.scm -- shell -CN -E LANG -E TERM -E PS1 -Df guix.scm -m manifest.scm
#+end_src

This uses the [[info:guix#Invoking guix time-machine][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 [[info:guix#Invoking guix shell][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

#+begin_src sh
  site build
#+end_src

** Clean Site

#+begin_src sh
  site clean
#+end_src

** Watch

#+begin_src sh
  site watch
#+end_src

** Deploy Site

#+begin_src sh
  site deploy
#+end_src

** Test

#+begin_src sh
  site test
#+end_src

* Writing a Blog Post

#+begin_src sh
  guix time-machine -C channels.scm -- shell -CN -E LANG
#+end_src

* 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:

#+begin_src shell
  cd infra
  terraform workspace select production
  terraform plan --var-file=production.tfvars --out local.plan
  terraform apply local.plan
#+end_src

* Known Issues

If you have an issue while browsing [[http://www.blog.rekahsoft.ca][my blog]] please file a issue in the [[https://git.rekahsoft.ca/rekahsoft/blog-rekahsoft-ca/issues][blog-rekahsoft-ca]]
issue tracker.