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-public/blog-rekahsoft-ca"><img src="https://ci.home.rekahsoft.ca/api/badges/rekahsoft-public/blog-rekahsoft-ca/status.svg?ref=refs/heads/master" 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)]]
- Write blog posts and pages in markdown
- Support for math markup via MathJax
- RSS/Atom feed

* 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
- [[https://guix.gnu.org/][Gnu Guix]] is used to manage development environments and packaging
- [[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/][Gnu Guix]] is used to package this project and manage its dependencies, as well as to provide
reproducible development environments.

A simple wrapper script [[./site][site]] is provided that wraps the hakyll powered site builder to
offer some additional functionality.

** 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~.

To start a development environment, run the following:

#+begin_src sh
  guix time-machine -C channels.scm -- shell -CN -E '^LANG$' -E '^TERM$' -E '^PS1$' -f guix.scm -Df guix.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, ~-f guix.scm~ loads the
~blog-rekahsoft-ca~ package, and ~-Df guix.scm~ indicates that development dependencies of
the ~blog-rekahsoft-ca~ package should be included in the environment.

*** Deployment Development Environment

[[https://guix.gnu.org/][Gnu Guix]] is used, similar to in the [[*Start Development Environment][previous section]], to create environments with all tools
necessary for deployments, with a notable difference being a ~guix.scm~ file is not provided
or needed, as the deployment environment is used solely for its side effects. 

- [[./infra/channels.scm][infra/channels.scm]] :: Symlink to [[./channels.scm][../channels.scm]] to make the guix cli workflow nicer when
  in the ~infra~ directory. Technically this doesn't need to be a symlink, and could be a
  different set of channels or version of channels compared to the channels file at the
  top-level of the repository, however this would complicate [[*Composing Site Development and Deployment Environments][Composing Site Development and
  Deployment Environments]], so its preferred that all guix environments for the project,
  including the development and deployment environment use the same set of Guix channels.
- [[./infra/manifest.scm][infra/manifest.scm]] :: Defines packages required for deployment of this site

To start a deployment development environment, run the following:

#+begin_src sh
  cd infra
  guix time-machine -C channels.scm -- shell -CN -E '^LANG$' -E '^TERM$' -E '^PS1$' -E '^AWS.*$'
#+end_src

*** Composing Site Development and Deployment Environments

#+begin_src sh
  guix time-machine -C channels.scm -- shell -CN -E '^LANG$' -E '^TERM$' -E '^PS1$' -E '^AWS.*$' -f guix.scm -Df guix.scm -m infra/manifest.scm
#+end_src

** Build Site

This website is built from a collection of markdown files and templates that are processed by
pandoc and are stitched together using Hakyll. To build the html/css/jss and all other assets
required to deploy and distribute the site, the hakyll derived site-builder,
~blog-rekahsoft-ca~ must be invoked. Under usual conditions it is not invoked directly, but
instead via the ~site~ wrapper script. For example, this is how within a development
environment the site can be built.

#+begin_src sh
  site build
#+end_src

** Clean Site

[[*Build Site][Building the site]] has the side effect of writing a couple files/directories to disk as a
result of the build process. In some cases, its useful to start of with a clean slate and
remove any files that were generated for the site. To so so, the ~clean~ sub-command can be
used:

#+begin_src sh
  site clean
#+end_src

** Watch

#+begin_src sh
  site watch
#+end_src

** Deploy Site

Terraform is used to deploy this site. Its configuration files are located in ~./infra~.

Under normal conditions, all deployments occur from my internal ci/cd system. This ensures
that the deployment process is reliable, repeatable and quick. However, in the case of both
development and emergency deployments, clear documentation surrounding the deployment process
is necessary.

*** TODO ~site deploy~ command

#+begin_src sh
  site deploy
#+end_src

*** Start [[*Deployment Development Environment][Deployment Development Environment]]
*** Setup a Particular Environment

Three environments (terraform workspaces) are currently available, including:

  - default    :: unused default terraform workspace
  - staging    :: https://www.blog.staging.rekahsoft.ca
  - production :: https://www.blog.rekahsoft.ca

#+begin_src sh
  make setup ENV=<env>
#+end_src

From this point onward, any ~make~ target run will operate on the selected environment,
unless its switched with the ~workspace~ or ~setup~ targets, or manually with ~terraform~.

*** See What Infrastructure Will Change

Run a terraform plan to see how the selected environments infrastructure will change.

#+begin_src sh
  make plan
#+end_src

*** Deploy the Site

Run a terraform apply to deploy to the selected environment.

#+begin_src sh
  make deploy
#+end_src

*** Working with Terraform Directly

Within a development environment, ~terraform~, its providers and all other dependencies are
available. As such, its possible to directly leverage ~terraform~ and its various operations.
This is particularly useful when debugging or adding make targets.

** Clean up Guix Store

#+begin_src sh
  guix gc --list-dead | grep -e '^/gnu/store/.*-blog-rekahsoft-ca-.*' | xargs guix gc -D
#+end_src

* Building a Release

The software built that itself builds this blog is released as a Guix package. It is
currently not, and is not ever expected to be distributed via a channel, as it provides
little benefit to anyone except myself, and is meant to operate along with stateful data,
including the site templates, content, pages, posts, etc..

To build a release, run the following command:

#+begin_src sh
  guix time-machine -C channels.scm -- build -f guix.scm
#+end_src

This will produce a guix package with the following three outputs:

- ~out~ :: The ~blog-rekahsoft-ca~ site builder and ~gencss~ css generator binaries, as well
   as ~site~ user script
- ~site~ :: A build of the website made with the site builder, etc.. in the ~out~ output of
  this package, using the content at the same version
- ~static~ :: License file and any other file that should be distributed (eg manual)

** TODO What is done with the release?
  
* Writing a Blog Post

#+begin_src sh
  guix time-machine -C channels.scm -- shell -CN -E LANG -E TERM -E PS1 -f guix.scm -- site watch
#+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.

To see a list of already known issues, see [[./TODO.org][TODO.org]].