Thomas Letan's Blog - meta

What happened in February 2026?

March 8, 2026

What happened in February 2026?

Time flies. February was a productive month, and I got many things done—with the help of my coding assistant , that is. I haven’t joined the “I haven’t written a single line of code for quite some time” flock just yet, but I am close. At the same time, I feel like I’m still locked in beginner mode. Like I have still to really tap into what agentic tools like Claude Code have to offer.

For now, the tools may have changed, but the journeys feel somewhat the same as they used to a few months back. It’s a strange feeling, and I am still trying to wrap my head around it.

Yet Another Claude Code Wrapper

In my previous retrospective, I mentioned CeCe and Vee. The former is a plugin for turning Anthropic’s model into a “modal” agent that I had vibe “prompted” with Claude itself. The latter was a second take at the exact same concept.

A month later, Vee has evolved quite a bit, to a point where the “modal” aspect of the project lost the front seat. More precisely, Vee has become a session multiplexer for Claude Code, with built-in support for spawning it in ephemeral containers with --dangerously-skip-permissions enabled. It is also a playground for me to experiment with the agent. For instance, I built a feedback system where I can point it to the good and bad things it’s doing—my feedbacks get saved in a SQLite database and appended in the system prompt during the next sessions. I’ve also tried to set up a knowledge base with embeddings. Both approaches have their benefits, but I don’t think I have clear evidence that they can be a game changer.

You may remember Vee started out of my frustration to losing control of CeCe’s internals. Well, Claude Code took over Vee’s codebase quite quickly as well. But this time, the output was a lot more satisfying. This time, I leaned into playing the role of a Tech Lead and a QA tester. Seeing the project taking shape and the tool I wanted becoming a reality that quickly has clear upsides. I also find it interesting that I have both a fairly good understanding of how the software works overall—I called most of the architectural choices—and very little insight on how the code itself is written. It reminds me of $WORK, where I am involved in some projects without being a direct IC.

I Built Myself a Cloudlab

In the first half of the month, a colleague of mine was tasked with building “staging environments à la demande” for the engineers working on $WORK’s Next Big Thing™. Their answer was a managed Kubernetes cluster and a bunch of Helm charts—and a small CLI tool to deploy the latter onto the former. A few hours later, I started building myself a k3s cluster. It’ll be a fun way to get familiar with the stack, I thought. What emerged almost resembles a managed cluster of sorts. I called it elsa , and it now hosts this very website along with a few other self-hosted services I had under my radar for a while .

Note

Yes, GitHub Pages and the like remain a better, cheaper, superior even way to host my website. But where is the fun in that? 😁

This may come as a surprise, considering I had migrated my website to a new setup called tinkerbell barely a month ago. Well, fret not. The little VPS sure has been retired early, but its legacy has not been lost. elsa was built upon the very same tools (Terraform, CoreOS, and Ignition) and promise I got hooked on a month ago: that there is freedom in designing a system whose destruction is a non-event. If anything, working on elsa has only deepened my understanding—and my appreciation—of what Fedora has been pushing for with CoreOS.

I really, really want to publish an article about elsa. I yet have to find my angle, though. Funny story, the first couple of paragraphs of this section were initially intended to be its introduction, until I grew dissatisfied with them and decided to repurpose them. Which means I need to restart from scratch. 😆

Anyway, as I was making good progress on elsa, I ran into some good opportunities to contribute to some open source software. I opened two bugfix PRs over the course of my journey: one for the official BetterStack’s Terraform provider , and the other for external-dns’ Vultr webhook sidecar . That was pretty cool! I want to do that more often.

We are almost a third into March already, and the month is clearly following the trend set by its predecessor. As such, I expect to have plenty to write about in a month’s time, meaning I should be able to keep up with publishing these retrospective pieces for a while. At least, I hope so!

What Happened in January 2026?

January 30, 2026

What Happened in January 2026?

meta vibecoding

This is my first retrospective in quite a while—I have yet to make writing these logs a real habit of mine. That being the case, so much happened this month that this article felt like the obvious thing to do.

`tinkerbell`’s First Month

On January 5th, I published my account of migrating my website to a completely new setup. Not only am I very proud of this article in and of itself, I am also quite happy that it has sparked discussions in a few places such as lobste.rs or the orange website . It has also been shared in other places like the DevOps’ish newsletter I have also created a GitHub repository to host tinkerbell configuration, and it is quietly farming stars as we speak. .

I don’t write articles with the expectation that they reach a large audience, but I will admit I had some ambitions for this one. It’s very fulfilling to know my experiment report of sorts has caught the attention of my peers, if only a little.

At first, I thought I would spend January experimenting with my new playground. I have a handful of services I want to deploy. Little did I know I would be sidetracked sharply before I had a chance to get to it.

Meeting with Claude Code

Somehow, I have managed to go through 2025 while staying afar from the code agent hype. I gave “vibecoding” a try in May by chatting with ChatGPT and Gemini while yak shaving my way towards transcribing YouTube videos in OCaml. Even I realized back then that the hype had already moved on from chat UI towards agents.

Then, the craziest thing happened. I went on holidays on December 23rd, 2025. Two weeks later, as I was going back to $WORK, Claude Code and its ilk suddenly felt inevitable. It looks like agentic workflows got very good in a matter of a few weeks, up to a point where there is a real opportunity cost in ignoring them altogether. And as I am about to take out a mortgage, it feels like a bad time to take the risk of falling out of relevance.

Looking back, I think it started with a simple, genuine suggestion—we were discussing a fairly ambitious clean-up of our test-suite at $WORK when someone mentioned Claude Code was quite relevant for this kind of tedious, boilerplate-heavy task. This resonated with all the success stories I was suddenly exposed to. Before I could realize what was happening, I was caught up in an intense introspective journey.

Part of my answer to the angst of LLMs being on the verge of reshaping the way I work is CeCe CeCe being a nickname for Claude Code (CC). .

CeCe is a Claude Code plugin ~~I have been working~~ Claude Code and I have been working on for the better part of the month, and it has become my sandbox to experiment with and understand agentic workflows. Configuring Claude Code in a very opinionated way felt only natural—that’s the only starting point I know. I am glad I did that, it enabled me to get a better understanding of how Claude Code actually works.

Ironically, since CeCe has mostly been written by CeCe itself and because it grew quite fast as a result, I do not really feel confident in modifying it myself 😆. I am now trying to rewrite it on my own, with more structure and “intention.” We will see how it goes.

New RSS Feeds

On a final note, I am glad to say that this website now features some new RSS feeds that you may be interested inThat’s actually the very first task I entrusted to Claude Code. Suffice it to say, it didn't blink, and navigated through my quite unusual setup like a champ. : one per tags, and one per series. I have been meaning to implement them since I’ve added my website to a certain aggregator that now advertises every article I publish that cites one particular programming language.

I am glad to know that camel aficionados learnt about my tinkerbell setup simply because I drew a parallel between infrastructure as code and functional programming. Maybe they don’t share my enthusiasm, though. With this change, I am one PR away from limiting this aggregator’s scope to simply the articles featuring the appropriate tag. I think they will find it useful. Maybe you will too!

I Cannot SSH Into My Server Anymore (And That’s Fine)

January 5, 2026

I Cannot SSH Into My Server Anymore (And That’s Fine)

coreos docker meta self-hosting terraform vultr

I would like to thank Yann Régis-Gianas, Sylvain Ribstein and Paul Laforgue for their feedback and careful review.

To kick off 2026, I had clear objectives in mind: decommissioning moana, my trusty $100+/month VPS, and setting up tinkerbell, its far less costly successor.

On the one hand, I have been using moana to self-host a number of services, and it was very handy to know that I had always a go-to place to experiment with whatever caught my interest. On the other hand, $100/month is obviously a lot of money, and looking back at how I used it in 2025, it was not particularly well spent. It was time to downsize.

Now that tinkerbell is up and running, I cannot even SSH into it. In fact, nothing can.

There is no need. To update one of the services it hosts, I push a new container image to the appropriate registry with the correct tag. tinkerbell will fetch and deploy it. All on its own.

In this article, I walk through the journey that led me to the smoke and mirrors behind this magic trick: Fedora CoreOS , Ignition and Podman Quadlets in the main roles, with Terraform as an essential supporting character. This stack checks all the boxes I care about.

Note

For interested readers, I have published tinkerbell’s full setup on GitHub. This article reads as an experiment log, and if you are only interested in the final result, you should definitely have a look.

Container-Centric, Declarative, and Low-Maintenance

Going into this, I knew I didn’t want to reproduce moana’s setup—it was fully manualIn the end, I never took the time to publish a write-up about it, so in a nutshell: everything relied on a small script that enabled me to create interconnected nspawn containers on the spot. and I no longer have the time or the motivation to fiddle with the internals of a server. Instead, I wanted to embrace the principles my DevOps colleagues had taught me over the past two years.

My initial idea was to start with this very website, since it was the only service deployed on moana that I really wanted to keep. Since I had written a container image for this website, I just had to look for the most straightforward and future-proof way to deploy it in production™— something I could later extend to deploy more cool projects, if I ever wanted toIf my goal was limited to host a static website, this whole setup would arguably be both overengineered and counterproductive. tinkerbell was to become my little foothold in the Internet, though. My “cloud homelabs,” of sorts. .

Docker Compose alone wasn’t a good fit. I like compose files, but one needs to provision and manage a VM to host them. Ansible can provision VMs, but that road comes with its own set of struggles. Writing good playbooks has always felt surprisingly difficult to me. In particular, a good playbook is supposed to handle two very different scenarios—provisioning a brand new machine, and updating a pre-existing deployment—and I have found it particularly challenging to ensure that both paths reliably produce the same result.

Kubernetes was very appealing on paper. I have seen engineers turn compose files into Helm charts and be done with it. If I could do the same thing, wouldn’t that be bliss? Unfortunately, Kubernetes is a notoriously complex stack, resulting from compromises made to address challenges I simply don’t face. Managed clusters could make things easier, but they aren’t cheap. That would defeat the initial motivation behind retiring moana.

CoreOS , being an operating system specifically built to run containers, obviously stood out. That said, I had very little intuition on how it could work in practice. So I started digging. I learned about Ignition first. Its purpose is to provision a VM exactly once, at first boot. If you need to change something afterwards, you throw away your VM and create a new one. This may seem counter-intuitive, but since it eliminates the main reason I was looking for an alternative to Ansible, I was hookedCoreOS and Ignition enable me to think about virtual machines the same way OCaml or Haskell trained me to think about data: as immutable values. .

I found out how to use systemd unit files to start containers via podman CLI commands. That was way too cumbersome, so I pushed on for a way to orchestrate containers à la Docker Compose. That’s when I discovered Podman Quadlets and auto-updates .

With that, everything clicked. I knew what I wanted to do, and I was very excited about it.

Assembling `tinkerbell`

For more than a year now, my website has been served from RAM by a standalone, static binary built in OCaml, with TLS termination handled by Nginx and certbot’s certificates renewal performed by yours trulyI didn’t lie when I said moana’s setup was indeed manual. . I didn’t have any reason to fundamentally change this architecture. I was simply looking for a way to automate their deployment.

Container-Centric, …

The logical thing to do was to have tinkerbell run two containers:

The reverse proxy: I had been firmly on Team Nginx for years now, but when I heard Caddy could “automatically obtain and renew TLS certificates,” I was sold on giving it a try.
The website itself: Static binaries can be wrapped inside a container with close to zero overhead using the scratch base image, so I did just that. I published it to a free-plan, public registry hosted on Vultr that I created for the occasionWhich means getting an offline copy of this website is now as simple as calling docker pull ams.vultrcr.com/lthms/www/soap.coffee:live. .

Nothing beats a straightforward architecture

Nothing fancy or unexpected here, which made it a good target for a first deployment. It was time to open Neovim to write some YAML.

Declarative, …

At this point, the architecture was clear. The next step was to turn it into something a machine could execute. To that end, I needed two things: first an Ignition configuration, then a CoreOS VM to run it.

The Proof of Concept

Ignition configurations (.ign) are JSON files primarily intended to be consumed by machines. They are produced from YAML files using a tool called Butane . For instance, here is the first Butane configuration file I ended up writing. It provisions a CoreOS VM by creating a new user (lthms), along with a .ssh/authorized_keys file allowing me to SSH into the VMI didn’t know at the time that I would deliberately remove these lines from the final Butane file. .

variant: fcos
version: 1.5.0
passwd:
  users:
    - name: lthms
      ssh_authorized_keys:
        - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKajIx3VWRjhqIrza4ZnVnnI1g2q6NfMfMOcnSciP1Ws lthms@vanellope

What’s important to keep in mind is that Ignition runs exactly once, at first boot. Then it is never used again. This single fact has far-reaching consequences, and is the reason why any meaningful change implies replacing the machine, not modifying it.

Before going any further, I wanted to understand how the actual deployment was going to work. I generated the Ignition configuration file.

butane main.bu > main.ign

Then, I decided to investigate how to define the Vultr VM in Terraform. The resulting configuration is twofold. First, we need to configure Terraform to be able to interact with the Vultr API, using the Vultr provider . Second, I needed to create the VM For discovering what values to put in most fields, vultr-cli is pretty convenient. Kudos to the Vultr team for making it in the first place. and feed it the Ignition configuration.

resource "vultr_instance" "tinkerbell" {
  region = "cdg"
  plan = "vc2-1c-1gb"
  os_id = "391"

  label = "tinkerbell"
  hostname = "tinkerbell"

  user_data = file("main.ign")
}

And that was it. I invoked terraform apply, waited for a little while, then SSHed into the newly created VM with my lthms user. Sure enough, the tinkerbell VM was now listed in the Vultr web interface. I explored for a little while, then called terraform destroy and rejoiced when everything worked as expected.

The MVP

At this point, I was basically done with Terraform, and I just needed to write the Butane configuration that would bring my containers to life. As I mentioned earlier, the first approach I tried was to define a systemd service responsible for invoking podman.

systemd:
  units:
    - name: soap.coffee.service
      enabled: true
      contents: |
        [Unit]
        Description=Web Service
        After=network-online.target
        Wants=network-online.target

        [Service]
        ExecStart=/usr/bin/podman run \
          --name soap.coffee \
          -p 8901:8901 \
          --restart=always \
          ams.vultrcr.com/lthms/www/soap.coffee:latest
        ExecStop=/usr/bin/podman stop soap.coffee

        [Install]
        WantedBy=multi-user.target

Adding this entry in my Butane configuration and redeploying tinkerbell got me exactly what I wanted. My website was up and running. For the sake of getting something working first, I added the necessary configuration for Caddy (the container and the provisioning of its configuration file), redeployed tinkerbell again, only to realize I also needed to create a network so that the two containers could talk together. After half an hour or so, I got everything working, but was left with a sour taste in my mouth.

This would simply not do. I wasn’t defining anything, I was writing a shell script in the most cumbersome way possible.

Then, I remembered my initial train of thought and started to search for a way to have Docker Compose work on CoreOSWell, Podman Compose, I guess. . That is when I discovered Quadlet, whose initial repository does a good job justifying its existence This repository is now archived, since Quadlet has got merged upstream. . In particular,

With quadlet, you describe how to run a container in a format that is very similar to regular systemd config files. From these actual systemd configurations are automatically generated (using systemd generators ).

To give a concrete example, here is the .container file I wrote for my website server.

[Container]
ContainerName=soap.coffee
Image=ams.vultrcr.com/lthms/www/soap.coffee:live

[Service]
Restart=always

[Install]
WantedBy=multi-user.target

I wasn’t wasting my time teaching systemd how to start containers anymore. I was now declaring what should exist, so that systemd—repurposed for the occasion as a container orchestrator—could take care of the rest.

Tip

If your containers are basically ignored by systemd, be smarter than me. Do not try to blindly change your .container files and redeploy your VM in a very painful and frustrating loop. Simply ask systemd for the generator logs.

sudo journalctl -b | grep -i quadlet

I excitedly turned caddy.service into caddy.container, redeployed tinkerbell, ran into the exact same issue I had encountered before and discovered the easiest way for two Quadlet-defined containers to talk to each other was to introduce a pod . Unlike Docker Compose which uses DNS over a bridge network, a pod shares the network namespace, allowing containers to communicate over localhost.

To define a pod, one needs to create a .pod file, and to reference it in their .container files using the PodName= configuration option. A “few” redeployments later, I got everything working again, and I was ready to call it a day.

And with that, tinkerbell was basically ready.

Caution

I’ve later learned that restarting a container that is part of a pod will have the (to me, unexpected) side-effect to restart all the other containers of that pod.

And Low-Maintenance

Now, the end of the previous section might have given you pause.

Even a static website like this one isn’t completely “stateless.” Not only does Caddy require a configuration file to do anything meaningful, but it is also a stateful application as it manages TLS certificates over time. Besides, I do publish technical write-ups from time to timeTwo in 2025, that’s true. But 2026 is only starting, you never know what might come! .

Was I really at peace with having to destroy and redeploy tinkerbell every time I need to change anything on my website?

On the one hand, yes. I believe I could live with that. I modify my website only a handful of times even in good months, I think my audience could survive with a minute of downtime before being allowed to read my latest pieces. It may be an unpopular opinion, but considering my actual use case, it was good enough. Even the fact that I do not store the TLS certificates obtained by Caddy anywhere persistent should not be an issue. I mean, Let’s Encrypt has fairly generous weekly issuance limits per domain How do I know that? Well... I might have hit the limit while hacking my way to a working setup. . I should be fine.

On the other hand, the setup was starting to grow on me, and I have other use cases in mind that could be a good fit for it. So I started researching again, this time to understand how a deployment philosophy so focused on immutability was managing what seemed to be conflicting requirements.

I went down other rabbit holes, looking for answers. The discovery that stood out the most to me—to the point where it became the hook of this article—was Podman auto-updates.

To deploy a new version of a containerized application, you pull the new image and restart the container. When you commit to this pattern, why should you be the one performing this action? Instead, your VM can regularly check registries for new images, and update the required containers when necessary.

In practice, Podman made this approach trivial to put in place. I just needed to label my containers with io.containers.autoupdate set to registry, enable the podman-auto-update timerBy default, the timer is triggered once a day, which felt unnecessarily long, so I decided to make it hourly instead. , and that was it. Now, every time I update the tag www/soap.coffee:live to point to a newer version of my image, my website is updated within the hour.

And that is when the final piece clicked. At this point, publishing an image becomes the only deployment step. I didn’t need SSH anymore.

The Road Ahead

tinkerbell has been running for a few days now, and I am quite pleased with the system I have put in place. In retrospect, none of this is particularly novel. It feels more like I am converging toward a set of practices the industry has been gravitating toward for years.

A man looking at the “CoreOS & Quadlets” butterfly and wondering whether he’s looking at Infrastructure as Code. I’m not entirely sure of the answer.

The journey is far from being over, though. tinkerbell is up and running, and it served you this HTML page just fine, but the moment I put SSH out of the picture, it became a black box. Aside from some hardware metrics kindly provided by the Vultr dashboard, I have no real visibility into what’s going on inside. That is fine for now, but it is not a place I want to stay in forever. I plan to spend a few more weekends building an observability stackOh, and maybe I will move these TLS certificates in a block storage or something. That could be a good idea. . That will come in handy when things go wrong—as they inevitably do. I would rather have the means to understand failures than guess my way around them.

Did I ever mention I am an enthusiastic Opentelemetry convert?

What Happened in 2024?

January 1, 2025

What Happened in 2024?

Free and Open Source Software

I’ve been a “prolific contributor” at $WORK, but less so with my personal projects.

Spatial Shell remains my most “popular” projectWe should reach 100 stars on GitHub in 2025 😅. , but except for a very minor 7th release in January, I have not touched it. It’s basically a done project, and I very much enjoy using it on a daily basis. My main regret is that, contrary to what is stated in its README, Spatial Shell does not work at all with i3.
ezjsonm-encoding was initially written for Spatial Shell, but I turned it into its own OCaml package in 2024. It is a JSON-only encoding library heavily borrowing on Data-encoding API , but with a more flexible default behavior for object parsing. I enjoyed writing the documentation, inspired by a tweet from Dmitrii Kovanikov Yes, cool kids moved to Bluesky in 2024, and Dmitrii is definitely a cool kid. . That being said, I have never bothered to benchmark this package properly, so if performances are important, it may not be a good fit for you.
jsonrpc2 is, as of January 1st, 2025, an experiment in providing a general-purpose framework for servers and clients communicating with the JSON RPC 2.0 protocol. I quite like the API I’m proposing there, and maybe I’ll try to polish and publish it in 2025.
bepo-tsrn.nvim is another thing I have done for myself, but published as if it was a public good. Now, instead of having to copy/paste the same Neovim configuration file on every computer I use, I can just type yay -S neovim-bepo-tsrn-git and be done with it.
celtchar has seen its first commits since 2021, which is not nothing. As a reminder, celtchar is a little tool I have written to generate ebooks and static websites for the stories I write; and as I was doing the 2024 edition of NaNoWriMo , I found myself in need to add a missing feature (supporting books split in parts, not only chapters).

Overall, I’ve been defaulting to OCaml for the past two years or so, and I am starting to think it is time to widen my perspective again. I will probably start with relearning GoI don’t know why, but I have been mildly obsessed with this language lately. .

Blog posts

2024 was not a very productive year when it comes to this website. I have published 5 articles, which is half the number of publications of 2023. As a logical consequence, not a lot of folks have visited my website this year. Funnily enough, the most read article (by far) in 2024 was published in 2023To be fair, it was published on December 30, 2023. .

Yes, 2024 was a quiet year for this website

That being said, I am quite happy with the content published in 2024.

Using git maintenance with Encrypted SSH Keys is the first article I published in 2024. It is a direct consequence of my trip to Brussels in February to attend to FOSDEM . If you haven’t already, you should watch Scott Chacon’s talk about Git less known commands; it is the only reason why I learned about git maintenance.
Installing a LUKS-Encrypted Arch Linux on a Vultr VPS is mostly a gift I have made to Future Me. It is a very specific how-to that I can use to quickly set up a new server with disk encryption. Funny story, I was planning to publish a follow-up about how I use systemd-nspawn to run my web services in containers , but no matter how many times I tried, I’ve never quite found a good way to tell this story. As I plan to educate myself on Kubernetes in 2025, it is not clear I will ever publish it now.
Introducing bepo-tsrn.nvim is probably the less useful article I have published in 2024, considering I expect the userbase to bepo-tsrn.nvim to stick to 1 until the very endBut who knows? Maybe one of you will prove me wrong! .
On Vestigial Structures hardly qualifies as a blog post, and is mostly a joke. It is also the only content on my website that was mostly generated by ChatGPT, and it is flagged as such. I don’t like using AI to write, but I do appreciate having a reviewer always at hand.
Serving This Article from RAM for Fun and No Real Benefit was very fun to write. This little experiment was stuck in my head for basically two years, and it turned out basically exactly as I had pictured it. That being said, I want to learn about CDNs now.

Overall, I still enjoy having my own little corner of the Internet, but if there is one thing I’d like to improve in 2025, it is its reach. I’d like you folks to run into my website, instead of having to promote it every time I write something. 2025, the year of SEO?

`$WORK`

2024 started with my decision to go back to a Software Engineering position, after giving an honest try at being an Engineering Manager in late 2023.

I want to remember 2024 for two things.

This year, more than ever, I have tried to appreciate my work beyond my individual contributions. I am confident in my programming skills (although I have so much to learn), but being an accomplished engineer is much more than contributing code. Making sure every engineer in the team can work to the best of their current ability, fostering a work environment favoring growth and initiative, estimating as precisely as possible the amount of time needed to deliver the next important thing, collaborating efficiently with non-technical teams... I am becoming increasingly interested in these areas.

Besides, this year was all about delivering and deploying in production. It’s been a wild ride , and I loved it even if it was very demanding. After having mostly contributed to R&D projects, the focus on UX, backward compatibility, etc. was very refreshing. I learned so much through the year, and had many opportunities to make significant impacts.

In 2025, I want to keep learning about software engineering, and maybe start sharing my thoughts on the subject on my website.

Talks

I gave only one talk in 2024, at a conference called EthCC . It was actually a follow-up to the talk I gave the year before. You can watch me deliver the talk here , but if you are more into written content, I have also published a transcript on this very website. I actually loved writing it down, and plan to systematically publish similar content for every recorded talk I will give in the future.

I also had the opportunity to participate in a Twitter Space .

This year, my public speaking opportunities were all $WORK-related. I would like to change this in the future, because there are enough events out there for me to start speaking about something other than workIt’s too late to apply to FOSDEM, but maybe I can find something to say to an event later in the year! I think. .

Sport

This year was a bit of a disappointment, sport-wise. I tried several times to get back to running regularly, and failed miserably. I went to Lyon for a 10km run without proper training, and skipped the half-marathon I signed up for. I should update my Running Log nonetheless. I started swimming regularly during the Summer, only to pierce my earlobes in September 😅.

Let’s hope I do better in 2025! I am planning to register for the Triathlon de Deauville with my sister. That promises to be fun! And I want to commit to the 20km de Paris as well.

On the bright side, I have started to use my bike again. I love riding around Paris, especially at night.

Final Notes

Overall, I’ve devoted a large part of my time to $WORK in 2024. Hopefully, I will find a better balance over the course of 2025, which should give me more time to explore and experiment more things.

Anyway, happy new year everyone! And happy Dry January!

Serving This Article from RAM for Fun and No Real Benefit

December 25, 2024

Serving This Article from RAM for Fun and No Real Benefit

docker meta ocaml

In 2022, Xe Iaso published a transcript of their talk on how their website was working at the time . In a nutshell, their approach consisted of a server preprocessing the website from its source at startup, then serving its contents from memory. If you have not already, I can only encourage you to read the article or watch the talk, as the story they tell is very interesting. For me personally, it sparked a question: what if, instead of preprocessing the website at startup, one decided to embed the already preprocessed website within the program of the HTTP server tasked to serve it?

Fast-forward today, and this question has finally been answered. The webpage you are currently reading has been served to you by an ad hoc HTTP server built with Dream , whose binary is the only file I need to push to my server to deploy the latest version of my website. I have actually deployed it, and it’s been serving the contents of this website for more than a week now.

What did I learn from this fun, little experiment? Basically, that this approach changes nothing, as far as Lighthouse and my monitoring is concerned. I couldn’t find any meaningful differences between a static website served by Nginx, a piece of software with thousands and thousands of engineering work behind it, and my little toy web server pieced together in an hour or so. Still. It was fun, so why not write about it?

This article is a kind of experience report. I’ll dive into what I have done to turn my website into a single, static binary. Not only does it mean writing some OCaml, which is always fun, but it also requires understanding a little some key HTTP headers, as well as using Docker to build easily deployable binaries. All in all, I hope it will be an interesting read for the curious minds.

Embedding My Website in a Binary

Not much had changed much since I stopped using cleopatra to generate this website, and the article I published in 2023 still stands. In a nutshell, I work in the site/ directory, and soupault generates my website in the out/~lthms directory, thanks to a collection of built-in and ad hoc pluginsFor instance, Markdown footnotes are turned into side notes with a soupault plugin. . To deploy the website, I was relying on rsync to sync the contents of the out/~lthms directory with the directory statically served by a Nginx instance on my personal server.

The first step of my little toy project is to actually embed the output of soupault into an OCaml program.

That’s where ocaml-crunch comes in handy. It is a MirageOS project, whose only job is to generate an OCaml module from a file system directory. It is straightforward to use it from Dune.

; file: out/dune
(rule
 (target website_content.ml)
 (deps (source_tree ~lthms))
 (action
  (run ocaml-crunch -m plain -o %{target} -s ~lthms)))

This snippet generates the website_content.ml module, which we can then expose through a library with the library stanza.

; file: out/dune
(library
 (name website_content))

And we are basically done. Excluding an Internal module, the signature of Website_content is pretty straightforward.

val file_list : string list
val read : string -> string option
val hash : string -> string option
val size : string -> int option

Serving the content with Dream

Dream is a cool project, and provides a straightforward API that we can leverage to turn our list of in-memory files into an HTTP server.

Naive Approach

Our goal now is to create a Dream.handler for each item in file_list. Done naively (as was my first attempt), it gives you something of the form:

let make_handler ~content path =
  Dream.get path (fun req ->
    Lwt.return (Dream.response content)))

Which we can use to build the main route we will then pass to Dream.router.

let website_route =
  Dream.scope "~lthms" []
  @@ List.map
       (fun path ->
         let content = Option.get (Website_content.read path) in
         make_handler ~content path)
       Website_content.file_list

With this approach, we build our handlers once, and then the lookup is done by Dream’s router. It could be an interesting experiment to see if doing the lookup ourselves is more performant (since Dream’s router is very generic, while in our case we don’t really need to parse anything). I remember Xe routing is basically going through a linked list, which seems strange at first, but works very well in practice because they have ordered said list with the most recent articles up front, and everybody comes to their website to read the latest article anyway.

It does not take an extensive QA process to figure out that this approach is far from being enough. To name a few things:

My website assumes http://path/index.html can be accessed with http://path/ or http://path. Our little snippet does not handle this.
Browsers expect the Content-Type headers to be correctly set. To give an example, they won't load a CSS file if the Content-Type header is not set to text/css.
Browsers work best for websites that take the time to provide caching directives. Our little snippet does not care to do so.
Even if my website is rather lightweight20MBytes at the time of writing the first version of this article. , compressing the response of our HTTP server for clients that support it is always a good idea.

This is a gentle reminder of all the things Nginx can do for you with very little configuration.

Handling `index.html` Synonyms

This one is rather simple. For files named index.html, we need 3 handers, not just one. We can achieve this with an additional helper make_handler_remove_suffix.

let make_handler_remove_suffix ~content path suffix
    =
  if String.ends_with ~suffix path then
    let alt_path =
      String.sub path 0 (String.length path - String.length suffix)
    in
    [ make_handler ~content alt_path ]
  else []

Updating the website_route definition to use make_handler_remove_suffix is quite easy as well.

 let website_route =
   Dream.scope "~lthms" []
-  @@ List.map
+  @@ List.concat_map
        (fun path ->
          let content = Option.get (Website_content.read path) in
-         make_handler ~content path)
+         if path = "index.html" then
+           (* Special case to deal with "index.html" which needs to be
+              recognized by the route "/" *)
+           [
+             make_handler ~content "/";
+             make_handler ~content "";
+             make_handler ~content "index.html";
+           ]
+         else
+           make_handler_remove_suffix ~content path
+             "/index.html"
+           @ make_handler_remove_suffix ~content
+               path "index.html"
+           @ [ make_handler ~content path ])
        Website_content.file_list

With that, https://soap.coffee/~lthms/posts/index.html returns the same pages as https://soap.coffee/~lthms/posts or https://soap.coffee/~lthms/posts. Check.

Supporting `Content-Type`

Content-Type is an HTTP header which is used by the receiver of the HTTP message (whether it is a request or a response) to interpret its content.

For instance, when building a RPC API, Content-Type is used by the server to know how to parse the request body (Content-Type: application/json or Content-Type: application/octet-stream being two popular choices, for JSON or binary encoding, respectively).

In our case, the Content-Type header is used by the HTTP server to communicate the nature of the content to browsers. For my website, I can just use the file extensions to infer the correct header to set. First, we list the extensions that are actually used.

let content_types =
  [
    (".html", "text/html");
    (".css", "text/css");
    (".xml", "text/xml");
    (".png", "image/png");
    (".svg", "image/svg+xml");
    (".gz", "application/gzip");
    (".pub", "text/plain");
  ]

A header in Dream is encoded as a string * string value, with the first string being the header name and the second being the header value.

let content_type_header path =
  List.filter_map
    (fun (ext, content_type) ->
      if String.ends_with ~suffix:ext path then
        Some ("Content-Type", content_type)
      else None)
    content_types
  |> assert_f
       ~error_msg:Format.(sprintf "Unsupported file type %s" path)
       (( <> ) [])

with assert_f being defined as follows.

let assert_f ~error_msg f v =
  if f v then v else failwith error_msg

assert_f is used to enforce that I don’t deploy a website which contains route lacking a Content-Type header. For instance, if I remove the "html" entry of the content_type list, I get this error when I try to execute the server.

Fatal error: exception Failure("Unsupported file type index.html")

This is because the headers are only computed once, when each route are defined. This is a key principle of this project: compute once, serve many timeI would love to get a compilation error instead (considering there are no runtime values involved), but have not looked into this just yet. .

 let website_route =
   Dream.scope "~lthms" []
   @@ List.concat_map
        (fun path ->
          let content = Option.get (Website_content.read path) in
+         let headers = content_type_header path in
          if path = "index.html" then
            (* Special case to deal with "index.html" which needs to be
               recognized by the route "/" *)
            [
-             make_handler ~content "/";
-             make_handler ~content "";
-             make_handler ~content "index.html";
+             make_handler ~headers ~content "/";
+             make_handler ~headers ~content "";
+             make_handler ~headers ~content "index.html";
            ]
          else
-           make_handler_remove_suffix ~content path
+           make_handler_remove_suffix ~headers ~content path
              "/index.html"
-           @ make_handler_remove_suffix ~content
+           @ make_handler_remove_suffix ~headers ~content
                path "index.html"
-           @ [ make_handler ~content path ])
+           @ [ make_handler ~headers ~content path ])
        Website_content.file_list

(The changes in make_handler and make_handler_remove_prefix are left as an exercise to enthusiast readers)

Compressing if Requested

Nowadays, computations are cheap, while downloading data costs time (and sometimes money). As a consequence, it is often a good idea for a server to compress a large HTTP response, and browsers do ask them to do so, by setting the Accept-Encoding header of their requests.

The value of the Accept-Encoding header is a comma-separated list of supported compression algorithms, optionally ordered with a priority value q.

For instance, Accept-Encoding: gzip;q=0.5, deflate;q=0.3, identity tells you that the browser supports three encoding methods: gzip, deflate and identity (no compression), and the browser prefers gzip over deflate. Besides, the request can provide several Accept-Encoding headers instead of just one, so we can have

Accept-Encoding: gzip;q=0.5
Accept-Encoding: deflate;q=0.3
Accept-Encoding: identity

The String module provides everything we need to check if a browser supports gzip as an encoding methodSpoiler: they do. I was even wondering at some point if I could just always return GZIP-compressed values, ignoring the Accept-Encoding header altogether. If you do that, though, curl becomes annoying to use (it does not uncompress the response automatically, and instead complains about being about to write binary to the standard output). .

(* For [method(; q=val)?], returns [method], except if
   [q=0]. *)
let to_directive str =
  match String.split_on_char ';' str |> List.map String.trim with
  | [ x ] -> Some x
  | [ x; y ] -> (
      match String.split_on_char '=' y |> List.map String.trim with
      | [ "q"; "0" ] -> None
      | [ "q"; _ ] -> Some x
      | _ -> None)
  | _ -> None

(* [contains ~value:v header] returns [true] if [v] is a
   supported method listed in [header]. *)
let contains ~value header =
  String.split_on_char ',' header
  |> List.to_seq |> Seq.map String.trim
  |> Seq.filter_map to_directive
  |> Seq.exists (( = ) value)

We use contains to tell us if we can return a compressed response, which leaves us with one final question: how to compress said response?

The OCaml ecosystem seems to have picked camlzip library when GZIP is involvedYou know it is a legitimate OCaml library when one of the top-level modules is not documented at all . . What is surprising with this library is that it does not support in-memory compression: the functions expect channels, not bytes. That is quite annoying, because we are specifically doing this not to use files.

The Internet is helpful here, and quickly suggests using pipes. It works when you remember –or figure out– that pipes are a blocking mechanism: one does not just write a buffer of arbitrary size in a pipe, because after something like 4KBytes, writing becomes blocking until a read happens to free some space. That’s not a big problem: we can read and write concurrently to the pipe using threads, and OCaml 5 makes it quite easy to do so with the Domain module.

let gzip content =
  let inc, ouc = Unix.pipe () in
  let ouc = Gzip.open_out_chan ~level:6 Unix.(out_channel_of_descr ouc) in
  let _writer =
    Domain.spawn (fun () ->
        Gzip.output_substring ouc content 0 String.(length content);
        Gzip.close_out ouc)
  in
  let res = In_channel.input_all Unix.(in_channel_of_descr inc) in
  Unix.close inc;
  res

Caution

As rightfully pointed out by Daniel Bünzli , the gzip function presented in this article is full of shortcomings. To quote the message, the function can leak fds in case of errors and domains are not meant to be used that way (it’s rather spawn one long running domain per CPU you have). It’s not necessarily more complicated to correct it to use Fun.protect invocations to make sure all your fds get closed even if the function blows up and use Thread.create so that the netizens cut and paste correct code.

In my opinion, this implementation is “good enough” for my use case, which is compressing arbitrary strings before the HTTP server is even started. If it were to be called in the handlers themselves, then definitely, it would not be suitable.

Keep that in mind if you want to borrow this code.

We know how to decide whether to compress or not, and how to compress. The next step is to modify make_handler accordingly.

-let make_handler ~headers ~content path =
+let make_handler ~headers ~gzip_content ~content path =
+  let gzip_headers = ("Content-Encoding", "gzip") :: headers in
   Dream.get path (fun req ->
-    Lwt.return (Dream.response content)))
+      match Dream.headers req "Accept-Encoding" with
+      | accepted_encodings
+        when List.exists (contains ~value:"gzip") accepted_encodings ->
+          Lwt.return @@ Dream.response ~headers:gzip_headers gzip_content
+      | _ -> Lwt.return @@ Dream.response ~headers content)

gzip_content is computed only once (using our gzip function), and passed to make_handler. This way, the only computation the handler needs to do is to “parse” Accept-Encoding.

Caching

Compressing a page to reduce the number of bytes a browser needs to download is fine. Letting the browser know it does not need to download anything because it's previous version is still accurate is better.

This is achieved through two complementary mechanisms: entity tags (ETag)My first encounter with entity tags was around the time GDPR was a hot topic, because you can use them as a cheap replacement for cookies to track your users . I remained at the surface level at the time, it was fun learning more about them through this little project. , and cache policies (Cache-Control).

Entity tags are used to identify a resource, and are expected to change every time the resource is updated. The general workflow goes like this: the first time a browser requests https://soap.coffee/~lthms/index.html, it caches the result along with the value of the ETag header. The next time it needs the page, it adds the header If-None-Match, with the ETag as its value. For such requests, the server is expected to return an empty response with HTTP code 304 (Not Modified).

I decided to use the sha256 hash algorithm to compute the entity tag of each resource of my website. The sha OCaml library looked like a good enough candidate.

(* in `website_route` *)
let etag = Sha256.(string content |> to_hex) in

Interestingly, one question I had to answer was whether the entity tag of a page needed to be different whether it was compressed or not. Internet almost unanimously answered yes. So be it. We just need to keep in mind ETag values are expected to be surrounded by quotes, and we are good to go. It is just a matter of suffixing the ETag with +gzip in the compressed case.

-let make_handler ~headers ~gzip_content ~content path =
-  let gzip_headers = ("Content-Encoding", "gzip") :: headers in
+let make_handler ~headers ~etag ~gzip_content ~content path =
+  let etag_gzip = Format.sprintf "\"%s+gzip\"" etag in
+  let etag = Format.sprintf "\"%s\"" etag in
+  let gzip_headers =
+    ("Content-Encoding", "gzip") :: ("ETag", etag_gzip) :: headers in
+  let identity_headers = ("ETag", etag) :: headers in
   Dream.get path (fun req ->
-      match Dream.headers req "Accept-Encoding" with
-      | accepted_encodings
-        when List.exists (contains ~value:"gzip") accepted_encodings ->
-          Lwt.return @@ Dream.response ~headers:gzip_headers gzip_content
-      | _ -> Lwt.return @@ Dream.response ~headers content)
+      match Dream.headers req "If-None-Match" with
+      | [ previous_etag ] when previous_etag = etag || previous_etag = etag_gzip
+        ->
+          Lwt.return
+          @@ Dream.response
+               ~headers:(("ETag", previous_etag) :: headers)
+               ~code:304 ""
+      | _ -> (
+          match Dream.headers req "Accept-Encoding" with
+          | accepted_encodings
+            when List.exists (contains ~value:"gzip") accepted_encodings ->
+              Lwt.return @@ Dream.response ~headers:gzip_headers gzip_content
+          | _ -> Lwt.return @@ Dream.response ~headers:identity_headers content))

Entity tags are useful, but you still need the browser to make an HTTP request every single time you visit the website. By setting a cache policy, we can remove even remove the need for this request most of the time. The Cache-Control header is used to set a number of parameters, including the max-age value (in seconds).

In my Nginx configuration, I had set max-age to a year for images. I did the same thing here. Besides, I decided to set max-age for other resources to 5 minutes. This seems like a good compromise: since my website does not change very often, it is very unlikely that you happen to visit it when I publish new content. Setting a 5-minute cache policy should let my readers download each resource only once, yet get the freshest version at their next visitDealing with the Cache-Control header is basically the same exercise as setting the correct Content-Type header, and this article is already long enough, which is why there is no diff or snippet in this section. .

And with this, we are done. We get a standalone library to server our website in a browser-friendly manner, which I can theoretically use to replace my current Nginx-powered setup. Although… is it that simple?

Building and Deploying the Website

Files are quite easy to share and deploy. As I mentioned earlier in this article, you just need to rsync them and be done with it. Binaries, on the other hand… One cannot just assume a binary build on a machine X will work on another machine Y. Some additional works need to be done.

The most straightforward solution I know is to rely on static binaries. I have already written about how to generate static binaries for OCaml projects, so I had a pretty strong head start, but one drawback of the approach I’ve described there (and that I have been using for Spatial Shell’s releases Not that there were many of them lately. ) is that it is rather slow (I have a script creating a new local switch each time) and requires static libraries to be installed (which Arch Linux does not provide).

And so, I figured, why not build the static binary in Docker? This allows me to use Alpine to get a static version of my system dependencies, and can be quite fast thanks to Docker build cache . The Dockerfile is quite simple: one stage for building the system and OCaml dependencies, and one stage for building the static binary.

FROM alpine:3.21 AS build_environment

# Use alpine /bin/ash and set shell options
# See https://docs.docker.com/build/building/best-practices/#using-pipes
SHELL ["/bin/ash", "-euo", "pipefail", "-c"]

USER root
WORKDIR /root

RUN apk add autoconf automake bash build-base ca-certificates opam gcc \ 
  git rsync gmp-dev libev-dev openssl-libs-static pkgconf zlib-static \
  openssl-dev zlib-dev
RUN opam init --bare --yes --disable-sandboxing
COPY makefile dune-project .
RUN make _opam/.init OCAML="ocaml-option-static,ocaml-option-no-compression,ocaml.5.2.1"
RUN eval $(opam env) && make server-deps

FROM build_environment AS builder

COPY server ./server
COPY out ./out
COPY dune .
RUN eval $(opam env) && dune build server/main.exe --profile=static

FROM alpine:3.21 AS soap.coffee

COPY --from=builder /root/_build/default/server/main.exe /bin/soap.coffee

Then, building my static binary becomes as simple as:

docker build . -f ./build.Dockerfile \
  --target soap.coffee \
  -t soap.coffee:latest
docker create --name soap-coffee-build soap.coffee:latest
docker cp soap-coffee-build:/bin/soap.coffee .
docker rm -f soap-coffee-build

docker cp does not work on an image, but on a container, so we need to create one which can be destroyed shortly after.

This little binary weights 38MBytes, which seems relatively reasonable to me, considering my website weights 20MBytes. I guess it could be easy to reduce this size by embedding the compressed version of my articles and images, instead of the uncompressed one. But really, for my website, I’m not really interested in investing the extra effort.

Conclusion

I would not recommend anyone to use this in production for anything remotely important, but from my perspective, it was both fun and insightful. I was able to refresh my memories about HTTP “internal,” among other things. Again, as far as I can tell, deploying my website this way did not bring me any benefit, performance-wise; even worse, I am pretty sure the Dream server will not behave as well as Nginx when it comes to handling the load (since it is limited to one core, instead of several with Nginx).

That being said, I am way too invested now… which is why, yes, you are reading a blog post served to you directly from memory 🎉.

The Free and Open Source Software Projects This Website is Built Upon in June 2023

June 23, 2023

The Free and Open Source Software Projects This Website is Built Upon in June 2023

Authoring Contents

As mentioned in my latest retrospective, I have simplified how I write my contents. Nowadays, all my write-ups are written in Markdown, and I use markdown-it to parse them and generate nice and fancy HTML documents.

In addition to the base parser that markdown-it is, I am relying on an ever-growing collection of plugins:

As a consequence, this website also benefits from two very nice projects: highlight.js for syntax highlighting, and $\KaTeX$ for displaying mathematics equations.

Frontend

In addition to normalize.css to “reset” the CSS defaults of various browsers, this website could not exist as it is now without the awesome Tufte CSS project. The sidenotes of this website could not have existed without it.

HTML Generation

While markdown-it is doing the heavy lifting of turning my Markdown contents in HTML pages, soupault is the goldsmith which pieces these pages together into a coherent whole.

I really enjoy using soupault for my website. In a nutshell, this tool enables me to customize the pages of my website with an API very similar to what Javascript offers, but instead of the computation happening on the client side every time the page is loaded, it is done on my laptop once, just before I push the new pages. Just an example: for my sidenote pages, I was able to reuse the markdown-it-footnote with zero modification, and I just had to write a simple Lua plugin to customize its output to my (humble) needs.

The running log is also another good example of an ad hoc page I can generate using a simple Lua script.

What happened since December 2022?

May 18, 2023

What happened since December 2022?

emacs meta neovim releases spatial-shell

Initially, I started this “What happened” series as an exercise to publish more regularly on this website. Suffice to say, I haven’t done a particularly impressive job in that regard, which only means I have a lot of room for improvement.

Anyway, if the first few months of 2023 has been mostly $WORK focus, the same cannot be said for April and May. For one, I have started running again. But this is only the tip of the iceberg.

Spatial Shell got its first releases

Spatial Shell is probably my hobby project I am most excited about. The “call for testers” article I have published recently managed to catch the attention of a few folksYou want to hear a lesson I learned the hard way just after publishing it? Before calling for testers, it is better to be sure your project can actually be compiled easily by the potential volunteers . . The perspective to publish such a write-up was a very strong source of motivation for me to clean up a project I was using daily for several months now, and I am very satisfied with the result.

Mass adoption is still a distant horizon, but still, the project is now mainstream enough that it has already been mentioned in a random topic on the OCaml discourse by someone who isn’t me . 🎉

This led me to formally release a first version of Spatial Shell in the end of April, and a second today. For the first time, I have also published an Archlinux package , to make the life of potential early adopters even easier. Do not hesitate to upvote it so that it can find its way to the extra repository some day.

Goodbye Emacs! Remember me, Neovim?

In 2015, I started using Coq for my PhD thesis and at the time, there was no real support for (Neo)vimThe situation later improved. Nowadays, you can implement your theories using Coqtail , and Coq LSP will probably become a viable and interesting setup in a near future. . Everyone was using Proof General and Emacs, so I was left with little choice but to follow through. With only my courage and the good advice of a fellow “vimer” who had also made a similar journey , I started using Emacs.

Fast forward 8 years later, and my Emacs configuration has become a project of its own. Overall, I was pretty happy with my setup, but in the same time, I always remained a bit nostalgic of my Neovim days. This is probably why I decided to give this old friend a try when my company bought me a new laptop. I also used this as an opportunity to try out this LSP-thing everyone was talking about.

It has been a month now, and I do not plan to come back to my previous habits. There are still some few edges here and there, I still need to get my head around lua, but LSP is nice, and plugins like telescope are simply too beautiful.

That being said, there was one aspect of moving from Emacs to Neovim I had not anticipated: Org mode. Which constitutes a perfect transition to the next session.

Website redesign, again

Did you notice this website has been revamping recently? The changes are actually deeper than “just” a redesign, to a point where I had to port all my write-ups to a different markup languageAre you starting to understand why “Org mode” was the perfect transition to move on to this section? .

Why, you ask? Well, it’s actually pretty simple: as time goes, I’ve grown lazier.

Let me give you some context. Until very recently, my website was built around the idea to have literate programming as a first-class citizen of my author tools. For instance, you can have a look at what used to be the literate program which was responsible for generating the website. Similarly, most of my write-ups about Coq were actually Coq documents. Literate programming is actually a very nice paradigm for authoring technical contents, because it gives you the tools to keep said contents accurate and up-to-date. In a nutshell, you cannot have a typo in one of your code snippets which would prevent it from compiling, because you actually compile the snippet and catch the typo when you try to generate your website. Or at least, it is what I used to do.

I decided to stop because, for all its benefits, this approach has one major drawback: it is hard to maintain. I had invested quite some time and efforts to keep my website sources under control, but it really was an everyday fight. There are some strange things which start happening when you fully commit to this, as I think I did. For instance, software dependencies tie your article together. Suddenly, you cannot talk about this new fancy feature of the latest Coq release without upgrading all your write-ups implemented as Coq documentsWell, in theory you can. Just have each Coq document specifies the Coq version it requires, and support this level of customization in your build toolchain. But then, your blog takes forever to build from a cold repository. .

That being said, most of the work had already been done. This website was a collection of literate programs, and I was pretty proud of the state of things. I could deal with the annoyancesLike using Coqdoc syntax to write my articles, for instance. I could write about how the Coqdoc syntax irks me for ages. . But then, as I explained in the previous section, I decided to move away from Emacs. The first time I tried to start a new write-up, it hit me.

I used to write most of my contents using Org mode. Org mode, also known as the Emacs markup language.

I know of at least one “Org plugin” for Neovim , but instead of giving it a try, I decided to use this opportunity to tackle my “maintenance problem” once and for all. I gave up on literate programming for this website. As a result, this website is now generated from Markdown files only (using markdown-it with many plugins). As a consequence, the generated HTML is way more “predictable.” This was enough to motivate me at giving a try at Soupault’s indexes , which are way more powerful than I anticipated. Now, this website has

Tags. Each write-up can be labeled with as many tags as I want, there is a page which lists all the tags used in the website, and each tag has its own page (for instance, the coq tag.
A RSS feed. It was actually one of the main features I really wanted to get with this revamp.
Automatically generated list of articles in the home page, for each series (see the Ltac series for instance). Before, I was publishing “curated indexes,” or put in other words: I was writing these indexes myself, by hand. And again, I’ve grown lazier.

It took me a week to go through this rework. Translating manually every write-up was tedious, to say the least, as was implementing the Lua plugins for Soupault since I have neither proficiency nor tooling to help me write Lua code. But I am very glad for the final result.

Also, I have invested in an Antidote license, so hopefully, this website will have fewer typos and English butchering as of now. A clean text, delivered with a nice and simple design, from a sane and maintainable Git repository .

What happened in September 2022?

September 18, 2022

What happened in September 2022?

spatial-shell meta

It is September 18 today, and it has already been a month since I decided to start these retrospectives. This means it is time to take a step back and reflect of what happened these past few thirty days or soThere is the shocking news that I have started to use syntax highlighting again. But let’s not linger too much into it just yet. .

Spatial Sway

A few days after publishing my August Retrospective, I have learned the existence of Material Shell , an extension for GNOME 3 that provides a very interesting user experience.

I tried it for a few hours, but the thing kept crashing (it’s probably on me, I did not even remember I had Gnome installed on my machine, and I would not be surprised the culprit was my dusty setup rather than Material Shell itself). The experience remained very promising, though. Their “spatial model” especially felt like a very good fit for me. Basically, the main idea is that you have a grid of windows, with your workspaces acting as the rows. You can navigate horizontally (from one workspace to another), or horizontally, and you choose how many windows you want to see at once on your screen.

And so for a few hours, I was a bit frustrated by the situation… until I learned about how one can actually manage and extend Sway (the Wayland compositor I use for several years now) thanks to its IPC protocol. I spend like three days experimenting, first in Rust, then in OCamlThis was actually an interesting thought process. I am using OCaml at $WORK for about more than a year now. I have curated a setup that works pretty well, and I am familiar with the development tools. On the contrary, I had not written a line of Rust for at least a year, my Emacs configuration for this language was broken, and I had lost all my fluency in this language. Still, I was not expecting to pick OCaml when I started this project. , and by the end of the week, I had a first working prototype I called Spatial Sway . It works pretty well; well enough that I am using it daily for several weeks now. It feels clunky at times, but it works well, and I have been able to write a Waybar configuration heavily inspired on Material Shell UI.

Overall, I am pretty satisfied with this turnout. Writing a hobbyist software project is always nice, but the ones you can integrate in your daily workflow are the best one. The last time I did that was keyrd , my little keystrokes counting daemon19,970,965 since I started using it at the time of writing this article .

Anyway, lots remains to be said about Spatial Sway, but I might save it for a bit later. I still have some key features to implement (notably, moving a window to another workspace), then I will probably try to advertise it a bit. I am under the impression this project could be of interest for others, and I would love to see it used by folks willing to give a Material Shell-like experience a try, without having to deal with Gnome Shell. By the way, considering Sway is a drop-in replacement for i3, and that it implements the exact same IPC protocol, there is no reason why Spatial Sway is actually Sway specific, and I will rename it Spatial Shell at some point.

Mandatory screenshot of Spatial Sway.

This Website

On a side note, I have started to refine the layout of this website a bit. Similarly, I have written a new, curated home page where I want to highlight the most recent things I have published on the Internet.

I have been experimenting with Alectryon as a way to replace coqdoc, to improve the readability of my Coq-related articles. Unfortunately, it looks like this tool is missing a key feature I need . I might try to get my hand dirty and implement it myself if I find the time and the motivation in the following weeks.

Finally, reading about how Xe Iaso’s talk about how she generates her blog was very inspiring to me. I can only suggest that you have a look.

Though not to the same extent, I also think I have spent way too much effort in my website. Most of my Coq-related articles are actual Coq program, expect the articles about coqffi which are Org mode literate programs. Hell, this website itself used to be a literate program of the sort, until I stopped using my homegrown literate programming toolchain cleopatra last month. At some point, I have even spent a bit of time to ensure most of the pages of this website were granted a 100/100 on websites like PageSpeed InsightGood news, I’ve just checked, and it still is! . I had almost forgotten.

A lot remains to be done, but watching this talk made me reflect on the job done. And opened my eyes to a new perspective, too. We will see what translates into reality.

What happened in August 2022?

August 15, 2022

What happened in August 2022?

emacs meta

Without further ado, let’s take a look at what was achieved for the last thirty days or so.

Emacs

I have started tweaking and improving my Emacs configuration againAfter having used Emacs for seven years now, I am nowhere close to consider my configuration as a done project. I really envy developers who are using their editor with little to no customization. .

Theme Selection Menu

The change I am the most excited about is that I have finally reduced the boilerplate in need to write to use a new theme. I am very indecisive when it comes to theming. I like to have my choices, and I get tired of any color scheme pretty quickly. As a consequence, I introduced a customizable variable to let me select a theme dynamically, and have this choice persist across Emacs session.

I have a Hydra menu that allows me to select which theme I want to use for the time being. It looks like this.

A Hydra menu for selecting a theme.

But adding new entries to this menu was very cumbersome, and mostly boilerplate that I know a good macro could abstract away. And I can finally report that I was right all along. I have my macros now, and they allow me to have the Hydra menu above generated with these simple lines of code.

(use-theme ancientless "a" :straight nil :load-path "~/.emacs.d/lisp")
(use-theme darkless "d" :straight nil :load-path "~/.emacs.d/lisp")
(use-theme brightless "b" :straight nil :load-path "~/.emacs.d/lisp")
(use-theme monotropic "m")
(use-theme monokai "M")
(use-theme nothing "n")
(use-theme eink "e")
(use-theme dracula "D")
(use-theme chocolate "c")
(use-themes-from tao-theme
                 '(("tl" . tao-yang)
                   ("td" . tao-yin)))

Eldoc and Flycheck Popups

I have been experimenting with several combinations of packages to have Eldoc and Flycheck using pop-up-like mechanisms to report things to me, instead of the echo area.

The winning setup for now is the one that uses the quick-peek package . That is, flycheck-inline (customized to use quick-peek, as suggested in their README), and eldoc-overlay . This works well enough, so the pop-ups of eldoc are maybe a bit too distracting.

#flycheck-inline in action with an OCaml compilation error.

In my quest for pop-ups, I ran into several issues with the packages I tried out. For instance, eldoc-box was very nice, but also very slow for some reason. It turns out there was an issue about that slowness, wherein the culprit was identified. This allowed me to submit a pull request that got merged rather quickly .

Similarly, after a packages update, I discovered flycheck-ocaml was no longer working, and submit a patch to fix the issue .

This Website

I have not been investing a lot of time in this website for the past six years or so. This month, things change a bit on that side too.

New Contents

First, I have published a (short) article on higher-order polymorphism in OCaml. The goal was for me to log somewhere the solution for an odd problem I was confronted to at $WORK, but the resulting article was not doing a great job as conveying this. In particular, two comments on Reddit motivated me to rework it, and I am glad I did. I hope you enjoy the retake.

Once this was out of the way, I decided that generating this website was taking way too much time for no good enough reason. The culprit was cleopatra, a toolchain I had developed in 2020 to integrate the build process of this website as additional contents that I thought might interest people. The sad things were: cleopatra was adding a significant overhead, and I never take the time to actually document them properly.

Under the Hood

Overall, the cost of using cleopatra was not worth the burden, and so I got rid of it. Fortunately, it was not very difficult, since the job of cleopatra was to extracting the generation processes from org files; I just add to implement a small makefile to make use of these files, without having to rely on cleopatra anymore.

This was something I was pondering to do for a long time, and as often in these circumstances, this gave me the extra motivation I needed to tackle other ideas I had in mind for this website. This is why now, rather than starting one Emacs process per Org file I have to process, my build toolchain starts one Emacs server, and later uses emacsclient.

Now, most of the build time is spent by soupault . I guess I will have to spend some time on the Lua plugins I have developed for it at some point.

A New Mailing List

Finally, I have created a public mailing list that is available if you want to start a discussion on one of my articles. Don’t hesitate to use it, or to register to it!

A Literate Toolchain To Build This Website

February 4, 2020

A Literate Toolchain To Build This Website

meta literate-programming emacs

Important

What you are reading is actually the rendered version of a Markdown document that was manually “translated” from the Org original document, named Bootstrap.org. Bootstrap.org was probably complete gibberish for anyone who isn’t me. This version was actually heavily reworked to try to fix that.

In any case, the tool-suite described here has not been used to generate this website for a while now.

A literate program is a particular type of software program where code is not directly written in source files, but rather in a text document as code snippets. In essence, literate programming allows for writing in the same place both the software program and its technical documentation.

cleopatra is a “literate toolchain” I have implemented to build this website, and you are currently reading itThis sentence was true when this article was published, but things have changed since then. . That is, cleopatra is both the build system and an article of this website! To achieve this, cleopatra has been written as a collection of org files which can be either “tangled” using Babel or “exported” as a HTML document. Tangling here refers to extract marked code blocks into files.

The page you are currently reading is cleopatra entry point. Its primary purpose is to define two Makefiles —makefile and bootstrap.mk— and the necessary emacs-lisp script to tangle this document.

On the one hand, makefile is the main entrypoint of cleopatra. It serves two purposes:

It initiates a few global variables, and
It provides a rule to tangle this document, that is to update itself and bootstrap.mk.

On the other hand, bootstrap.mk is used to declare the various “generation processes” used to generate this website.

makefile and the emacs-lisp scripts are versioned, because they are necessary to bootstrap cleopatra; but since they are also defined in this document, it means cleopatra can update itself, in some sense. This is to be kept in mind when modifying this document to hastily.

Global Constants and Variables

First, makefile defines several global “constants”As far as I know, make does not support true constant values, It is assumed generation processes will not modify them. . In a nutshell,

$ROOT tells Emacs where the root of your website sources is, so that tangled output filenames can be given relative to it rather than the org files. So for instance, the block_src tangle parameter for Makefile looks like :tangle Makefile, instead of :tangle ../../Makefile.
$CLEODIR tells cleopatra where its sources live. If you place it inside the site/ directory (as it is intended), and you enable the use of org files to author your contents, then cleopatra documents will be part of your website. If you don’t want that, just move the directory outside the site/ directory, and update the $CLEODIR variable accordingly.

For this website, these constants are defined as followsI will use a comment in the first line to recall to which file a given block code is expected to be tangled. .

# makefile:
ROOT := $(shell pwd)
CLEODIR := site/cleopatra

We then introduce two variables to list the output of the generation processes, with two purposes in mind: keeping the .gitignore up-to-date automatically, and providing rules to remove them.

$ARTIFACTS lists the short-term artifacts which can be removed frequently without too much hassle. They will be removed by make clean.
$CONFIGURE lists the long-term artifacts whose generation can be time consuming. They will only be removed by~make cleanall.

# makefile:
ARTIFACTS := build.log
CONFIGURE :=

clean :
	@rm -rf ${ARTIFACTS}

cleanall : clean
	@rm -rf ${CONFIGURE}

Generation processes can declare new build outputs using the += assignement operators. Using another operator will likely provoke an undesirable result.

Tangling Org Documents

cleopatra is a literate program implemented with Org mode, an Emacs major editing mode. We provide the necessary bits to easily tangle Org documents.

The configuration of Babel is done using an emacs lisp script called tangle-org.el whose status is similar to Makefile. It is part of the bootstrap process, and therefore lives “outside” of cleopatra (it is not deleted with make clean for instance). However, it is overwritten when this file is tangled. If you try to modify it and find that cleopatra does not work properly, you should restore it.

;;; tangle-org.el:
(require 'org)
(cd (getenv "ROOT"))
(setq org-confirm-babel-evaluate nil)
(setq org-src-preserve-indentation t)
(add-to-list 'org-babel-default-header-args
             '(:mkdirp . "yes"))
(org-babel-do-load-languages
 'org-babel-load-languages
 '((shell . t)))
(org-babel-tangle)

We define variables that ensure that the $ROOT environment variable is set and tangle-org.el is loaded when using Emacs.

# makefile:
EMACSBIN := emacs
EMACS := ROOT="${ROOT}" ${EMACSBIN}
TANGLE := --batch \
          --load="${ROOT}/scripts/tangle-org.el" \
          2>> build.log

Finally, we introduce a canned recipe to seamlessly tangle a given fileIt was the first time I had used canned recipes, and I don’t think I had the opportunity to re-use it ever again. .

# makefile:
define emacs-tangle =
echo "  tangle  $<"
${EMACS} $< ${TANGLE}
endef

Updating `.gitignore` Automatically

Assuming each generation process correctly defines its $ARTIFACTS and $CONFIGURE variables, we have all the information we need to update .gitignore automatically.

This is done by adding markers in .gitignore to define a region under the control of cleopatra, and writing a script to update said region after each build.

# update-gitignore.sh:
BEGIN_MARKER="# begin generated files"
END_MARKER="# begin generated files"

# remove the previous list of generated files to ignore
sed -i -e "/${BEGIN_MARKER}/,/${END_MARKER}/d" .gitignore
# remove trailing empty lines
sed -i -e :a -e '/^\n*$/{$d;N;};/\n$/ba' .gitignore

# output the list of files to ignore
echo "" >> .gitignore
echo ${BEGIN_MARKER} >> .gitignore
for f in $@; do
    echo "${f}" >> .gitignore
done
echo ${END_MARKER} >> .gitignore

The ignore rule of makefile is defined as follows.

# makefile:
ignore :
	@echo "  update  gitignore"
	@scripts/update-gitignore.sh \
	   ${ARTIFACTS} \
	   ${CONFIGURE}

Bootstrapping

The core purpose of makefile remains to bootstrap the chain of generation processes. This chain is divided into three stages: prebuild, build, and postbuild.

This translates as follows in makefile.

# makefile:
default : postbuild ignore

init :
	@rm -f build.log

prebuild : init

build : prebuild

postbuild : build

.PHONY : init prebuild build postbuild ignore

A generation process in cleopatra is a Makefile which provides rules for these three stages, along with the utilities used by these rules. More precisely, a generation process proc is defined in proc.mk. The rules of proc.mk for each stage are expected to be prefixed by proc-, e.g., proc-prebuild for the prebuild stage.

Eventually, the following dependencies are expected between within the chain of generation processes for every generation process.

prebuild : proc-prebuild
build : proc-build
postbuild : proc-postbuild

proc-build : proc-prebuild
proc-postbuild : proc build

cleopatra is a literate toolchain whose main purpose is to allow me to turn the scripts I wrote to generate my website into blogposts of said website. As such, it allows me to implement the generation processes using Org mode, which means that before being able to start generating HTML files, cleopatra has to tangle the generation processes.

To achieve this, cleopatra relies on a particular behavior of make regarding the include directive. If there exists a rule to generate a Makefile used as an operand of include, make will use this rule to update (if necessary) said Makefile before actually including it.

Therefore, the rules of the following form achieve our ambition of extensibility.

include ${PROC}.mk

prebuild : ${PROC}-prebuild
build : ${PROC}-build
postbuild : ${PROC}-postbuild

${PROC}-prebuild : ${PROC}.mk ${AUX}
${PROC}-build : ${PROC}-prebuild
${PROC}-postbuild : ${PROC}-build

${PROC}.mk ${AUX} &:\
   ${CLEODIR}/${IN}
	@$(emacs-tangle)

CONFIGURE += ${PROC}.mk ${AUX}

.PHONY : ${PROC}-prebuild \
         ${PROC}-build \
         ${PROC}-postbuild

where

$IN is the Org document which contains the generation process code
$PROC is the name of the generation process
$AUX lists the utilities of the generation process tangled from $IN with $PROC.mk

We use &: is used in place of : to separate the target from its dependencies in the “tangle rule.”Yet another obscure Makefile trick I have never encountered again. This tells make that the recipe of this rule generates all these files.

Rather than writing these rules manually for each generation process we want to define, we rely on to noweb of Babel . We call extends the primitive to generate new generation processes.

We derive the rule to tangle bootstrap.mk using extends, using the following Org mode syntax.

#+BEGIN_SRC makefile :noweb yes
# makefile:
<<extends(IN="Bootstrap.org", PROC="bootstrap", AUX="scripts/update-gitignore.sh")>>
#+END_SRC

which gives the following result.

include bootstrap.mk

prebuild : bootstrap-prebuild
build : bootstrap-build
postbuild : bootstrap-postbuild

bootstrap-prebuild : bootstrap.mk scripts/update-gitignore.sh
bootstrap-build : bootstrap-prebuild
bootstrap-postbuild : bootstrap-build

bootstrap.mk scripts/update-gitignore.sh &:\
   ${CLEODIR}/Bootstrap.org
	@$(emacs-tangle)

CONFIGURE += bootstrap.mk scripts/update-gitignore.sh

.PHONY : bootstrap-prebuild \
         bootstrap-build \
         bootstrap-postbuild

These are the last lines of makefile. The rest of the generation processes will be declared in bootstrap.mk.

Generation Processes

In this section, we construct bootstrap.mk by enumerating the generation processes that are currently used to generate the website you are reading.

We recall that each generation process shall

Define proc-prebuild, proc-build, and proc-postbuild
Declare dependencies between stages of generation processes
Declare build outputs (see ARTIFACTS and CONFIGURE)

Theming and Templating

The theme generation process controls the general appearance of the website. More precisely, it introduces the main template used by soupault (main/templates.html), and the main SASS sheet used by this template.

If a generation process produces a set of styles within a specific SASS files, the current approach is

To make this file a dependency of theme-build
To modify style/main.sass in theme to import this file

Eventually, the second step will be automated, but, in the meantime, this customization is mandatory.

Configuring Soupault

The soupault generation configures and run soupault, in order to generate a static website.

If a generation process proc produces files that will eventually be integrated to your website, its proc-build recipe needs to be executed before the soupault-build recipe. This can be enforced by making the dependency explicit to make, i.e.,

soupault-build : proc-build

Eventually, generation processes shall be allowed to produce specific soupault widgets to be integrated into soupault.conf.

Authoring Contents

The fact that cleopatra is a literate program which gradually generates itself was not intended: it is a consequence of my desire to be able to easily use whatever format I so desire for writing my contents, and Org documents in particular.

In the present website, contents can be written in the following format:

HTML Files: This requires no particular set-up, since HTML is the lingua franca of soupault.
Regular Coq files: Coq is a system which allows writing machine-checked proofs, and it comes with a source “prettifier” called coqdoc. Learn more about the generation process for Coq files .
Org documents: Emacs comes with a powerful editing mode called Org mode , and Org documents are really pleasant to work with. Learn more about the generation process for Org documents

Thomas Letan's Blog - meta

What happened in February 2026?

What happened in February 2026?

Yet Another Claude Code Wrapper

I Built Myself a Cloudlab

What Happened in January 2026?

What Happened in January 2026?

tinkerbell’s First Month

Meeting with Claude Code

New RSS Feeds

I Cannot SSH Into My Server Anymore (And That’s Fine)

I Cannot SSH Into My Server Anymore (And That’s Fine)

Container-Centric, Declarative, and Low-Maintenance

Assembling tinkerbell

Container-Centric, …

Declarative, …

The Proof of Concept

The MVP

And Low-Maintenance

The Road Ahead

What Happened in 2024?

What Happened in 2024?

Free and Open Source Software

Blog posts

$WORK

Talks

Sport

Final Notes

Serving This Article from RAM for Fun and No Real Benefit

Serving This Article from RAM for Fun and No Real Benefit

Embedding My Website in a Binary

Serving the content with Dream

Naive Approach

Handling index.html Synonyms

Supporting Content-Type

Compressing if Requested

Caching

Building and Deploying the Website

Conclusion

The Free and Open Source Software Projects This Website is Built Upon in June 2023

The Free and Open Source Software Projects This Website is Built Upon in June 2023

Authoring Contents

Frontend

HTML Generation

What happened since December 2022?

What happened since December 2022?

Spatial Shell got its first releases

Goodbye Emacs! Remember me, Neovim?

Website redesign, again

What happened in September 2022?

What happened in September 2022?

Spatial Sway

This Website

What happened in August 2022?

What happened in August 2022?

Emacs

Theme Selection Menu

Eldoc and Flycheck Popups

This Website

New Contents

Under the Hood

A New Mailing List

A Literate Toolchain To Build This Website

A Literate Toolchain To Build This Website

Global Constants and Variables

Tangling Org Documents

Updating .gitignore Automatically

Bootstrapping

Generation Processes

Theming and Templating

Configuring Soupault

Authoring Contents

`tinkerbell`’s First Month

Assembling `tinkerbell`

`$WORK`

Handling `index.html` Synonyms

Supporting `Content-Type`

Updating `.gitignore` Automatically