| .drone | ||
| clay | ||
| drafts | ||
| files | ||
| fonts | ||
| images | ||
| images-src | ||
| infra | ||
| js | ||
| lib | ||
| pages | ||
| posts | ||
| src | ||
| templates | ||
| .drone.jsonnet | ||
| .drone.yml | ||
| .gitignore | ||
| blog-rekahsoft-ca.cabal | ||
| channels.scm | ||
| guix.scm | ||
| LICENSE | ||
| README.org | ||
| robots.txt | ||
| Setup.hs | ||
| site | ||
| TODO.org | ||
Source Code for #! Lambda Slang
- Features
- Tools
- License
- Guix Development Environment
- Building a Release
- Writing a Blog Post
- Known Issues
#! Lambda Slang is the personal technical blog of Collin Doering, built using software that respects our freedoms.
Features
- 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:
- 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
- Gnu Guix is used to manage development environments and packaging
- 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
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 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
- Specifically defines a set of available software, their versions and their build recipe.
- guix.scm
- Defines the package for this site,
blog-rekahsoft-ca.
To start a development environment, run the following:
guix time-machine -C channels.scm -- shell -CN -E '^LANG$' -E '^TERM$' -E '^PS1$' -f guix.scm -Df guix.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, -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
Gnu Guix is used, similar to in the 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
- Symlink to ../channels.scm to make the guix cli workflow nicer when
in the
infradirectory. 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, 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
- Defines packages required for deployment of this site
To start a deployment development environment, run the following:
cd infra
guix time-machine -C channels.scm -- shell -CN -E '^LANG$' -E '^TERM$' -E '^PS1$' -E '^AWS.*$'Composing Site Development and Deployment Environments
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.scmBuild 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.
site buildClean 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:
site cleanWatch
site watchDeploy 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
site deploySetup 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
make setup ENV=<env>
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.
make planDeploy the Site
Run a terraform apply to deploy to the selected environment.
make deployWorking 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
guix gc --list-dead | grep -e '^/gnu/store/.*-blog-rekahsoft-ca-.*' | xargs guix gc -DBuilding 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:
guix time-machine -C channels.scm -- build -f guix.scmThis will produce a guix package with the following three outputs:
-
out - The
blog-rekahsoft-casite builder andgencsscss generator binaries, as well assiteuser script -
site - A build of the website made with the site builder, etc.. in the
outoutput 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
guix time-machine -C channels.scm -- shell -CN -E LANG -E TERM -E PS1 -f guix.scm -- site watchKnown Issues
If you have an issue while browsing my blog please file a issue in the blog-rekahsoft-ca issue tracker.
To see a list of already known issues, see TODO.org.