There’s a level in the excellent first person stealth game Dishonored 2, where for various reasons, you need to break into the mansion of a certain Aramis Stilton. But this mansion is protected by a door, and this door is protected by a lock devised by the great inventor Kirin Jindosh.

The lock is no ordinary lock. There isn’t a keyhole; instead it’s effectively a combination lock.

There’s also an accompanying riddle, which gives clues to the combination:

The lock proves too complicated for lockpickers living in the game’s world; unfortunately, Jindosh didn’t account for assassins that have access to a Prolog interpreter.

The Setup

The puzzle is effectively a zebra puzzle; a logic puzzle where you’re given a set of facts, a set of constraints, and you’re supposed to unify to find a solution to the constraints.

In our case, there are five diners at the dinner party, and five properties that we care about for each diner: their name; the colour of their clothes; what they’re drinking; where they’re from; and what heirloom they’ve brought.

Additionally, we care about the order in which they’re sitting; we can model this as a list with exactly five elements. Prolog comes with syntactic sugar for lists, but in this case it’s a little easier to roll our own since we want lists of exactly 5 elements:

% exists(A, Xs) states that A is an element of Xs
exists(A, list(A, _, _, _, _)).
exists(A, list(_, A, _, _, _)).
exists(A, list(_, _, A, _, _)).
exists(A, list(_, _, _, A, _)).
exists(A, list(_, _, _, _, A)).

% leftOf(L, R, Xs) states that L and R are elements of Xs, and L appears directly to the left of R.
leftOf(L, R, list(L, R, _, _, _)).
leftOf(L, R, list(_, L, R, _, _)).
leftOf(L, R, list(_, _, L, R, _)).
leftOf(L, R, list(_, _, _, L, R)).

% first(A, Xs) states that A is the first element of Xs
first(A,  list(A, _, _, _, _)).
% second(A, Xs) states that A is the second element of Xs
second(A, list(_, A, _, _, _)).
% middle(A, Xs) states that A is the third (middle) element of Xs
middle(A, list(_, _, A, _, _)).

% If A is next to B, then either A is to the left of B, or B is to the left of A.
nextTo(A, B, Xs) :- leftOf(A, B, Xs).
nextTo(A, B, Xs) :- leftOf(B, A, Xs).

The above prediates are enough to encode the ordering constraints given in the puzzle. I’m also going to declare now that my prolog solution is in no way minimal!

The Puzzle

We’ll define the puzzle as a predicate called, fittingly, puzzle. The code for this will look as follows:

puzzle(Diners) :-
  constraint1,
  constraint2,
  ...
  constraintN-1,
  constraintN.

Note that this predicate is dependent on a metavariable called Diners. This will be the list of diners and their properties, and solving for puzzle(Diners) will give us our solution.

We’ll also need a consistent way to represent a diner. Since the position is encoded in the list, we only need to store the other five properties:

% Name, Colour, Drink, Town, Heirloom
diner(winslow, white, whiskey, dunwall, warMedal)

The exact constraints of the puzzle appear to be randomised on each playthrough, presumably to stop people from just sharing the solution online.

Let’s walk through the puzzle description from my playthrough piece by piece.

At the dinner party were Lady Winslow, Doctor Marcolla, Countess Contee, Madam Natsiou, and Baroness Finch.

This sentence simply states that there are five diners, and gives their names. We can translate this into prolog as follows:

exists(diner(winslow,  _, _, _, _), Diners),
exists(diner(marcolla, _, _, _, _), Diners),
exists(diner(contee,   _, _, _, _), Diners),
exists(diner(natsiou,  _, _, _, _), Diners),
exists(diner(finch,    _, _, _, _), Diners),

The underscores represent metavariables in the statement that we need to fill in via unification.

Next, we get the following paragraph:

The women sat in a row. They all wore different colors and Lady Winslow wore a jaunty blue hat. Madam Natsiou was at the far left, next to the guest wearing a purple jacket. The lady in red sat left of someone in green. I remember that red outfit because the woman spilled her whiskey all over it. The traveler from Karnaca was dressed entirely in white. When one of the dinner guests bragged about her Snuff Tin, the woman next to her said they were finer in Karnaca, where she lived.

Here’s the prolog version:

% Lady Winslow wore a jaunty blue hat.
exists(diner(winslow, blue, _, _, _), Diners),
% Madam Natsiou was at the far left,
first(diner(natsiou, _, _, _, _), Diners),
% next to the guest wearing a purple jacket.
second(diner(_, purple, _, _, _), Diners),
% The lady in red sat left of someone in green.
leftOf(diner(_, red, _, _, _), diner(_, green, _, _, _), Diners),
% I remember that red outfit because the woman spilled her whiskey all over it.
exists(diner(_, red, whiskey, _, _), Diners),
% The traveler from Karnaca was dressed entirely in white.
exists(diner(_, white, _, karnaca, _), Diners),
% When one of the dinner guests bragged about her Snuff Tin, the woman next to her said they were finer in Karnaca, where she lived.
nextTo(diner(_, _, _, _, snuffTin), diner(_, _, _, karnaca, _), Diners),

The next paragraph says:

So Baroness Finch showed off a prized Ring, at which the lady from Baleton scoffed, saying it was no match for her War Medal. Someone else carried a valuable Bird Pendant and when she saw it, the visitor from Fraeport next to her almost spilled her neighbor’s wine. Doctor Marcolla raised her rum in toast. The lady from Dunwall, full of beer, jumped up onto the table, falling onto the guest in the center seat, spilling the poor woman’s absinthe. Then Countess Contee captivated them all with a story about her wild youth in Dabokva.

In Prolog:

% So Baroness Finch showed off a prized Ring,
exists(diner(finch, _, _, _, ring), Diners),
% at which the lady from Baleton scoffed, saying it was no match for her War Medal.
exists(diner(_, _, _, baleton, warMedal), Diners),
% Someone else carried a valuable Bird Pendant
exists(diner(_, _, _, _, birdPendant), Diners),
% and when she saw it, the visitor from Fraeport next to her almost spilled her neighbor's wine.
nextTo(diner(_, _, _, fraeport, _), diner(_, _, wine, _, _), Diners),
% Doctor Marcolla raised her rum in toast.
exists(diner(marcolla, _, rum, _, _), Diners),
% The lady from Dunwall, full of beer,
exists(diner(_, _, beer, dunwall, _), Diners),
% jumped up onto the table, falling onto the guest in the center seat, spilling the poor woman's absinthe.
not(middle(diner(_, _, _, dunwall, _), Diners)),
middle(diner(_, _, absinthe, _, _), Diners),
% Then Countess Contee captivated them all with a story about her wild youth in Dabokva.
exists(diner(contee, _, _, dabovka, _), Diners),

Finally, we have a sentence that simply asserts the existence of four other heirlooms besides the ring.

In the morning, there were four heirlooms under the table: the Snuff Tin, Diamond, the War Medal, and the Bird Pendant.

Technically, the only one we haven’t seen yet is the diamond, but we’ll encode them all for completeness.

exists(diner(_, _, _, _, snuffTin), Diners),
exists(diner(_, _, _, _, diamond), Diners),
exists(diner(_, _, _, _, warMedal), Diners),
exists(diner(_, _, _, _, birdPendant), Diners).

With that, we’re done, there’s only one more sentence to deal with:

But who owned each?

We can evaluate the following:

puzzle(Diners)

Which spits out this:

list(
diner(natsiou,white,wine,karnaca,birdPendant),
diner(marcolla,purple,rum,fraeport,snuffTin),
diner(winslow,blue,absinthe,baleton,warMedal),
diner(contee,red,whiskey,dabovka,diamond),
diner(finch,green,beer,dunwall,ring)
)

list(
diner(natsiou,white,wine,karnaca,diamond),
diner(marcolla,purple,rum,fraeport,snuffTin),
diner(winslow,blue,absinthe,baleton,warMedal),
diner(contee,red,whiskey,dabovka,birdPendant),
diner(finch,green,beer,dunwall,ring)
)

Two answers? I feel I must be missing a clue in the text, but I’ve scoured it and can’t find where it may be. A few other people have had the same idea as me to use Prolog to solve this puzzle, and some of their solutions also produce two answers. I wonder if this is an issue with the constraint randomisation or if there’s a subtlety in the wording that multiple people have missed.

Conclusion

You can find the complete file in a SWI-Prolog session here.

Once you’ve put in the solution to the puzzle into the lock, the door opens, and if you go through it, the level ends. You encounter the door at the beginning of the level, and you’re supposed to go through a whole side quest dealing with a gang war to get the door open, but I find it very funny that you can skip the whole thing if you know a bit of predicate logic.

Look! Zero kills and zero detections, and it only took three hours (after trying to unify by hand for a while). So convenient!

Welcome! This page gives a rough description of my personal computing stack.

I’ve seen a few people around the web with a page similar to this one, and I thought I’d try my hand at it too. I’ve added a rating to each item, and a brief sentence trying to give my overall thoughts about it. You’ll notice most of the ratings are 4 or 5 out of 5; generally if something is lower than that, it won’t make it into regular use!

Hardware

Main Devices

Framework 13 AMD

5/5 - It just feels dependable.

At the start of 2024, I bought a Framework 13 AMD, which had just released. This was to replace my previous laptop, an XPS 13 7390 2-in-1. That machine was lovely in most aspects, but I was constantly running low on RAM, and the webcam and fingerprint sensors didn’t have driver support on Linux. The Framework, of course, has perfect Linux support, and given the whole gimmick of the device is to be upgradeable, being stuck on 8GB of RAM will not be an issue. I’m also in the process of replacing my desktop with this, since it gets roughly the same performance!

reMarkable 2

5/5 - Invaluable for research

The reMarkable has fully replaced paper for me. I got it for ~£170 including the pen from a friend who no longer needed it. That’s an absolute bargain, and knowing how much I like using it, I’d probably buy one full price.

It’s sleek, responsive (or as responsive as e-ink can be), and very light; only weighing 400g, it’s lighter than the notebook I used to carry. Reading PDFs on it is a dream, and the writing experience is the best out there; the feel is roughly similar to a ballpoint pen on paper. In this regard, it is way better than any other tablet I’ve tried, even with a paper-like screen protector.

POCO X4 Pro 5G

4/5 - Does the job, plenty of alternatives available.

This is a very cheap Android phone for its specifications: 120Hz screen; decent battery; okay camera quality; and a lovely blue colour. It even comes with an IR blaster of all things! I managed to get it for only £160 in total. I’m not someone who wants to be using their phone all that much, so it does the job for me. As a bonus, it comes with a compact 67W USB-C power delivery charger, which is insane, and conveniently enough to charge my laptop from. By this point I use USB-C exclusively (save for my watch) to charge things, so a high-quality charger included for free is a very welcome surprise.

Topton R1 Pro

5/5 - A very good deal, and a NAS works so much better for me than a desktop.

This is a cute two bay NAS enclosure with an Intel N100-based motherboard I recently picked up. As mentioned above, I’m trying to get rid of my desktop computer, primarily because it draws a lot of power for the amount I use it these days. However, there’s a bunch of small services I run on it, and I’d rather not run them on a VPS since they contain sensitive personal information. This thing only draws around 25W when my drives are being accessed, compared to the 100W my PC drew.

It was about £200 in total (including 16GB of RAM), which is a very good price for an entry-level NAS. I already had the storage from my old desktop; a 512gb 7Gbps NVMe SSD for the boot drive, and two 3.5 inch HDDs (8TB and 1TB). I run Proxmox on it. You can see which services I’m running in the software section.

Peripherals

Logitech Pebble

4/5 - Beats a touchpad

This is a pretty uncomfortable mouse to use for long periods of time. Luckily, that’s not what I bought it for; this is for when I need to do some work that would be annoying on a touchpad, but I don’t want to have to lug a full mouse around.

Its design is surprisingly clever, ignoring the lack of ergonomics; the USB receiver and (AA) battery are hidden underneath the top of the mouse, which is held in place magnetically against some standard screws - a very smart solution! It’s got a nice button that toggles between the USB receiver and Bluetooth for connectivity, which is handy if you need to switch between two devices frequently.

Between Pro

5/5 - Although they have a newer model that’s presumably better

These true wireless earbuds are great: they’re very comfortable; last for absolutely ages on a single charge; never fall out; block out most environmental noise even without ANC; and sound amazing. The box is fairly bulky compared to e.g. AirPods, but Edinburgh weather tends to force you to wear a jacket, so it’s not that big of a deal for me. I use them daily to listen to music when walking around or shopping, and also during work calls. The mic quality is average I’d say; I think you always end up with worse quality mic audio on these sorts of earphones since the mics are nowhere near your mouth.

If I were looking to buy some of these today, Status Audio have a newer model out that has ANC and an app, which I presume is probably better.

Status Audio Flagship ANC

5/5 - Great sound for the price.

Given how much I liked the Between Pros, I ended up snagging a pair of Flagship ANCs, also by Status Audio. They’ve got good sound and battery life, with a generally convenient touch surface on the right ear to control your music. They’re great for focusing in a co-working environment. I think they’ve been discontinued, which is a shame; the noise cancelling is really good, and the cheaper replacement model doesn’t have the same system.

One really important feature about these for me is that, while they are primarily wireless headphones, you can connect an aux cable to them with zero latency - you’d be shocked at how many Bluetooth devices have a 6-700ms delay even when using wires! Because of this, I find it super convenient to use these with my synths if I want to play later at night.

Yubico Security Key

5/5 - Can’t complain, it beats SMS any day.

For 2FA, I’ve been making use of this thing. Note that it isn’t a Yubikey proper! It only does FIDO U2F, but that’s enough for me; I’m not encrypting many emails.

Smart Devices

Emporio Armani Connected Gen 2 Smartwatch

4/5 - Looks very nice for a smartwatch

I received this smartwatch as a gift. It’s a really nice design for a smartwatch; very far from the silicon straps and circular edges of the Apple and Pixel watches. Unfortunately, it runs Wear OS, which is somehow an even worse version of Android than all the other versions of Android. Its battery life doesn’t last a day, and its app support is now limited, given its age. Still, as a day-to-day watch, it looks nice, and keeps track of my activity pretty well.

Smart lights

5/5 - Assuming you have Home Assistant.

These things are great. I have Home Assistant set up to turn them on alongside my alarm, and turn them off when I start sleep tracking or leave the house. They also adjust their colour temperature and brightness throughout the day.

Renpho Smart Scales

4/5 - Pretty much the same price as regular scales but they do way more.

Since I’m trying to get a better understanding of my health, I thought smart scales were a decent option to get started. There’s a bunch of different models that Renpho sells, and I’m not sure what the differences are between them; I just picked my one based on aesthetics. They can connect over Bluetooth or Wi-Fi to an app, which will then show you:

• Your weight
• Your body fat percentage, broken down into visceral and subcutaneous
• Your muscle mass
• Your BMI and “metabolic age” (who cares)
• And several more which I don’t bother checking

They’re good, but I do question the 11.5% body fat they give me. Mostly, I end up just caring about the trend lines.

Wanbo T2 Max

3/5 - Software is terrible, but it’s cheap!

This was the cheapest true 1080p projector I could find. It runs a very laggy version of Android 6, but I think newer models have a much more powerful CPU and a newer Android version. I generally only use this to connect other devices through HDMI. Given that, as a student, my housing is pretty non-permanent, this is a lot more transportable than a TV (it is tiny), and gives a much bigger image. Plus, projectors are just more fun.

I’d definitely recommend having a projector, but probably not this one.

Software

NixOS

The main reason I use NixOS is it lets me keep my system configs all in one place. When I switched to my Framework, it took me 5 minutes (excluding time taken to download files) to get it set up the exact way I had my old laptop set up, and I was immediately able to be productive on it.

It’s also nice being able to revert to a previous build of my system if something breaks and I don’t have time to fix it.

Emacs

I use Emacs mostly out of a lack of choice. There aren’t really any other editors that have support for the languages I usually write. That being said, I do enjoy the customisability you can get with it.

Firefox

I use Firefox as my main browser, with Sideberry to give a vertical tree structure to my tabs (of which I usually have around 50 open at any given time).

Filesystem Structure

I have a rather unorthodox home directory.

At its core, my filesystem structure has two main folders:

~/docs

Permanent, synched storage for my work and important files.

~/inbox

Effectively a downloads folder. It’s shown on my desktop by default, to discourage building up too many files. The downloads folder on my phone is also synched here to make it easy to copy files between devices.

Synching is accomplished via Syncthing. Large media (photos, videos, etc.) is kept on my NAS, not locally. I find this system really helps me keep on top of my files; generally I know exactly where everything important to me is saved. Keeping all my important files in one folder makes backups simple too.

Personal Finance

I have a very complicated setup for managing my personal finances. It’s based around hledger and Observable notebooks, to provide an overview of my spending and saving across multiple accounts all in one place. It’s a little janky, and took an age to set up; I wouldn’t recommend this exact setup for people to use, but I certainly would recommend they look into something similar like YNAB.

Services

Immich

Good alternative to Google Photos. I used to use photoprism, but Immich is generally faster.

Jellyfin

A great replacement for streaming service paralysis.

Tailscale

Invaluable; I no longer need to worry about port forwarding and secure auth to access my devices remotely.

VS Code Server

I keep this running in a scratch container for writing quick scripts. Very handy!

Other tools

Here’s a bunch of small utilities I use that don’t deserve their own subsection.

Warp terminal

It recently dropped for Linux, and it’s a vastly better experience than any other terminal emulator.

Fun

Cardputer

5/5 - I can’t describe how much I love this.

This thing is probably my favourite piece of technology that I own.

It’s £30, the same dimensions as a credit card (albeit with a depth of about a centimetre), and has:

• An ESP-32 as its main source of computation
• Wi-Fi and Bluetooth connectivity (as a result of the ESP-32)
• A tiny LCD
• A tiny keyboard
• A speaker and microphone
• An IR blaster
• A battery backpack, as well as a small internal battery
• A micro SD card slot
• An exposed 4-pin connector that speaks I2C
• Some pretty strong magnets
• LEGO headers

It’s so much fun to play around with. Being effectively a normal ESP-32 with a bunch of pre-connected peripherals, you can program this device from the Arduino IDE. I’ve loaded a custom Forth interpreter on it that can read programs from the SD card, to get around memory restrictions of the device itself. I actually use this thing in my daily life as a pomodoro timer; the magnets make it easy to prop up against metallic objects, and the simplicity of the device means you can’t really get distracted with it (Of course, you can easily distract yourself programming it).

Synths

Behringer DeepMind 6

5/5 - Very fun synth to use!

This hardware, analogue synth has six voices of polyphony and sliders all over it. It’s an absolute blast to play with!

UNO Synth

5/5 - A nice portable monosynth!

This was the first synthesizer I ever bought. It’s got a very strong analogue sound engine for something of this size and budget, and as such I still use it frequently for basslines alongside the DeepMind 6. This use case is actually aided by the capacitive touch pads; they make it very easy to slide between notes.

It’s portability is unmatched; it’s a little bit taller than an A5 piece of paper, can run on either AA batteries or a USB power supply (and thus a USB power bank), and weighs barely anything. You can use MIDI either over USB, or via a MIDI-to-2.5mm jack adaptor provided.

The main downside in my opinion is that the sequencer is only 16 steps; the UNO Drum below has 64 steps and the ability to program “songs” as a list of sequences to go beyond that. As a result, I generally either play this manually or just play a pre-written bassline over MIDI.

UNO Drum

5/5 - Great little drum machine

This obviously pairs well with the UNO Synth above, and has many of the same portability features. It’s partially analogue, but mainly digital, and allows uploading of custom sample sounds over USB.

One nice feature is the line in port; this is routed through the effects engine, meaning you can use it as a compressor in a pinch.

This post acts as a simple note-to-self on how to install Pack, the primary package manager for Idris 2, on NixOS.

The Idris community currently doesn’t overlap much with the Nix community. Ignoring a basic nixpkgs entry for the compiler itself, and editor plugins for Vim and Emacs, there is nothing packaged for Idris 2 at all.

The primary package manager that has arisen is Stefan Hoeck’s Pack. It follows a Stack-like model, but the main thing that we care about is it’s what the community has settled on. Most libraries that have been written for Idris 2 can be installed through Pack, and it can even manage the version of the Idris 2 compiler¹ itself!

So Pack is a pretty indispensible tool for the Idris 2 programmer. How can we use it on NixOS?

The Pack repo offers a simple command to install it to the current user’s home directory on a standard Linux system.

bash -c "$(curl -fsSL https://raw.githubusercontent.com/stefan-hoeck/idris2-pack/main/install.bash)"

But NixOS is no standard Linux system.

The first hurdle is the shebang at the start of the file. Trying to run this command as-is can return:

bash: line 1: #!/usr/bin/env: No such file or directory

This can be fixed by downloading the file and running it directly with bash install.bash.

Then, the script may complain about missing dependencies such as git or make². These can simply be installed system-wide, or you can enter a shell that provides them.

Finally, when trying to compile the RefC backend, the script may complain about not being able to access the C headers for GMP. This can’t be solved by installing the gmp package globally, due to the nature of NixOS. The quickest way around this is to enter a Nix shell that exposes the package to the linker:

nix-shell -p bash gcc gmp gnumake

The above command will expose all the needed dependencies. From here, you should be able to install Pack as normal.

Ideally, a nixpkgs derivation would be made that does all of this, but I’m not experienced enough with writing Nix packages to do this myself. Maybe some day in the future.

TL;DR: My site can be browsed over Org mode! Go to Emacs Setup to see how.

I wrote in my last post about how my blog posts are written in Org mode. It’s a nice format for writing this sort of thing, with built in support for heading structure, links, images, and much more. It’s also nice for reading, as you can collapse sections, use your favourite Emacs focus package¹ for greater comfort, and even link directly to sections from your own Org notes. If you’re reading a technical post, you can even execute code blocks from within the post!

This got me thinking.

Since Org provides such a nice reading environment, why not also serve my site’s content over Org? Hakyll, the site generator I use, makes this straightforward, as I can just tell it to serve the same Org files I write my posts in. Surely Emacs is flexible enough to allow this?

The Emacs Side

It turns out, as always, that it is. There’s a built-in mode called url-handler-mode that lets us treat remote files as if they’re local. This works by wrapping the Emacs file handling primitives, which means it affects any function that tries to load a file. Crucially, this includes Org links, so we can link to remote pages and have them download and open entirely with Emacs.

By default, Org won’t download images and render them inline, even if you have inline images enabled by default. Luckily, the variable org-display-remote-inline-images lets us control this behaviour. You can choose to skip files (the default), download them every time, or cache them whenever the remote file is updated. I recommend the latter.

It’s also a good idea to set org-image-actual-width to nil, which allows the use of a #+ATTR_ORG tag to set the width of an image. I use this to make images smaller to minimise the effect of Emacs’ awful image handling².

With this, we have pretty much everything we need on the client.

The Hakyll Side

Hakyll is actually a bit finicky when dealing with Org input. It requires a yaml heading with variables for templating purposes, like this:

---
title: This is the title of my amazing blog post
author: Tim Smith
description: A stitch in time saves nine in time, but that's the way we all go.
---
Welcome to my post! Today, we'll be…

It’s possible to define a pandoc compiler that allows you to specify these with the standard Org headers for the title and author, but I use these tags for a few purposes that aren’t supported by the Org headers, so it’s easier to keep using the Hakyll header. Luckily for us, we can strip it away easily using getResourceBody. We can then fill in the standard Org headers using a template. I made one that also has header links, like the HTML version of my site.

We do still need to produce Org files as output. This basically consists of defining additional matchers for each fie we want to generate, and applying the Org compiler and templates instead of the HTML ones. Hakyll’s version tags make this really easy to do.

Homepage

With this, everything works pretty much flawlessly, except for the homepage. When we access https://jacobwalte.rs in a browser, it knows to automatically access /index.html. Org, not being built for this, doesn’t. Forcing the user to remember to add /index.org is really bad UX, so we need to find some way to automatically redirect Emacs traffic to that page.

Luckily, Emacs has its own user agent! When we browse a site (through url-handler-mode or an Emacs browser like w3), we use something like URL/Emacs Emacs/30.0.50 (PureGTK; x86_64-pc-linux-gnu) as our user agent. You can check yours by connecting to https://ifconfig.me/ua. So if we check against the user agent, we can automatically redirect to the Org file.

Caddy (the webserver I use) can do this easily, with the following rule:

@emacs-ua {
  header User-Agent *Emacs*
  path /
}
redir @emacs-ua /index.org

This redirects any Emacs traffic from https://jacobwalte.rs/ to https://jacobwalte.rs/index.org. It’s important that we filter for the root path, as otherwise any file we try to access would bring us to the index page!

This nearly works. Unfortunately, Emacs has no way to tell this is an Org file. The way I got around this was by adding a mode descriptor line to the homepage (and the homepage only):

-*- mode: org -*-
#+title: jacobwalte.rs
…

This tells Emacs to use Org for that particular file. With that, everything is ready to go!

Emacs Setup

To browse my site over Emacs, simply add the following to your config:

(url-handler-mode)
(setq org-display-remote-inline-images 'cache)
(setq org-image-actual-width nil)

You can read the full post for an explanation of how these work.

The second and third lines are optional, but basically allow Org to display inline and resized images.

Now, all you have to do is run find-file (that’s C-x C-f in vanilla Emacs, or SPC . in DOOM), and navigate to https://jacobwalte.rs. You should now see my homepage, rendered in beautiful high-fidelity Org!

This is how I build and host my site. If you want to look through the code while reading, it can be found here.

Laziness is perhaps one of Haskell’s most prominent features, and I’ve really taken that philosophy to heart. I want my software to work with as little user input as possible (once set up), preferably none. With a website, this means I want to be able to just write a blog post, upload that file somewhere, and have it appear on my site. There’s plenty of sites and companies that provide this directly, but they tend not to offer you much control. I already rent a VPS (to run personal services on for me and my friends), so why not use that to host my site?

Hakyll

Another famous aspect of Haskell is over-engineering simple things. It’s for this reason I chose to use Hakyll, a static site generator written entirely in Haskell, to achieve the previous paragraph’s goals. Hakyll makes use of the fact that pandoc is also written in Haskell, and can be used effectively as a library, to convert files into HTML. This means that I can write my pages in whatever format I like, which is nice, but I can also use pandoc plugins¹ to alter my page generation.

As far as formats go, I like Org mode. It’s built into Emacs, my text editor, and has a straightforward syntax (it’s similar to Markdown). The reason I use it over Markdown is that Emacs has a lot of extra support for Org mode, allowing you to do things like manipulate headings and content easily, execute code blocks, and lots more. Since Emacs is infinitely extensible, you can implement whatever feature you want and have it be integrated automatically with the entire Org ecosystem. I already have an advanced Org setup for writing course notes, so why not adopt that for my blog posts too?

The process of using Hakyll is straight forward. It reads in some input files, applies templates to them (thing like HTML boilerplate, and text substitution for dates, page titles etc), and spits out a folder with your generated HTML. You can then point your favourite web server to these files and serve them directly! It certainly satisfies the laziness requirement.

Footnotes and Sidenotes

You may have noticed that note on the side three paragraphs ago. I really like this form of literal marginalia, as it saves you from having to jump around the document to find information, and uses screen space better on our modern widescreen devices.

There’s a package that already implements this for us, that works with the CSS I use! This makes things really easy, I just add that to my stack.yaml and add it to the pandoc compiler in Hakyll.

Annoyingly, however, Org implements its footnotes as a heading at the end of the file. The contents of this are removed, but the footnote heading stays! This means it still gets rendered in the HTML, which is quite ugly. Luckily, we can define our own pandoc compiler:

removeFootnotesHeader :: Pandoc -> Pandoc
removeFootnotesHeader = walk $ \inline -> case inline of
    Header 1 ("footnotes", [], []) _ -> Null
    _                                -> inline

This will filter out the bogus heading.

Links

For some reason, Org links to other pages on the site don’t get converted to HTML correctly. We can just define another compiler plugin to fix this:

convertOrgLinks :: Pandoc -> Pandoc
convertOrgLinks = walk $ \inline -> case inline of
    Link attr inline (url, title) -> Link attr inline (pack (orgRegex (unpack url)), title)
    _                             -> inline
  where
    orgRegex :: String -> String
    orgRegex str = subRegex (mkRegex "^(.*?)\\.org$") str "\\1.html" 

This code was originally from here.

Headings

Pandoc, by default, will convert Org headings directly to HTML headings. That is to say, * becomes <h1>, ** becomes <h2>, etc. However, we’re already using <h1> for our title! We need to lower the heading depths somehow.

Hakyll provides a function to do this, called demoteHeaders. However, its type is String -> String, which can’t be directly applied in a compiler. So we need to map it:

comp :: Compiler (Item String)
comp = fmap demoteHeaders <$> pandocCompiler

This gets us what we want. Importantly, we’re running the compiler before adding the template; if we ran it after, we’d demote the heading of our title too!

Caddy

So what is my favourite web server? I’ve become a fan of Caddy, largely because of how incredibly easy it is to use over something like nginx. To serve files from a directory, all you have to have in your config is this:

jacobwalte.rs {
  encode zstd gzip
  root * /srv/http/
  file_server
}

These few lines will serve your site over ports 80 and 443, with HTTPS already set up for you! This is genuinely all you need to host a personal site. You don’t even need the encode line, that just helps to speed up page loads slightly. It really is this simple!

Error Page

It’s handy to let users know if they’ve followed a broken link somewhere. Caddy allows us to redirect requests with non-200 HTTP codes to a specific page, and we can use this to provide a 404 page:

handle_errors {
  @404 {
    expression {http.error.status_code} == 404
  }
  rewrite @404 /404.html
  file_server
}

NixOS

The main benefit I reap from NixOS is the declarative configuration. This means I can keep my server’s entire configuration in one file², which makes it very easy to keep on top of things. Furthermore, if I’m making a large change to my configuration, it keeps the old one around. If something breaks, I can simply roll back.

NixOS has support for configuring Caddy directly, which is nice. The config looks something like this:

services.caddy = {
  enable = true;
  virtualHosts."jacobwalte.rs" = {
    serverAliases = [ "www.jacobwalte.rs" ];
    extraConfig = ''
      encode zstd gzip
      ...
    '';
  };
}

networking.firewall.allowedTCPPorts = [ 80 443 ];

Basically the same as the default Caddy file, but it means less to back up.

Deployment

With the setup so far, every time I make an update to my site, I have to push the change to GitHub, ssh into my VPS, su into my deploy user, cd into the repo, git pull, and finally make. This is slow!

What I really need is CI/CD. This allows me to make the change on my local device, push to GitHub, and have GitHub automatically do the rest for me. Conveniently, they provide an integrated service for this, called GitHub Actions. This lets us spin up a container, build our site, and then scp it over to my VPS.

GitHub actions are made by placing a yaml file in .github/workflows/ in your repo. You can do this through the UI too. I find it easiest to write these by stealing other’s, so here’s mine to get you started.

Caching

If we change our site.hs, we obviously need to rebuild it in order to reflect the changes in our output HTML. This means we need to run stack run site build again, which is fairly quick if we’ve already built all of Hakyll’s dependencies.

However, presumably for various reasons, GitHub does not preserve your container once it’s run its course. This is bad news for us Haskell enjoyers, because Haskell builds tend to be big. A clean ~/.stack for my site totals just over one gigabyte,³ and that’s after compiling! An uncached build takes around 35 minutes on GitHub’s machines, which is quite dreadful if you’re just making a small grammatical change. Since the container gets wiped after the build is complete, we’d hit this 35 minute build time on every change!

Thus, it’s important we add caching to our action. We can use the official GitHub caching action to achieve this:

- name: Cache stack folder
  uses: actions/cache@v3
  with:
    path: ~/.stack
    key: ${{ hashFiles('stack.yaml') }}

This means our ~/.stack will be cached by the hash of our stack.yaml, so if this file is untouched, we’ll reuse the already built workdir. This takes roughly 45s to happen, as the runner now needs to download 1GB of stack files, but it’s a big improvement over 35 minutes! If we update stack.yaml (by e.g. adding a new dependency, or updating GHC), it will start anew.

It’s worth remembering also that GitHub will only keep your caches around for a week, so if you don’t make any changes for a while, you’ll once again hit that 35 minute build time. There’s no real way around this, but you could just run builds on the deployment server itself, using one of the SSH actions.

One final thing to remember is that caching installs two actions, one that runs at the beginning (to check if we hit or miss the cache), and one at the end (to update the cache if necessary). If your build fails in the deployment phase, your cache won’t be written to! So make sure everything works downstream before wasting 35 minutes of your life, like I did.

Building and Deploying

Building is thankfully very straightforward. All you need to run Hakyll is this:

- name: Build Site
  run: |
    cd ${{ github.workspace }}
    make build

(Assuming make build does what you’d expect)

Once built, our HTML is probably in _site/, so we need to copy the contents of that folder to our VPS. There are many ways of doing this, but I chose SCP, since it’s very straightforward. In particular, I chose this action, as it can empty the target directory before copying, which is what we want:

- name: Deploy over SSH
      uses: appleboy/scp-action@v0.1.4
      with:
        host: ${{ secrets.HOST }}
        username: ${{ secrets.USERNAME }}
        key: ${{ secrets.KEY }}
        source: "_site/*"
        target: ${{ secrets.DEPLOY_DIR }}
        rm: true

You need to set up your secrets, through the Settings page for your repo. This is straightforward, you just put the string values in. For the SSH key, I recommend making a dedicated one for each repo (with the standard ssh-keygen), dropping the private key into the KEY secret, and installing the public key as normal. On NixOS, that can be done as follows:

users.users.deploy = {
  openssh.authorizedKeys.keys = [ "ssh-rsa AAAA..." ];
}

This should be it! Your site should now automatically be deployed whenever you commit.