233 lines
9.7 KiB
Org Mode
233 lines
9.7 KiB
Org Mode
#+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)]]
|
|
- 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]].
|