Published on by Aluísio Augusto Silva Gonçalves.

(hello "world"); or: an incredible journey

Table of contents

I spent most of last week getting this blog up and running. Inspired by Deploying This Site with IPFS and Scheme I set out (for the nth time) to create someplace I could eventually publish my writings on (and incidentally serve as a hub for my web presence). The result of that work is now available on sourcehut.

Shining a spotlight

The first step was getting Haunt, a static site generator written for Guile, GNU’s implementation of the Scheme language. As of today, it is not widely packaged: according to Repology, only the AUR, Guix, and pkgsrc have it. Since that intersects with exactly zero of the systems I’m currently using, I ended up packaging it (and its dependency guile-commonmark) for Nix, and intend to upstream it to Nixpkgs at some point.

The major difficulty I had during this part was making the build system install the files where I needed them to be. Nixpkgs sets up a very specific load path for Guile, and the autoconf script used by both Haunt and guile-commonmark don’t offer any way to override those, asking Guile directly instead. I worked around it by overriding the directory variables when invoking make.

Amateurish professionalism

Now that I could build a site, I just needed one. I started out borrowing from David Thompson’s and Elais Player’s configs, although the only survivors seem to be first-paragraph and the static page pattern. For styling, I wanted to try one of the many drop-in CSS stylesheets around, and experimented with Water.css before settling on Classless.css because of its navigation bar (which you see at the top of the site).

Next, I spent a solid few hours wandering about the Creative Commons website and iterating on the phrasing of the site’s licenses (code snippets are public domain, everything else is CC-BY-SA, and possibly ISC for the source code). Somehow I found out the Creative Commons symbols are now part of Unicode, and Daniel Aleksandersen created a font that allows websites (and you!) to start using them immediately, without waiting for fonts to catch up. I used that font to put the important bits in the footer, and pushed the details under the rug.

Distributed web, concentrated frustration

Building the site on builds.sr.ht, with Nix’s help, was quite fun – it is my first chance to set up CI on a project! (Except it doesn’t have any tests.) Making the very last build step – publishing to IPFS – work, however, brought out quite the opposite sentiment.

Since I already run an IPFS node, I wanted to send the built website to it rather than rely on a(nother) third-party service. Guessing that a mechanism to do that would already be available for GitHub Actions, I found one that led me to IPFS Cluster, a daemon that coordinates pins among IPFS nodes (which would let me easily pin files from my desktop on my public server) and, more relevant to the task, provides an authenticated HTTP API.

After finding myself having to create new packages (this time for FreeBSD), came the time to configure IPFS Cluster. My original plan was to proxy the HTTP API through Caddy, placing in on a subpath of my IPFS gateway (i.e. https://ipfs.aasg.name/cluster), but it turns out that Multiaddrs (the format IPFS uses for Internet addresses) can’t yet represent HTTP resources, so instead I just let the daemon handle connections directly on a different port.

Most of my frustration at this stage stemmed from what seems like a lack of integration between the IPFS subprojects. For instance, ipfs-cluster-ctl add does not support the --dereference-args flag added to go-ipfs over a year ago. Nor does the IPFS proxy API provided by Cluster work out of the box with IPFS Companion or IPFS Desktop.

All in all, getting everything ready for automated publishing took me most of a day. It is still not complete, however: since IPFS Cluster still doesn’t publish IPNS names, updating the site viewers get at the main domain will require a webhook from sourcehut’s end.

View comments to this post or send your own