@duggan

Build Everything

2026-03-14T15:35:26.000Z

Claude is changing how I write software dramatically.

My biggest worry, as someone who's been writing software for a long time, is that I will be so blinded by my hard earned intuition on complexity that I will subconsciously be less ambitious than the moment calls for – that some treacherous part of my mind stubbornly knows it's too hard.

When I was 25 I thought it was a given that I would just never stop learning. Back then the risk, from what I could see of middle aged developers, was clownishly bungling your way into some obvious technological cul-de-sac. The intervening 15 years have tested it at times, but I had not considered that the raw intuition itself might end up the problem.

#Combinations and permutations

For the last few years, new companies were really the only time I got to try out new architectural patterns. They become concrete so quickly, and updating them becomes an exercise in changing the wheels on a moving car. Plus, there's always stuff that seems more important.

One of the slightly unintentional effects for me has been the ability to experiment with a variety different architecture and deployment patterns.

For a specific example, one of the projects I'm working on at the moment, rockstar.ninja (saving and sharing Claude Code sessions), has a macOS taskbar application. I've never written one of these before, and it's been my first experience working with Apple's notarization system.

The backend server and CLI are written in Go, so I've just been cross-compiling for Linux and deploying the system using rsync over SSH. This is not too far from how we used to deploy boards.ie in 2008. Even the git repo for this one is just on one of my home servers.

For another project, bewitch.dev (a terminal-based system monitor for Linux), I've gotten to build out the apt repo and multi-architecture build system that I always wanted to have when I started building command-line tools.

This blog itself is something of a continuous project. I started frontend development again in 2024 after our company pivoted, and my blog has been a way for me to explore the space without worrying too much about making mistakes. It started as a Next.js / Supabase project, quickly became an Astro-based project instead, and recently I've been replacing Astro entirely, as it was never quite the right fit.

#I can move through phases more quickly

Discovering what you're building as you're building it is par for the course in software development.

The essential element of all of this is that, thanks to LLMs, it's been possible to iterate rapidly. That rapidity has enabled these projects to reach a level of quality (build automation, tests, documentation) that would otherwise have been hugely time consuming to produce.

It is allowing me to start a variety of different projects, integrating architectural and agentic lessons from each one into each other, combining or discarding approaches and trialling new ones.

Certainly, it has sometimes enabled me to go off on ill-advised tangents, over-engineering some corner of the system before I quite understand it. That is not new though– the difference is that now the cost to correct those missteps has also reduced significantly.

#It's easier to be more ambitious

Being able to iterate faster and correct mistakes faster means I get to consider projects and possibilities that would have been out of reach before.

As a result, I am trying to build everything.

Everything I can think of, every project that has ever sat on the back burner. Any number of ideas for new software, features or fixes might pop into my head a day. If I reckon I have the spare usage to tackle them, they get tackled. I can't even tackle them all with LLMs, but I am sure starting to make a dent.

It's the only way I can think of, in 2026, to try and crack a hole in that calcified intuition and start finding out where the edges are again.

Changelog:

Mar 16, 2026, 9:31 PM — Correct tense.

Building a Stripe dashboard with an ESP32 desktop clock and Rust

2026-02-13T11:27:12.000Z

A few weeks ago I built some custom firmware to turn the Ulanzi TC001 desktop clock into a Stripe subscription statistics and notification doodad.

Here's a fun little simulator that demonstrates the various screens and animations it has now:

This is a WASM compiled variant of the project's integrated simulator that I added so I could iterate on the design without having to flash the device repeatedly. The buttons along the bottom trigger various screens and are just for debugging; they don't appear on the device.

On boot it creates a wireless access point with a captive portal for configuration, like the automatic login page you get with airport WiFi.

To me, this is a perfect demonstration of the power of frontier coding assistants. The activation energy of this project was high, and even then, it allowed me to quickly become more and more ambitious in a very short period of time.

I've had the Ulanzi TC001 sitting doing nothing other than tell the time in the year since I purchased it – another project component doomed to never get any of my time...

#
First pass: AWTRIX and a Raspberry Pi

Initially I started out flashing it with the AWTRIX3 firmware, and running a Node.js service to update it over the network. It was maybe 30 minutes effort to put together, I showed it off to my cofounders and they loved it! We had just turned on the subscription payments system after iterating on the product with early customers over several months, and it was exciting to see people finding it useful enough to actually pay for it.

I thought it would be nice if they could also have one of these, but the fact that you need basically a whole other server to do the custom logic made it a non-starter. AWTRIX is really meant for smart home hackers.

So I had a bright idea: maybe I can customise the firmware? Set it up so it just communicates with Stripe directly?

Then I had a more fun idea: instead of modifying AWTRIX3, a feature-rich C++ project, how about I get Claude to help me write some firmware from scratch in Rust? Perhaps paring it back to the essentials would be simpler than trying to shoehorn my idea into an already complex system.

I had a vague impression that Rust was good for embedded systems development, but hadn't written any before, so this would really test just how far I could get using a coding assistant to build in a language and runtime environment (ESP32) I was new to.

The convenient thing about this project is that it is fairly unambiguous whether the system works or not – plus it helps that the ESP32 boards are difficult to brick^[1], and not too expensive^[2] to replace.

I've been using AI coding assistants a lot over the last few months, and I was still genuinely shocked at how easy it was to get to a basic working state using Claude. However, I can guess at some ideas why it might have been more successful than I initially expected.

Rust – A compiled language that has a reputation for being expressive and thoughtfully documented, with safety features that perhaps makes it naturally amenable to the self-directed feedback loop of agents.
The simplicity of the hardware – the low resolution display and limited features of the system limits the design space. There's a lot you can do with an ESP32, a 32x8 LED matrix and a piezo buzzer – but not that much.

It wasn't without bugs, of course. For example, initially, the screen glitched out continuously:

This turned out to be due to "interrupt latency from WiFi interfering with the WS2812B signal generation in the RMT ISR" – 😵‍💫
It actually looks pretty cool, and I'll have to keep it in mind if I want to generate an effect like that for some other project, but it's just distracting in this case.

Once the features and basic setup were working, I was able to step back and start to think what would make it fun and easy.

#Artwork

I did not have any success creating actual pixel art with OpenAI. ChatGPT can create things in the style of pixel art, but which are actually thousands of pixels in width and height, but I could not get it to build something to the constraints of the TC001 display. Maybe it's possible, but I did not have the patience to find out.

On the other hand, Claude Code Opus 4.6 seems to be quite capable of creating that minuscule artwork, and some of it looks quite good. However, I didn't realize Opus 4.6 could actually create images before I'd already hand drawn most of what I wanted using PixilArt.

#Captive portal

I wasn't really sure what was involved in creating a captive portal. I didn't even Google it before getting Claude to write it, and it turned out to be conceptually relatively straightforward: DNS interception. Your device connects to the access point, and whatever URL it requests, the AP responds with the configuration page.

There are also some magic URLs that the OS checks for, which seem to trigger the familiar "popup" you get after connecting to a network that supports one:

All it really does is save the person setting it up the hassle of knowing what IP to visit in their browser, but it's a detail I really enjoy, since it's one of those technical curiosities that I've briefly wondered about – for however long it took to connect to the WiFi – then forgotten.

The native simulator includes a reasonably accurate replication of the TC001's integrated piezo buzzer, as well as a live Stripe API integration. This was an addition that I just took a punt on once the basic tent poles of the system were working.

From the native simulator, it was a fairly straightforward path to compiling to Wasm, hence the little simulator at the top of the post.

It was fun having a device running in the corner of my office, beeping when a new subscriber arrived, but my original goal was to have a version I could hand to my cofounders. I had ordered another couple of the TC001s on AliExpress, and conveniently they arrived just a day or two before I was due to meet up with David and Clodagh.

This is the point at which I discovered that at some point since I got my own TC001 a year or so back, the manufacturer had apparently decided that 8MB of storage was overkill for a desktop clock, and the new models were shipping with only 4MB of flash memory. This required some slight rejigging of the code – which Claude was more than capable of – ditching my beloved OTA firmware rollback feature.

Another key component is, of course, setup instructions, which I included as a single printed page, with example screens:

David and Clodagh were delighted, and were fortunately both able to get the devices set up easily when they got home, and now we all have little chirping devices to tell us when new customers arrive!

One thing I did overlook was that Clodagh tends to bounce between her home office, and a small office we rent, which means she needs multiple wifi connections configured. Will have to fix that in a future firmware update. For better or worse, I was not able to finish my planned auto-update functionality before handing the devices over. Given how new this is to me I am as likely to brick their devices remotely as improve them, so manual updates from the firmware page will do for now!

PS: I created a tool to create self-contained HTML embeds from Twitter archives while writing this post. You can find it here.

Changelog:

Mar 12, 2026, 10:54 PM — Fix layout issue.

Notes:

Make inaccessible, basically.
A TC001 on AliExpress is something like €35 delivered.

microgpt on the ESP32 – but... why?

2026-03-03T11:17:43.000Z

Yesterday I was looking at the zclaw project, and I thought it would be cool if the ESP32 could run an actual language model instead of phoning out to OpenAI, Anthropic, or some other provider.

Then I remembered that Andrej Karpathy had dropped microgpt a couple of weeks ago, and thought it might be fun to try and get a GPT running on the ESP32. I've got a couple of them lying around from a few other tinkering projects, as well as a functioning ESP32 Rust project to base it on.

I am very much the dog-on-computer^[1] meme regarding this stuff. I have trained and run LLMs for years, but I have not tried writing them. I have the general idea, tokenizers, transformers, gradient descent, yada yada, but they're mostly just words.

With the blog post and my other project as a starting point, it was, however, pretty easy to get to a functional port of microgpt training and then generating a continuous stream of names on the ESP32!

The code is here, and the Claude session that produced the first functioning variant of the project is below:

rockstar.ninja

For a fun technical challenge, and based on our work in ~/Projects/stripe-dashboard, and the informa

opus 4.6 · haiku 4.5 · 92 turns · For a fun technical challenge, and based on our work in ~/Projects/stripe-dashboard, and the information in https://k...

rockstar.ninja

I also had a fresh session of Claude conduct a review, which spotted that the implementation was missing RMSNorm, and filled in the gaps:

rockstar.ninja

Let's do a thorough review of this repository, and evaluate whether it meets the goal of reproducing

opus 4.6 · haiku 4.5 · 48 turns · Let's do a thorough review of this repository, and evaluate whether it meets the goal of reproducing microgpt on the ...

rockstar.ninja

#What's the point?

Well, I learned that training a language model on an ESP32 is something that can be done. I did not know that yesterday. I also found this is not by any means the first or even most interesting attempt. David Bennett used a slightly larger ESP32 variant (1MB of RAM, still minuscule) to spit out 20 tokens a second of much more recognizable "LLM" output. Two years ago!

I think I've learned a little more than I'd have learned reading a blog post from someone else describing how they'd done it. I did a little post-Claude tinkering with stuff I'd remembered from the last ESP32 project (core pinning, RNG).

Does this magically make me able to understand the math? No, I'd have to use my brain more for that, but I've read some of the code, and have given Karpathy's post a closer read than I might have done otherwise.

This was a shower thought that was turned into a working demo. A year ago, I'd have forgotten about it and moved on, or jotted something down in a list of rainy day projects that I would realistically never get around to.

Some people will find this unsatisfying, maybe even a quintessential example of the missed learning opportunity that happens when someone uses LLMs. I'm not sure I even disagree in principle. I just know that I was very unlikely to ever even attempt to do this. There are lots of random ideas that I'll never get around to.

The space of possible ideas is large, and time is finite. Maybe noodling on this for an hour or two will open me up to other possibilities. Too early to tell.

I played video games a lot as a teenager, and watched television, and both of these were going to rot brains. Brains are more resilient than they seem to get credit for.

Changelog:

Mar 3, 2026, 5:02 PM — Fixed a typo.

Notes:

[image: https://duggan.ie/files/7d49752be1352668.jpg]
(I have no idea what I'm doing)

Cognitive debt in AI coding

2026-02-15T10:25:18.000Z

Parachuting into an unfamiliar codebase, where the original author is long gone, is an experience that will be familiar to a lot of developers.

People writing with AI assistants have been encountering this in a new form.

Simon Willison wrote a brief post about it recently, concluding:

I no longer have a firm mental model of what they can do and how they work, which means each additional feature becomes harder to reason about, eventually leading me to lose the ability to make confident decisions about where to go next.

— Simon Willisonsimonwillison.net

Interestingly, this has been my experience in the large codebases of every company I've ever joined. Even with reasonably good documentation, it can be difficult to get to grips with any sufficiently large codebase – say, over a million lines.

This can also be true of smaller systems. If you're new to programming, you will be learning what works best as you go, and so your codebase will change as you learn. Even an experienced developer can make plenty of design mistakes in a domain they are unfamiliar with.

Working with large, successful systems are the circumstances under which code review skills are built. Something true in one part of the system may not hold in another. Experienced developers have their own methods to build understanding, like creating or adding to test suites, extracting microservices, and cultivating the patience, persistence, and humility to read the code.

What's new, though, is experienced developers needing these skills in their own personal projects.

Systems like Claude Code now have an integrated MEMORY.md that they can use for projects in order to persist comprehension across sessions. I am using it and CLAUDE.md religiously in order to build persistent knowledge of the system into each project – but it's early days.

Coding assistants are taking people from idea to working system much faster than before. They are reaching the points at which design and testing become valuable much more rapidly. Not only that, but it's also possible to turn many ideas that might have remained pleasant daydreams into reality, and dreams brought into reality can sometimes turn out to be nonsense.

This may even tie into at least some of the sense of burnout that people have been reporting. It can be comforting and intrinsically rewarding to tinker away on a codebase, but if you're building a business, or at least software for other people, code is just part of it.

It can be quite disheartening to realise that customers won't just appear out of thin air. Building for yourself is fun, but building for nobody is pointless. Claude Code isn't talking to your customers. It's not being thoughtful about the problem. It doesn't have a strong sense of aesthetics.

It doesn't know that what you don't build can be as important as what you do build.

All sorts of people, developers included, are finding out that coding is not software engineering, and that software projects are not startups. This is not new information, but it can take a long time for it to sink in. If people are able to get to that lesson faster, then it's a good thing.

I built a terminal monitoring app and custom firmware for a desktop clock with Claude

2026-02-07T16:17:21.000Z

The way that I've used AI for coding has changed drastically over the last year.

In fact, the rate at which it is changing is probably the most drastic element of it – I can't recall any time since my first year of college, twenty years ago, that I've experienced such a rapid evolution in my own ability to do stuff.

This week I have written a fully self-contained system monitoring daemon and terminal UI, based on the Charm toolkit and using DuckDB. It archives metrics to parquet, shows ECC status, SMART health, temperature, sparklines, historical charts, and even has an alerts system.

bewitch comes in one colour: hot pink.

I am passingly familiar with Go, but this is a project that's been in the back of my head for a while, and would have been a monumental undertaking. It already works well enough, and I'm using it for a handful of servers.

Also this week, I built custom firmware to show Stripe subscription metrics for the Ulanzi TC001. I've linked to a good overview below if you're not familiar with it – basically a cheap and hackable desktop clock.

Blakadder’s Smarthome Shenanigans

Ulanzi Desktop Pixel Clock TC001 Review

As I was trawling AliExpress in search for a decent but cheap photography light I found Ulanzi, a Chinese brand specialized in making video and photography equipment. Browsing their product list something peculiar jumped out in the recommended tab. A desktop pixel clock targeted to YouTubers, the Ulanzi TC001, priced at 59.99$. After various sales and coupons the price dropped down to a very affordable 43$ and that made me click the buy button.

blakadder.com

This is the kind of project I have dreamed about putting together, but I've never found the time required to become familiar with firmware development outside of a few Arduino demos many years ago.

Most of these project ideas go to a list of ideas that I look at and go, "some day, if I have the time." – I rarely have the time. This blog was one such project, and I sat on it for ten years!

AWTRIX3 is the go-to firmware for customizing the Ulanzi TC001, but customization requires running a process on another machine and sending data over the network to the device. I wanted something I could bundle up and send to my other cofounders. So, again, I leaned on Claude Code to create custom firmware in Rust that communicates with the Stripe API, providing a subscriber count, MRR, and notification for new subscribers. It runs a wifi access point that you can connect to and configure, after which it connects to the wifi and communicates with Stripe via their API.

Ironically, given how long generative AI has been threatening art, I ended up having to do a lot of the actual pixel art for the device by hand. Precise pixel art is one area chat models remain mysteriously terrible at.

The Stripe subscription firmware shown here configured with a demo sandbox to test everything out.

I have never written a line of Rust, but I know it is a relatively unforgiving language, and the ESP32 is a less forgiving environment than most I've developed for, with 8MB of flash storage and something like 160KB of RAM.

These are two projects that would have remained on the back burner forever, requiring activation energy that I just don't have to spare. They were both written over the course of a few days, here and there, between other work, and recovering from a cold.

#A year ago

When I was writing the engine that powers this blog in December 2024, I would upload a few files at a time through the Claude or OpenAI web UIs, try to get them to reshape them into something that seemed close enough to what I wanted, and then iterate on that work myself.

This was slow, but the project of putting together a custom editor using Lexical was daunting enough that I would not have attempted it otherwise. At that point I had only about six months of modern frontend development experience and my reach exceeded my grasp^[1].

Then the startup I was working for ran out of runway, we shut down the company, I spent a couple of months learning Japanese, and then went bumming around Japan for a few months with my partner Ash.

Fast forward to August 2025, I'm starting a new company, and coding assistants are starting to generate a good bit of heat on Hacker News.

One of the first things I did after getting back was try to make some headway on my cofounder's MVP, and it seemed like a perfect opportunity to try out Claude Code. I had it write a few helper scripts, add logging, and act as a glorified find-replace in a few areas. For this tedious work it was quite useful, despite frequently giving up or failing the tasks.

I had it write the first draft of a feature that we needed, and iterated on it myself, getting Claude to throw in some fixes here and there.

Actually, it now reminds me of the accounts recorded by the engineers using the first computer being built at Princeton in the 1940s (from Turing's Cathedral, by George Dyson).

Essentially, the ENIAC often produced incorrect calculations, overheated and shut down during jobs, and was generally a hassle to work with. Despite all that, it was still better than doing it by hand, turning what would be months of human calculation into mere weeks of computer assisted work.

#December 2025

By December, I had written one major piece of functionality with Claude Code. Arguably I would have done a better job doing it by myself, maybe in a similar timeframe if I had been really dialled in and had no distractions.

All of my experience was with Sonnet at this point, and while it was useful and sometimes surprisingly good, it wasn't a huge accelerant. If pushed, I'd have said something like 1.5x, maybe. My €22/month usage plan was enough to help me write helper scripts and break ground on new features though, which was already worth it.

At the end of November though, Opus 4.5 had been released, and some time in December I decided to give it a try. It didn't seem massively different at first, but I was still working with it like it was Sonnet – giving it small tasks, writing scripts, etc. It absolutely burned usage though, and until Opus I had never run into a limit before my usage counter reset. I literally didn't even realise there was a limit.

It wasn't until I started asking it to implement features that I found it was making far fewer mistakes, and was in fact producing relatively good first passes.

In October I had begun adding Github Copilot to some pull requests, and it had found a few issues. This was great, even if it came with some mistakes and noise. When you're a team of one and a half developers, an extra set of eyes is absolutely worth the trouble.

Eventually the Co-authored-by: Copilot notes start showing up more frequently in the commit logs, and I found it useful enough to pay for the basic subscription once my free tier limits ran out.

By the end of December, I was hitting my Claude Code limits constantly. I started using "extra usage" which lets you spend a little more to get to the end of whatever was being worked on when the included limits were reached.

I experimented with using GPT-5 and Opus via the Copilot extension included with VSCode. Once I run through the limits there, I start going through extra usage on that.

The point at which Copilot started being very useful.

Using Copilot, I built the first application that I have not read line-by-line, a VAT invoice generator. I needed to generate mock invoices to do some basic interactive testing of the OCR flow for Manano. As long as it generated something that looked plausible, it was fine, but I found that with GPT-5 doing the bulk of the actual coding, I was able to freewheel on ideas about design and local-first software.

I wanted it to be like Tiddlywiki, where it could be used as a file on the desktop as easily as something at a URL. I wanted it to be WYSIWYG rather than a set of dull forms to fill out. And having a bunch of visually distinctive templates to make sure a variety of visual styles would work.

#Christmas break, structured prompts

Over the Christmas period, while Ash was visiting her family, I had the opportunity to get stuck into the feature idea backlog for my blog. This felt like a good testing ground for the coding assistants, as it was a bit cobbled together, had gone through a few architectural lurches, but I had written enough of the codebase myself to evaluate the results.

Also, being a blog, the stakes were low. Every time I'd have some idea for the blog I'd jot it down in Apple Notes. Here was what I had built up:

duggan.ie features/bugs

Saving/updating published posts
When a post has been published, any subsequent updates should include an optional reason for the update.
If a post is published, hitting save or using the save shortcut (Cmd+S) should pop up a dialog with a textbox to describe the reason for the change. This should be plaintext only, no special formatting.
It should still be possible to change without including a reason. In that case, the update should not change the updated_at marker.
The “save” target should move to the dialog box, so that hitting Cmd+S again will save the post.

Changelog
Include the post updates in published posts.
It should be implemented as a collapsed summary + details element at the bottom of the post.
It should also be included in the Atom feed.

Feedback system for shared drafts

Goal: Create a feedback system for shared links.
Context:
Shared links are designed to be shared with a single person. The URLs are deliberately obfuscated and they have configurable expiry, after which they return 404.
The editor is built using Lexical, and stores the lexical node data in the post_revisions table, with a posts table to hold the rendered html and reference to the currently fresh post_revisions record.

Implementation details:
Implement the feedback system as a Lexical plugin.
The shared links can use a Lexical editor with our feedback system plugin.
Other than using the feedback system, the shared link editor should be read-only – the user should just be making notes, not editing the text directly.
Each shared link will likely need to make a copy of the main editor node data on creation.

Open questions:
How best to handle when the main editor updates the post data. Should the shared links be updated? Should the user get a note/bar at the top of the screen saying something like “the author has updated the draft, would you like to refresh?” etc.

Opengraph integration for links
When pasting a link into the editor, it should give me the option to include it as nicely formatted block with OpenGraph data (image, title, content, etc) like Notion.

Video/image loading skeleton
Context: images and videos can be dragged and dropped into the editor, and are displayed inline.
Goal: While the images are uploading, there should be a loading skeleton in place to show that it is being processed.

Enhanced video/image resizing controls
Context: image and video resizing in the editor is very basic
Goal: enhance the resize functionality so that arbitrary resizing is supported.
Additional support: helpful resize controls, like “original”, “full width”, etc., should be included

Light / Dark mode
Initial change to light mode seems to result in a white screen
Continue button flashes when changing, sometimes on loadMake tags distinctive

Tag management area
Include emoji / stickers / SVG images as part of the tags
Should be able to specify a colour for each tag using a colour wheel, etc.
V2
More comprehensive emoji selector (with keyword search)

Post list
Add a new post status: archived
The post list navigation should be broken out by published vs draft vs archived in the left navigation.

It was quite a decent chunk of work in my book.

These notes were originally just for my own reference, but you'll notice that at some point I started editing the notes with a basic structure for Claude Code that I felt was clearer.

I thought I'd make good headway on a few of them, but over the Christmas break I steamrolled every one of them, iterated on a few, and even added some extras once I ran out.

I started out just about coming up short on Claude limits, having to wait 30 minutes or so before starting again. But by the end of this process I was smashing through those limits really quickly, and had to start getting more targeted and careful about what I wanted to work on.

Eventually though, I was paying extra usage on both Copilot and Claude Code, still cheaper than springing for a higher usage plan, but chafing at the limits.

#The Yegge Inflection Point

This month, I finally sprung for Claude Code Max – though only 5x, not yet the 20x. It's just too powerful an upgrade on my capabilities as a developer to pass up. Other people can wait to see where it goes and look back on this period with sagacity and the wisdom of hindsight.

I am still using Claude Code interactively in VSCode, I haven't gotten to the stage where I never read the code that's being produced, though maybe I'll get there, too. Steve Yegge is there with a few other people, and they are probably living in a version of the future, but it's not the only version of the future.

There are lots of different kinds of software. Not all of it will be amenable to this style of development.

For a 20 year old aspiring software developer in college, I have no idea how they are going to get to their version of mastery^[2]. I suspect it will be very different to mine, and will take a very different route. I think it will be daunting, but I hope exciting. Nobody starts off knowing how everything works.

For me, it's exciting. If at the end of the day all I end up with is a bunch of completed side projects, it will have been money well spent.

Changelog:

Feb 8, 2026, 11:21 PM — Fixed formatting in notes.

Notes:

...to paraphrase Robert Browning.
For want of a slightly less pretentious term. Basically I just mean skilled and experienced enough to be useful at their craft. Being able to dive deep, take responsibility, adapt and learn on the fly.

Self-hosting git and builds without running a bunch of web services

2026-01-05T20:59:48.000Z

My main side project at the moment is this blog. I tinker away with it when I feel like it. I'm not working on it with anyone else, not fielding pull requests, and not writing documentation.

That said, I do still like having it in version control. I like having a Dockerfile to encapsulate dependencies and configuration, and using docker compose as a portable runtime manager. It's probably not everyone's idea of a simple setup, but I like it.

The blog is deployed to a small VPS in Hetzner, running behind nginx.

GitHub, Github Actions, and the GitHub Container Registry have been how I've been handling builds, but it's been slow, and it's started to seem absurd to have all these builds occurring in some random datacenter presumably on the other side of the Atlantic ocean, that I am then pulling back to a server in Europe.

I started fishing around for a locally hosted replacement, coming across Forgejo, Woodpecker CI, and OneDev in addition to more familiar names like GitLab and SourceHut.

At some point it occurred to me that this was a lot of ceremony for something relatively simple. How hard could it be just to have a git remote and hang some builds off it? I'm not trying to launch my own GitHub here.

I want to:

git push to a central^[1] repo
When I push, it kicks of a container image build
That image is pushed to an image registry that I can deploy from

This does not need several UIs and databases. In any case git being git, you can always switch out for something more complex later.

#Hosting a git repo

On GitHub, an SSH clone URL looks something like:

git@github.com:duggan/duggan.ie.git

It's an SSH URI just like it would be with scp or rsync. A helpful breakdown from Mike Slinn and Jaditpol on StackOverflow:

    git@github.com:myuser/myrepo.git
    \_/ \________/ \_______________/
     |      |              |
    user   host           path

Since I'm the only user, I don't need to get fancy, and I can just use my own login.

The origin of a git repo is more or less just the contents of the .git directory in a remote location. That's it. You don't even need to run a git server if you're happy enough using ssh for transport.

I put it outside my home path just to keep it a little out of the way, as I won't need to interact with it too often:

sudo mkdir -p /srv/git
sudo chown -R $USER:$USER /srv/git
cd /srv/git
mkdir example.git
cd example.git/
git init --bare

In my case I've replaced my GitHub origin with this one directly in the .git/config of my local checkout, but when I was testing the waters I just added an additional remote:

$ git remote add test ross@buildmachine:/srv/git/duggan.ie.git

#Building an image on push

Git's own hooks system, combined with a Makefile and Docker, is enough to put together a pretty flexible build system for anything you can deploy using a container.

In my newly minted upstream repo, I added a file named post-receive into the hooks directory, i.e., /srv/git/duggan.ie.git/hooks/post-receive (and chmod +x it):

#!/bin/bash

set -e

# Read the push info (branch being updated)
while read oldrev newrev refname; do
    # Only trigger on main branch
    if [[ $refname == "refs/heads/main" ]]; then
        echo "=== Build triggered for main branch ==="

        # Get repo name from current directory
        REPO_NAME=$(basename "$(pwd)" .git)
        WORK_TREE="/tmp/git-build-${REPO_NAME}"
        GIT_DIR=$(pwd)

        # Clean checkout
        rm -rf "$WORK_TREE"
        mkdir -p "$WORK_TREE"
        git --work-tree="$WORK_TREE" --git-dir="$GIT_DIR" checkout -f main

        cd "$WORK_TREE"
        # Check for Makefile and build target
        if [[ -f Makefile ]]; then
            if grep -q "^build:" Makefile; then
                echo "=== Running make build ==="
                make build
                echo "=== Build complete ==="
            else
                echo "Makefile found but no 'build' target, skipping"
            fi
        else
            echo "No Makefile found, skipping build"
        fi

        # Cleanup
        rm -rf "$WORK_TREE"
    fi
done

When I push to the repo, this looks for a Makefile in the root of the repo, checks for a build command and executes it.

My Makefile is super basic, just:

IMAGE=localhost:5000/duggan.ie:latest

build:
	docker build -t $(IMAGE) .
	docker push $(IMAGE)

As a bonus, I could have thrown that post-receive script into a git template^[2] so that new repos are automatically created with a copy of the post receive script, but it doesn't seem necessary just yet.

On the build machine I've also enabled my user account to run docker directly without requiring sudo:

Docker Documentation

Post-installation steps

docs.docker.com

#Hosting an image

At this point the image is built, which will be fine if I just wanted to run the container on the same machine, but I need to deploy this to my little Hetzner VPS.

This is where Tailscale comes in handy, as it lets me have Docker's own container registry running on my build server, which I then pull from on the VPS. It's very straightforward to set up.

On the build server I have a docker-compose.yml file with the registry configured:

 services:
  registry:
    image: registry:2
    container_name: registry
    restart: always
    ports:
      - "5000:5000"
    volumes:
      - ./data:/var/lib/registry
    environment:
      REGISTRY_STORAGE_DELETE_ENABLED: "true"

#Deploying from a private registry

With the registry and VPS both on the Tailscale network, I can allow regular HTTP traffic, which requires a small tweak to Docker on the VPS.

In /etc/docker/daemon.json:

{
  "insecure-registries": ["buildmachine:5000"]
}

With that done, I'm able to update my make deploy command to point at the new registry:

services:
  web:
    image: buildmachine:5000/duggan.ie:latest

This all works much more quickly than before, and since it's running the builds over SSH directly, I'm getting feedback faster than I would refreshing a build log.

Notes:

I code from a couple of different machines, so having an actual central remote upstream makes things easier.
You could probably do a lot of this on just your local machine with a few tweaks.
For example, you can throw `post-receive` into a directory at `/srv/git/template` then configure via the git config:

git config --global init.templateDir /srv/git/template

New Year's Resolutions 2026

2026-01-02T12:30:12.000Z

It was impossible for me not to include this image. I am not sorry.

I was never big on New Year's resolutions. However, as I get older I appreciate that there are natural moments of reset in your life. New decades, new jobs, new homes.

New years are one of the predictable ones. Conveniently, they come with a built in universal counter and even a glass of champagne and fireworks at the end. Might as well take advantage of the infrastructure.

So, I've thought about what I've been doing over the last while that I'd like to continue doing, do better, or do less, and come up with what feels like a pretty achievable list:

Run 5km twice weekly
Weights twice weekly
Eat less meat
Drink less, and less frequently
Read more adventurously
Write every day
Publish every week

Some of these are measurable, some a bit more vague. Drink less, for example. I'll get into my rationale below.

#Run 5km twice weekly

The idea of running 5 kilometres regularly, and trying to improve my time consistently is far more appealing than aiming for a 10k or marathon, etc.

I've had a couple of false starts at running. It seemed pretty simple: leave house, run.

But if you just start running without warming up you can do damage. I'm assuming this is something that changes as you age, and so the first time I started running I ran like I would have run for the bus when I was 17 – except this time I was 30 and sedentary. Instant plantar fasciitis. Could barely walk for a week, then hobbled for months. End attempt one.

So now I've got decent running shoes, and after a slow build up got to a decent frequency of running in 2025, interrupted significantly by my three month trip to Japan with Ash. No such once-in-a-lifetime trips planned this year, so back to a regular cadence^[1] it is!

#Weights twice weekly

I've solved a few health issues just by taking up some regular weight training. Nothing spectacular, 15-20 minute sessions with a bench and some adjustable weights. It's been genuinely life changing though. I've been doing it for long enough that it feels like baseline. If I miss it for a few weeks I can feel my shoulders starting to develop twinges. My main goal there is to not let that happen.

#Eat less meat

This one has been on my todo list for a couple of years. Eating meat has various links to cancer, and eating plants has a lot of positive correlations. I can eat less meat and eat more plants, and hopefully end up healthier overall. I also sporadically feel guilt over an animal dying for my food. Not truly enough to stop entirely, but enough that I would like to be some percentage less part of the problem.

I've already made pretty good progress, but it's taking me time to build up a repertoire of vegetarian meals that I want, and make the time to prepare them. I mostly have porridge in the mornings now, and a vegan soup for lunch. Dinners have remained elusive though, and that's what I plan to improve this year.

#Drink less, and less frequently

A cop-out, you might say– cold turkey or no turkey! But I'm just not convinced that just cutting out alcohol entirely is the best thing for me. I like drinking socially, I just don't like the increasingly long hangovers that result from overdoing it. Being wooly headed from poor sleep, or suffering a pounding headache, is just not a price I'm willing to pay as often. I'll drink on special occasions, or try zebra striping^[2], and basically just make a more concerted effort to wind down my alcohol consumption.

#Read more adventurously

I am an almost embarrassingly single-genre reader, but I've not found myself moved by much that makes the top lists of science fiction for the last few years. I'm probably not checking the right lists. I do still like a well-structured space opera, but my favourite novel in recent memory is The Dispossessed, by Ursula K. Le Guin. I found it gripping – beautifully written, desperately and probably eternally relevant, and a revelatory exploration of anarchism.

It is a book from an author who is considered to transcend genre, and it has made me want to dig deeper to find other novels that require critical engagement, both inside science fiction and in broader literature.

To that end, my first read of the year is M. John Harrison's Light, which is certainly turning out to be a worthy contender.

#Write every day

I'd like to write more, always have, and I keep putting it off^[3]. I'm starting to realise now, though, that not only am I not immortal, but in fact, am increasingly mortal^[4]. Anything I'm not immediately working towards is not likely to happen.

I can do a few things with this information. I can be angry about it, deny it, make my peace with it, or I can get working. Maybe all of those things in order.

#Publish every week

Weirdly I think this will be the hardest one.

About the only saving grace here is that I am a working software developer and have a close and wry understanding that any software which is not released essentially does not exist.

Another lesson is that releasing software is one step of a many-stepped process when building a product. Not even necessarily the first step, depending on how you want to think about it.

Despite knowing this I just don't post anything that feels too incomplete. Yet occasionally I re-read those posts and wonder whether they could ever be more complete than they already were.

Publishing a post feels like a big step, and it is in one sense, but it's also just one step. You can fold in whatever you want after it; sharing the post around, corrections, additions, or responding to feedback/comments.

But the real outcome of publishing a blog post is mostly nothing external. Maybe some people read it, maybe nobody does. But the act of publishing itself is a useful line to draw under it. A way of moving on to the next thing.

Ultimately that's what we get out of a New Year's resolution, too. Draw a line under the last year, and make some space for a change.

Notes:

Pun intended. Running jokes! Ho ho ho. 🏃‍♂️
Zebra striping is when you alternate between alcoholic and non-alcoholic drinks.
Like the black and white stripes of a zebra, this method creates a pattern that helps moderate your drinking. Because of this technique, you’ll find yourself able to still enjoy social occasions that typically involve alcohol.

via drinkaware.co.uk
I decided when I was young that the only chance of succeeding at either writing or software engineering, would be to put all my effort into one at the expense of the other. Software won. Not because I thought it was a hot career, but because I thought it would be easier to get a job with than writing. It was 2003, and software was interesting to me, but not seen as prestigious or valuable amongst my peers.
As far as I know, I'm the only person that pursued software engineering in my entire year of ~150 male students.
Hence the health goals 😅

Moving Cloudflare out of the critical path

2025-12-15T00:34:13.000Z

By way of disclaimer: I really like Cloudflare, I've been a customer and (minor) shareholder for years, and I will continue to use them.

My general principle around infrastructure outages is to stick with the providers that make mistakes. The good ones learn from those mistakes, improve their processes, and improve reliability. Plus I can't even recall the last time a Cloudflare outage occurred before that, let alone took down a good chunk of the Internet. If anything it's a testament to both their scale and remarkable resilience.

However, the extended outage on November 18th was long enough that I started wondering whether I really needed Cloudflare to be in the critical request path for my blog. Mostly in the name of being thoughtful about technical decisions.

During the outage, the only way to potentially route around Cloudflare was using their API to disable request proxying – and this was contingent on your origin server already being set up to handle SSL traffic and being able to handle the increase in load.

Alexander Belanger posted a handy comment on Hacker News detailing the process:

abelanger | on: Cloudflare Global Network experiencing issues

If anyone needs commands for turning off the CF proxy for their domains and happens to have a Cloudflare API token.

First you can grab the zone ID via:

    curl -X GET "https://api.cloudflare.com/client/v4/zones" -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" | jq -r '.result[] | "\(.id) \(.name)"'

And a list of DNS records using:

    curl -X GET "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records" -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json"

Each DNS record will have an ID associated. Finally patch the relevant records:

    curl -X PATCH "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records/$RECORD_ID" -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" --data '{"proxied":false}'

Copying from a sibling comment - some warnings:

- SSL/TLS: You will likely lose your Cloudflare-provided SSL certificate. Your site will only work if your origin server has its own valid certificate.

- Security & Performance: You will lose the performance benefits (caching, minification, global edge network) and security protections (DDoS mitigation, WAF) that Cloudflare provides.

- This will also reveal your backend internal IP addresses. Anyone can find permanent logs of public IP addresses used by even obscure domain names, so potential adversaries don't necessarily have to be paying attention at the exact right time to find it.

This ended up being what I did, with some minor tweaks that I included in the comment thread around using global API keys and checking origin firewall rules^[1].

My blog does not receive enough ordinary traffic to warrant a globally distributed CDN, and since I use LetsEncrypt on the origin server, I'm not relying on Cloudflare for SSL termination.

The two main things I'm using Cloudflare for are caching and security. I'm interested to see how far I can get with my own efforts on caching – I have spent a lot of time fiddling with caching over the years.

Security, DoS protection, etc., are also something I'm familiar with, but not to the point of reproducing Cloudflare's capabilities. Still, I am willing to see if fail2ban with some LLM-curated filters and an aggressive policy against scanners is going to be enough to keep things ticking over.

There are some anti-spam and quality-of-life stuff Cloudflare does too, like email address obfuscation, and JS/CSS/image optimisation. I like email obfuscation in theory, but I drop my public email address everywhere, so I'm not sure it has any practical benefit!

The great thing is that my blog is architecturally very simple, with all the content and images in an SQLite database that is live replicated with litestream, and occasionally manually dumped to my own laptop. It's all running on a €5/month VPS with Hetzner, and if it gets taken down reproducing it isn't a big deal.

In fact I'm still using Cloudflare for DNS, so I can just pop over to the dashboard and re-enable the proxy easily enough. If the DNS fails at some point I might revisit :)

For my blog, I like the idea of having no intermediate proxy between myself or the reader and the server. It's a bit more old school, but also simpler, and aligns with my desire to occasionally reevaluate my default choices.

Developer folk wisdom tells us to use the right tool for the job, but also to use the tools you know, two good principles that can be in tension with each other. It has always felt crucial for me to make sure I am not using familiar tools on the wrong problems though. That is laziness, and not the good kind.

That said, this is not a choice I think I would make in a professional capacity, especially if Cloudflare was handling a good chunk of my CDN traffic. As a passive and inexpensive service, it would need to do a lot worse to turn me off using it. Not a bad idea to have that disable proxy logic written up in a script somewhere though.

If my blog ends up being defaced, or dropping offline from attacks, I will count it as an interesting, and perhaps very cheap, lesson.

Edit, 2025-12-17: updated to include a link to the Hacker News discussion.

Notes:

I had been blocking all non-Cloudflare traffic to the server to stop the drive-by random scans of all IP addresses that otherwise happen constantly.

10GbE

2025-12-12T17:48:42.000Z

I live my life a quarter gig at a time.

After a half-price offer expired with Virgin Media, my 1Gb broadband price went from around €42.50 per month to €85, so I called them up to negotiate a better price. Those new customer offers were my target, but I was also willing to switch provider for a much cheaper 1Gb offer.

Siro (fibre delivered via the ESB network) has arrived in my area in the last month or so, and I figured I was in a reasonably good negotiating position. After an hour or so of waiting in queues and chatting to people, I ended up talking myself into signing up for Virgin's recently added 5Gb package.

Just to be clear, they did not talk me into it – there was no upsell. They gave me a reasonable offer for 1Gb broadband, and I pushed for 5Gb. It was also still about 25% cheaper than what I had been paying for 1Gb.

#Fast 5

Fast cars have never been my thing, but fast Internet? From my teens I have always wanted the fastest Internet, even if it didn't really make much sense. A holdover of those early years sipping 5kB/s over dialup – an unquenchable desire for more speed. Just like Vin Diesel. Maybe. I don't really remember what those movies were about.

In any case, even before I signed up, I knew I was giving myself a small problem: I do not have a single piece of equipment that supports 5Gb networking. Everything I have tops out at 1Gb. My thinking was that this was fine, I would just do some planning and slowly upgrade piecemeal over the next few months. Obviously 1Gb had been more than enough for everything, I had only really called up to get a cheaper price.

Unfortunately as soon as the router arrived, my 1Gb equipment became ancient technology shackling me to the mortal realm.

I didn't realise it, but the 5Gb package is not delivered via the same inconveniently located coax endpoint as the 1Gb. Since that coax was originally intended to deliver cable television, it always ends up being in a living room near wherever a TV might go, which is not necessarily the best place for your router to live.

The new broadband is delivered via a new fibre optic line being routed from inside the apartment building, and so two days later I ended up with a sliver of fibre optic going directly to my office.

This changed things. Instead of running CAT6^[1] through the walls myself at some unspecified date in the future, the termination point was now right where I needed it. The only thing holding me back was... everything else.

#10Gb is not necessarily RJ45

Since 1GB had served all my needs up until this point, I actually wasn't very clear on what happened beyond that. The last time real networking hardware was relevant to me – rather than the abstract concept of a network you get via AWS – was the late 2000s, and 1GbE was good enough for the rack at the time.

I was pretty sure that the next step change from 1Gb ethernet was 10Gb ethernet, but there is a halfway house, in fact more of a quarter-way house, between them: 2.5Gb.

Why 2.5Gb? Well, 2.5Gb still runs on CAT5e, which was cheap and widely available for much of the 2000s and 2010s. When your network cards were maxing out at 1Gb anyway, what was the point in paying more for CAT6? Why future-proof for a 10Gb world when your network cards are a mix of 100Mb and 1Gb and your Internet connection is maybe ~25Mb? I still had heaps of old CAT5E cables I cleared out at the start of this year.

Today, the networking hardware to handle 2.5Gb is actually more widely available in consumer devices, though not at all ubiquitous. The most recent M4 Mac mini can be upgraded from a 1Gb port to 10Gb, but I don't recall seeing an option like that on any machine I've bought for nearly two decades? Even my 2008 unibody MacBook, practically a museum piece, had gigabit ethernet as standard!

So 2.5Gb is a big speed increase over 1Gb for a moderate price increase, and will work if you've got CAT5E cables in the walls for some reason.

10Gb is different.

Not only does 10Gb need at least CAT6 cabling, it actually requires a decent amount of energy to operate, which means more heat, more expensive components, and potentially active cooling (i.e., fans).

At 10Gb, networking enters a transitional phase where you can use either copper cabling or fibre optic, with the latter being amazing for low-latency, long-distance, low-interference transmission of, like, hundreds of gigabytes per second. As you might imagine, fibre optic, being a way to transmit photons instead of electrons, requires a different connector than good old 8-pin RJ45^[2]. But to help with the transition, there is a clever solution: a hot-swappable modular interface called SFP+, basically an adapter for different types of network interfaces.

Depending on your hardware, you can plug optical or copper cables into ports that support these transceivers^[3].

Presumably, none of this is new if you're a network engineer, but it was new to me and pretty confusing.

Wherever you look on Amazon, you mostly find switches that are a mix of 2.5Gb RJ45, 10Gb SFP+, and only occasionally 10Gb RJ45. If you want to go from an eight-port gigabit switch –which you can buy for €20 – to an eight-port 10Gb switch, you are talking about actively cooled hardware costing anything from €500 up.

I ended up reading a bunch of stuff on ServeTheHome.com, which seems to have great breadth and depth into this particular niche of not-quite-home-not-nearly-enterprise hardware.

One of my main takeaways was that it's a lot easier to stick to a reasonable budget if you're not set on more recognisable brands like Zyxel or Netgear. In my case, I decided getting 10Gb on my primary home server was probably enough, with other equipment running on 2.5Gb, and the rest via WiFi.

Winging their way to me are:

A MokerLink Ethernet Switch with 2x10G SFP, 4 x 2.5G Base-T Ports^[4]
A Binardat 10G SFP+ PCIe Network Adapter^[5], to handily eclipse the capacity of the two gigabit network ports in my aging-but-durable HP Proliant Microserver Gen8.
A 10Gtek 10G SFP+ to SFP+ Direct Attach Copper cable^[6]
A QSFPTEK 10GBASE-T SFP+ RJ45 Transceiver^[7]
A UGREEN USB C Ethernet Adapter, 2.5Gbps^[8]

I mean, even getting 2.5Gb to most of the machines would be a huge step up – this is a 5Gb connection, so two of those machines could go flat out together, which is wild.

UGREEN is the only brand I'd even heard of beforehand, and even that's a pretty new one.

I'm interested to see how it all fits together. So far, this hardware is just pending orders waiting to be delivered, but at least some of my Christmas holiday period is going to be spent wiring this stuff up – I'm looking forward to it!

If you're a network engineer, or just an enthusiast who spots something wrong, please do let me know!

Edit, 2025-12-17: updated to include a link to the Hacker News discussion.

Notes:

CAT6 networking cable is made with copper, and enables transmission speeds up to 10Gb/s up to around 50 metres.
A subsequent standard, CAT6a, extends that out to 100m.
These cables use RJ45 connectors, which have been around since the 1970s.
[image: /files/b5f50cc9941698a0.jpg]
[image: /files/97254ce0bd542f47.jpg]Hello there!
Because they can be transmitters and receivers!
[image: /files/4db7c66eb5a6c98e.jpg]
[image: /files/192277070fad4f9a.jpg]
[image: /files/2cd22700bb4975e8.jpg]
[image: /files/a0842d386776f9b6.jpg]
[image: /files/02aad2dc602b339d.jpg]

A year of not really blogging

2025-12-14T21:40:19.000Z

A lot of drafts.

Short posts I should have just hit publish on.

I did not even publish enough posts to make my default pagination hit the second page^[1].

I did have a great year though, including three months in Japan in which I was only rarely tempted to blog, and now almost wish I'd put the effort into. There's a couple of stub posts and notes, but my main instrument was really the camera. I didn't feel like cracking out the laptop to jot down my thoughts most evenings. I didn't even have it with me for weeks at a time as we went bikepacking^[2] across^[3] Hokkaido^[4]. Maybe a retrospective photo blog?

I helped wind down the last company I worked for in January, then I started a new one.

When it comes to writing though, even with the blog, I mostly did what I usually do. I wrote up comments on Hacker News and deleted them before hitting submit.

I jotted down vague ideas for posts in the Notes app – though I did more of this in the blog editor. Looking back over the last year of them, it seems I still can't shake the occasional desire to comment on global affairs/politics. Maybe I should just write these articles up fully and never publish them, just to get the ideas out of my head; and practice writing.

I've really enjoyed working on the blogging software itself, not that I've spent a huge amount of time tinkering with it since January. The original risk I anticipated was that I would agonize over building the blog in and then never even start. I forgot that anything that is not easy to do is something you have to put continuous, deliberate effort into.

So what to do?

The fact that I've written so little makes me wonder whether I even want to write? Surely I would be making the time! I would have pages and pages to show for the amount of time that has passed.

I still believe writing well is an incredible talent, even more so in a time where mere lexical coherence is no longer a sign that a human being has been thinking somewhere.

The fact that I'm writing even this is probably enough of an indicator that I still want to keep doing it.

I guess I should return to Jeff Triplett's words that started me back blogging in the first place:

You don’t have to change the world with every post. You might publish a quick thought or two that helps encourage someone else to try something new, listen to a new song, or binge-watch a new series.

Maybe they'll sink in this time.

Notes:

Actually the pagination count was showing something like three pages for a good while due to a bug in the pagination code, but I only noticed that this last week 😅
[image: /files/b69a6dfcb09acf56.jpeg]
[image: /files/7e30dc907810028c.jpg]
[image: /files/35d3a47621e45897.jpeg]

Sync new purchases to iPod Classic

2025-10-30T17:13:12.000Z

I recently refurbished an old iPod Classic, and purchased some albums in the iTunes Store (yes, it still exists!) with the idea of trying what counts as oldschool in the 21st century – listening to music on something that doesn't also receive email^[1].

Once I found out that most iPod Classics are capable of playing Apple's lossless format, ALAC, I really wanted to sync them over to experience this heretofore unimaginable audio clarity^[2].

However, even though I could download them, the albums refused to show up in the sync list. Switching back to AAC worked fine, but ALAC was not working.

Turns out iTunes itself does not provide lossless downloads.

Because I also have an Apple Music subscription, the lossless versions of my albums were being downloaded, but in the protected .movpkg encrypted format that only works with Apple Music.

So the only way you can sync all your iTunes purchases is setting 256kbps AAC:

Another hiccup is that Apple recently removed some iPod sync support from MacOS Sequoia (15.4.1).

This isn't a showstopper for me as I have Macs of various vintages running everything from OS9 to Ventura, but it's an annoying thing for Apple to do right as iPods are having something of a renaissance.

There is a reported workaround that seems to work for some, if you happen to run into this.

As an addendum, here's a photo of my 4th gen classic, refurbished with a new battery from AliExpress^[3], and the iFlash ATA1 microSD adapter.

Notes:

Zawinksi's Law:
"Every program attempts to expand until it can read mail. Those programs which cannot so expand are replaced by ones which can."
-- James Zawinski, 1995
Only being slightly sarcastic here.
As I understand it's really only trained listeners on extraordinarily high end equipment that can tell the difference between a high bitrate mp3 and lossless.
Even then, my audio setup for the iPod involves using a 3.5mm to lightning adapter for my AirPods Max, which does involve some re-encoding.
🤷
AliExpress sellers frequently appear and disappear, so I can't link to the exactly battery I bought, but if you search for something like "3.7V 1400mAh ipod classic 4th gen" it should get you in the right direction.

VAT invoice generator

2025-11-19T08:35:56.000Z

I needed an invoice generator to quickly produce some random test invoices while building Manano, as part of a feature letting tradesmen track receipts by sending photos to our WhatsApp number.

I tried a few invoice generators that showed up in Google results, but most required either registering an account or were awkward to use.

Eventually I realized it would probably be straight forward enough to whip one together, and so here is my own VAT invoice generator!

You can add line items, it calculates tax, totals, etc.

Since I wrote it for testing a vision-based pipeline, it has a bunch of visually distinctive templates with pre-populated data and a randomzier to produce different figures and line items.

When you make changes, they are saved locally in your browser, so there's no services to host, and you can even download the page and use it locally. It loads html2cavnas for generating the PNG remotely, so it can't work entirely offline, but nothing leaves the browser.

Anyway this was fun to throw together, and might be useful to some other folks. The basics were done pretty quickly, and then I've sort of been doodling away at it every now and then for the last couple of weeks.

Fixing a problem at 40 that stumped me as a 10 year old

2025-09-03T16:12:20.000Z

A few months ago my parents gave me a box of my stuff they’ve had variously in attics and storage since I moved out in my early twenties.

One of the things in it was my Sega Mega Drive (called the Genesis in America) — boxed, and with games and accessories. Unfortunately, I didn't have a TV that I could connect it to! The only connector packaged with it was designed to plug into the aerial socket of a CRT television.

In the last week however, I've gotten hold of a CRT television after a bit of digging around^[1]. I hooked it up to the Mega Drive, and incredibly, it worked! Now, I did had to read the manual to figure out how to dial the receiver channel in 🥲

Channel 36! UHF scan! This is not how I'm used to thinking about screens anymore.

I'd plugged in one of the Mega Games cartridges that originally came with the console, with Golden Axe, Streets of Rage, and Revenge of Shinobi. It was amazing to watch the menu come into focus as the channel dialled in, turning first from the noise of the CMB to jagged lines, then resolving into the blinking menu.

Tuning into channel 36 😎

Initially though it was a little temperamental — if the controller wire pulled at it, or if it was nudged at all, the console would reset. I eventually remembered that I stopped playing it when I was a kid partly out of frustration at this exact problem. The Mega Drive does not come with any built in storage, so game cartridges themselves had to support that functionality. At ten years old, there was nothing quite so frustrating spending an hour playing a game and have a nudge reset you to zero.

Thirty years later and with various gadget repairs and upgrades under my belt, I don't feel so helpless 🙂 I opened up the Mega Drive – at ten it probably didn't even occurred to me as something I could do – and immediately spotted the problem: the solder connecting the power socket to the motherboard had cracked. All I needed to fix it was to resolder the joints, and now it’s as good as new!

I was honestly just a teensy bit emotional. It's not the most astounding technical achievement, and it's not going to make a difference to anyone else, but it feels a little like I've been able to help that ten year old version of me.

On the other hand, thirty years has not made me any better at Revenge of Shinobi.

#Footnotes

The difficultly of getting hold of a CRT television in 2025 was a real surprise to me!

Japan May 2025 – Hokkaido and Kyushu

2025-06-03T13:56:04.000Z

First few weeks of our Japan trip were fantastic. Despite some minor confusion over our visa length on entry^[1], we had a great start in Sapporo, with nice weather and friendly people.

In our first two days, two different people stopped to talk to us, one older gent just to ask where we were from and if we were enjoying our visit, and another young chap from a local college who wanted to practice his English. He was doing this almost daily with different strangers who looked like they might speak English in the park! Impressive.

We were also lucky that cherry blossoms were still in bloom in and around Sapporo!

I was also introduced to what has been my favourite beer of the trip so far, Sapporo Classic! Unfortunately I found out only after we flew down to Kagoshima that this beer is only sold in Hokkaido. Sayonara, Sapporo Classic. You were taken from us too soon 🥲.

Since I'm writing this while staying in Hakata, it feels sacrilegious to say this, but the best ramen I've had on this trip was a place we randomly walked into on our first day in Sapporo, Yoshiyama Shouten in Tanukikoji.

Notes:

1. Don't put 90 days into the electronic visa system – apparently the boundary checks are for < 90days, not <= 90 days 😅

Goodbye Hokkaido, next stop... Okinawa?

2025-04-03T10:45:48.000Z

We've been going over the pros and cons of the current route, and have decided that the V-shaped travel route is not our best option.

Discussed in my previous post, the V-shaped route was intended to start us in cherry-blossom season, take us down to Osaka for a few weeks, then Yakushima, and then slowly back up north. On further examination there are a few of problems with this.

First, we're planning to spend our initial week or so in Hokkaido, which actually leaves us with maybe ten days to get down to Osaka. That's a lot of interesting territory to cover in only a week! Also, while we'll be in Osaka itself for a couple of weeks, Ash will be preoccupied with exam preparation, leaving me exploring Osaka largely by myself.
After Osaka, the plan would be to head to Yakushima, then back up to continue the rest of the trip.

So, new plan!^{(Until the next plan)}

Hokkaido → Kagoshima → Okinawa Image credit: JNTO.

We'll still start with a week or so in Hokkaido, visiting Lake Toya, Hakodate, and renting a car for a day trip to Matsumae a bit further down the coast. This part of the trip is strongly influenced by a lovely Japan Guide video on a two day trip from Sapporo to Hakodate.

Matsumae Castle, Hokkaido. Image credit: JNTO.

Hakodate, Hokkaido. Image credit: JNTO.

Once we've completed our mini Hokkaido tour, we'll head back up to Sapporo, catch a flight to Kagoshima (flights are inexpensive), spend a few days there, then take a short ferry to Yakushima island for four days of hiking around the forest island that inspired Princess Mononoke.

Ferries and car rental for regional islands aren't really available through the usual providers you might use, like booking.com, etc, but honestly not that difficult to figure out.

For car rental we're using Yakushima NAVI (personally I am very much looking forward to my first time driving a keicar), and you can book a hydrofoil to/from Yakushima with Toppy & Rocket.

Kei car! Photo By Tokumeigakarinoaoshima - Own work, CC BY-SA 4.0, https://commons.wikimedia.org/w/index.php?curid=85137674

When we wave goodbye to Yakushima, we'll make our way towards Okinawa to camp out for Ash's exams for a couple of weeks. Once the exams are over, our travel arrangements will be a lot more flexible, and we can stick around, fly, or ferry our way back to Kyūshū.

We actually originally planned to start our trip in Okinawa and work north, but were drawn to Hokkaido by the chance of catching cherry blossom season.

#Kyūshū

With a more relaxed itinerary, it will be nice to have the option of dropping into Aso-Kuju National Park on our way up towards Fukuoka.

Aso-Kuju National Park. Image credit: JNTO.

One of the things I'm most looking forward to about Fukuoka is the chance to visit the home of tonkotsu ramen, where the talented Cork chef Takashi Miyazaki hails from.

The only wrinkle in the south-to-north itinerary is that it sort of coincides with tsuyu (rainy season):

Region	Start	End
Okinawa	May 8	June 23
Southern Kyushu	May 29	July 13
Shikoku	June 4	July 17
Kansai (incl. Kyoto)	June 6	July 19
Kanto (incl. Tokyo)	June 8	July 20
Northern Tohoku	June 12	July 27

Realistically though there's no way to avoid rainy season when traveling during the summer months. Plus, coming from Ireland, we are no strangers to rain 😅 Warm rain even sounds like an upgrade!

Since regional flights appear to be relatively inexpensive, it may even just make more sense for us to hop around a bit more rather than trying to make everything fit into train journeys. The more I see of Hokkaido through various YouTube videos the more time I want to spend there. We'll definitely have to head back there when the weather is warming up.

Preparing for the Japan trip

2025-04-11T21:23:51.000Z

As I wrote about in February, Ash and I are traveling to Japan for three months (May → August). It's a trip I've always wanted to take, and since I'm between work engagements I've been taking some time to prepare.

Three months is a long time to spend in a country you've never visited, and I'm going to go over a few ways we've been preparing.

#Skipping the detailed itinerary

We've decided that a detailed itinerary does not make sense over a three month period. This runs counter to a lot of Japan travel advice that I've read or watched, but it seems likely that this advice is geared towards people who have a two week trip and want to squeeze in as many highlights as possible.

If you read reddit, or travel blogs, or watch various YouTube videos, much of the prevailing advice on traveling to Japan is to book everything from accommodation to events months ahead. Ghibli Park sells out months in advance, accommodation can be hard to find during peak season, special discounts are only available months in advance, etc.

Historically, this is not how Ash and I have enjoyed traveling. Sure, there are one or two things that we'll plan in advance for, but otherwise we'll be happy to go off the beaten path rather than queue for the most popular attractions.

An itinerary so long and detailed would become a straitjacket, sucking all the fun and serendipity out of the trip. We want to have the flexibility to allow for chance and discovery. No matter how much research we could do ahead of time, once we're on the ground we will undoubtedly start to find people, places, and opportunities that no amount of preparation could account for. We spent some time figuring out the high level shape of our trip, with a handful of specifics planned, then will handle the rest as we go.

We're prepared to camp or even head to another country for a bit if the relaxed plan isn't working out. I doubt it will come to that, but it's been a relief to realize that ultimately we can just peace out and go somewhere else if it's not working 🙂

The only specific dates we've nailed down so far are flights and accommodation around our first week upon landing in Japan, and then later a few weeks accommodation in Osaka around Ash's exams.

That doesn't mean we're going unprepared, though. I've gotten an International Driving Permit, have been learning Japanese, and roughly sketched out what the trip might look like, as well as booking a few key accommodations and event tickets (e.g., Expo 2025 in Osaka).

The general idea is a sort of V-shaped itinerary (below), in which we start in the north (Sapporo, Hokkaido) during spring, head down to Osaka for a bit, then proceed to Yakushima, maybe Okinawa, and then make our way north to Hokkaido again as the summer heats up. This really depends on how we're feeling about the weather – I think I'm relatively comfortable in high heat and humidity, but we'll adjust our plans as needed.

It's a bit odd maybe, but Japan's public transport infrastructure is what has made it possible to even consider a zigzagging plan like this. This is not how I would travel around South Africa, for example – you'd be driving and flying everywhere.

Given the season, duration, and availability of public transport, this seems like a plan that will let us visit a lot of places, as well as make return trips or catch things we may have missed on the southward leg.

We're starting off in Hokkaido, since it turns out the dates we booked to arrive coincide with the peak of the cherry blossom season there! Map via japan.travel.

We also want to do some hiking – maybe the Kumano Kodo, though there's no shortage of places to walk – and even camping if the opportunity arises!

#Researching a trip in 2025

In terms of research, I've been watching a lot of Youtube videos. Like, a lot. There are a ton of recent and detailed guides put out by a variety of native Japanese, as well as foreigners who have been living in Japan for years. Back when I first considered a Japan trip the best option was an infrequently updated Lonely Planet guide. I was fishing around for a while looking for that guide again before I realized that it was the year 2025 and I was being a moron.

Something else I learned is that the Japan Rail Pass, which used to be practically a no-brainer for foreign travellers, is less of a no-brainer now since price increases in 2023:

For most first-timers to Japan, whether the JR Pass is for you is quite a simple question to answer. It usually boils down to whether you’re traveling to another major city after going from Tokyo to Kyoto via the Shinkansen (bullet train).
In other words, you need to be taking at least three Shinkansen rides in a 7-day window.

Frankly, the Japan Rail Pass probably didn't even make sense for our trip before the price changes. Three months slowly meandering around the entire country is not what it was designed for.

Just to call out some of the YouTube channels I found most useful:

Kensho Quest – detailed and up to date information on the practicalities of traveling to Japan, from what to pack, how to get around, and what to expect by season.
Toshi Guide – (maybe unintentionally?) hilarious with lots of dramatic stock footage, Toshi gets into the details of how travel to Japan is changing over the last couple of years, as well as specific details on things like smoking bans in Osaka, improving border control, and avoiding tourist traps and scams.
Japan Guide – wonderful mini travel documentaries in which someone takes a short trip to some part of Japan, showing some highlights and transport options. Great inspiration for places to visit.
Mrs. Eats – intentionally hilarious insights from a Japanese woman on Japanese culture, and nerdy things to do when in Japan.
Japan By Food – so many amazing looking restaurants to visit everywhere 🤤
Shohei Kondo – Shohei reviews and critiques the videos that various gaijin (foreigner) influencers produce about Japan. Really great to have another perspective on popular TikTok and YouTube videos that otherwise might have you worried about visiting Japan.

#Backpack or suitcase? 🎒か🧳？

Both of us like traveling light. For me there's a Tetris-y, technical optimization element to it – I like to pack as much flexibility as possible into as few grams and items as possible. For example, making sure most devices are USB-C, or using my laptop as a battery pack instead of bringing a separate power bank.
Ash is the true backpacker type – by which I mean she'd happily throw a toothbrush, change of clothes, and running shoes into a rucksack and traipse around India for a month.

We'll both have real-life things to accomplish during this trip – Ash will be doing exams, and I'll be coding, writing, and keeping up with Japanese study.

At the moment, backpack is winning out. We'll be moving around a lot, and ideally to less-traveled places, which means relying on takuhaibin seems awkward. Plus, if we're wrong it seems easier to bump up to a suitcase trip than it would be to downsize to a backpack trip.

#Learning Japanese 🇯🇵の📚

Ash is a bit too busy doing concurrent qualifications in both art and quantum physics (😵‍💫) to also learn a language, so I'll be the one attempting to learn enough of the language to be polite and navigate food, transport and accommodation.

While years of watching anime has given me a smattering of vocabulary and some familiarity with pronunciation, it's a whole other thing to converse in real time, read, and parse numbers.

I've been attending a weekly class in Portobello, which has been an excellent starting point, and is a good place for practicing and keeping me accountable.

I'm using Pimsleur's Japanese audiobooks to drum in sentence construction. I'm not sure these are as well known as I thought they were (maybe it's a bit old-school and expensive in 2025), but I've found them a good accompaniment to the regular classes. Sitting there for 30 minutes each day trying to build sentences before the recorded response kicks in has been a great motivator.

I'm also using Anki, which I'd heard of but never used before. I'm using a premade "deck" of 1500 basic vocabulary words to try and boost my vocabulary at the same time as maybe helping me parse signage, documents, etc. while I'm in Japan.

Including hiragana/katakana practice and other comprehension exercises, all of this adds up to a couple of hours day of deliberative effort. Hopefully it pays off.

I can imagine a version of this whole thing that is more targeted at my specific requirements, i.e., navigation, food, transport, and accommodation, but I'm willing to press on in the hopes that it will leave me with some basic level of preparation that I can improve upon when I'm actually in Japan.

Traveling to Japan for three months because life's too short

2025-02-10T16:49:16.000Z

I've been fascinated by Japan since I was a teenager. Thanks to Hayao Miyazaki (among others) the food, landscape, and architecture all exist in some dreamy, liminal space in my mind alongside wood sprites and lost civilizations.

Maybe it sounds daft, but the idea of actually visiting the country always seemed like it would break the spell somehow? Like anywhere, Japan has crime, social problems, bad weather, and if I go, me.

Same sad you.

That said, I've had a plan (concepts of a plan 👐) to visit for years. I've recently dug out an old copy of Rough Guide to Tokyo that dates from 2011, which was the first time I started vaguely planning to go.

However, that was also the year I started working for Engine Yard, which changed the entire trajectory of my career. This was a huge deal for me, but Engine Yard landing in Dublin was also a big deal for the local startup community – Silicon Republic had an article in 2013 that gives a bit of a retrospective.

Plans to visit Japan went on the back burner.

#Fast forward a few years

Speaking of back burners, in 2019, I was burning out at my job. This was well past Engine Yard, which I had left in 2014. Our startup had been acquired, and corporate bureaucracy was slowly draining away my will over the subsequent three year earn-out. There were plenty of smart and thoughtful people around, but somehow I felt like I was getting stupider.

The work was the most mind numbing drudgery. I had begun to hate writing software, and was terrified that if I didn't leave, I might never recover my enthusiasm.

Then sometime in early 2020 I read a series of blog posts by someone who had cycled the length of Japan, and it rekindled those old plans, but now on a grander scale. This was something I could aim for – I was going to cycle the entire length of Japan.

Clearly this was a huge "my life is derailing, I must escape" signal, but my girlfriend was having a similar crisis and so we agreed on the broad strokes of a New Zealand / Japan cycling tour, taking six months or so to do the whole thing. We both had enough savings to take an extended break from work. I started cycling training in earnest.

On March 1st 2020, I handed in my notice – this was going to be the year I did Japan.

RTÉ News from March 19th, 2020.

As COVID-19 wore on, it became increasingly clear that there would be no Japan trip. I finished out my notice period, and it would be almost a year before I felt like I could write code again professionally. I spent the intervening time doing not very much – I exercised, lost weight, went for long rambles in the Phoenix Park. Visited South Africa while there were still travel restrictions – that was memorable – had to get "war zone" travel insurance as it was the only option that would provide cover during the pandemic.

While I was in South Africa in 2021, David Coallier called and asked me to join as CTO of his new company, Clearword. I was ready to let go of Japan – I didn't want to spend another year on the sidelines, and so I joined David on what ended up being the most interesting and, hilariously, least personally remunerative startup we've done together. We had customers. We talked to them. We zeroed in on a niche. It felt really close to being something – but it never quite got there.

So it goes.

#2025, the year we make contact

And so here we are, in 2025. I am unemployed but am not immediately looking for work.

Emotionally though, things could not be more different.

I was disappointed about Clearword, but the writing had been on the wall for a while, and I came to terms with it months ago. I'll write that all down another time, but the gist is that I am feeling ready to start something new.

I am also turning 40 this year. Life moves pretty fast, and while I feel fitter and healthier today than I did ten years ago, I have to acknowledge that time is passing, and if I put this off now I may not have the opportunity again for a long time. And it's not just my own calendar that has to line up, but that of my girlfriend.

I also no longer feel the need to find myself by cycling the length of a country I've never even been to. I don't need a grand goal. I am going instead to soak in it. To be in the place and take it as it is. I want to do it peacefully and respectfully.

There are places I want to visit, of course – Yakushima island, the inspiration for the ethereal scenery of Princess Mononoke being top of my list.

Photo by Takeshi Kuboki, via Flickr.

Climbing Mount Fuji seems like it would be neat, if it works out, but mostly we both want to go off the beaten path, and avoid bustling around in crowds gawping at geishas, etc.

So – flights are booked. We are going for three months, start of May to start of August. We've booked our flights to arrive in Seoul rather than flying directly to Japan, as it gives us some options on whether we want to go north or south to start (regional flights from Seoul are relatively cheap). North, to Hokkaido, is sort of appealing with the chance of catching the sakura blossoms, but Yakushima is in the south, and it will be better to do that before summer gets into full swing.

In the mean time, I am attending evening classes in the city to learn hopefully enough Japanese to get by. Thanks to years watching anime, I have a surprising amount of vocab floating around in my head, if not all of the practical variety. This week I managed to write out my basic hiragana table from memory, which feels impressive, yet is just the tip of the iceberg.

Three months sounds like a long time, but anyone I've spoken to tells me however long they spent, it wasn't enough. We'll be traveling light and keeping our plans loose, and we are going to have some adventures.

Can't wait. 🇯🇵

Sources

Yakushima photo by Takeshi Kuboki, via Flickr.

Hacking together a Job Runner using Supabase Edge Functions

2025-02-11T00:00:22.000Z

If you're not familiar with Supabase, it's a collection of backend services (Postgres, PostgREST auth service, S3 storage, function runtime) that you can develop against locally and then deploy to production.

The Supabase team have also spent time making each of these parts complement each other, and since they're stitching together different open source projects this is seriously impressive. They also have in-depth documentation and examples, and the dashboard is top notch.

ℹ️ What makes Supabase so useful?

For example, items uploaded to the storage service are accessible via the database. The auth service is also hooked directly into the database, with convenience functions to wire up user permissions to the authenticated users. This means you can enforce object storage access permissions (using Postgres Row-Level Security) all the way through the stack via the database:

create policy "Individual user Access"
on storage.objects for select
to authenticated
using ( (select auth.uid()) = owner_id::uuid );

Additionally, the database is presented via a REST interface using PostgREST. With the aforementioned RLS policies, this gives you a permission-controlled API that you can auto-generate clients for. That means a React application can have a type-hinted, robustly authorized interface to the database – this makes it easier to build systems that are both secure and have a nice developer experience.

This is powerful stuff, and not necessarily easy to grok, but ultimately you're just learning how to use Postgres, so the knowledge is portable.

Anyway, this is all great stuff, but at some point I wanted to be able to run a bunch of asynchronous work in the background.

#Background jobs

What you need out of a background job runner varies wildly. Supabase provides some helpful primitives around this that are enough to get started with – you can fire off Edge Functions after a request and set them to process as Background Tasks, and you can use pg_cron to run them on a schedule.

If you just want to run a few static tasks regularly with Supabase, send emails, or fire off an API request after a user action, it's pretty straight forward. There are also ways to set up triggers, and fire webhooks on database events.

What I needed was a system where I could regularly run tasks in the context of a user – AI agents running on behalf of the user, checking third party services for new information, etc. Something which might take a while to run, or is part of automation that will trigger another action, maybe alert a customer.

I wanted to be able to queue up sometimes thousands of jobs to run – this would help me stagger their execution so that I wasn't overwhelming either the Supabase Edge Function dispatcher or my own APIs.

It was also important to me to keep the overall infrastructure stack as lean as possible, because I was deploying a stack per-company to keep resources isolated, as well as geographically proximate to the people using it.

There are, of course, third-party job runner systems like Inngest, Hatchet, trigger, or Temporal, some of which are open source, have UIs, a local dev system, and I'm sure lots of other useful features. But this is a class of problem that ranges from "Google Calendar reminder for me to run a script manually on Sundays" to "distributed MapReduce operation across a Kubernetes cluster" – you'll want something that suits your own circumstances.

#Cobbling together a job runner

The Supabase Edge runtime environment takes the form of Deno functions triggered via HTTP, and authorized using JWT. They are normal HTTP API endpoints, you can send payloads to them, stream results and return status codes.

Supabase also provides a PostgreSQL database with a variety of Postgres extensions installed, including pg_cron and pg_net.

With those pieces in place, we have the primitives for a system that can:

store a list of jobs and config
run Typescript functions (with some resource limits, see Caveats)
run tasks on a schedule
execute and evaluate the success of functions called over HTTP
propagate user authorization context into the edge functions
be permission controlled via RLS

The basic idea is that you write your jobs as Supabase Edge Functions, and you control when they're executed and what data they are passed using the database. The name of the job should map directly to the name of the Supabase Edge Function associated with it. pg_cron is used to pick up new jobs and clean up old ones.

Because it's implemented in the database, you can use it via Supabase's dashboard too, so if you want to see what jobs are running, fix them or run them manually, you can do it easily via the UI:

Running queue_job via the Supabase Dashboard.

Supabase's dashboard gives you the option to impersonate a user and run queries as them, which is immensely helpful when you have a lot of business logic and permissions encoded in SQL.
I found the only public endpoints I needed were some functions to queue and dequeue tasks on behalf of the user, everything else was internal to the job system and rarely needs to be used directly.

So I ended up with a system where a job is queued from the code like:

 const { error } = await supabase.rpc(
          "queue_job",
          {
          	_job_name: "example-job",
						_request_body: {
							"data": true
						}
          },
        );

Or more frequently as part of a database trigger:

CREATE OR REPLACE FUNCTION private.queue_directory_agent_for_meeting_trigger()
RETURNS TRIGGER AS $$
DECLARE
    existing_run UUID;
BEGIN
    -- Check if an agent run is already pending/running for this meeting
    SELECT id INTO existing_run
    FROM public.agent_run
    WHERE request_body ->> 'meetingId' = NEW.meeting_id::text
      AND agent_name = 'directory-agent'
      AND state IN ('pending', 'running');

    IF existing_run IS NULL THEN
        -- No pending/running run exists; queue the agent for the meeting
        PERFORM public.queue_job(
            'directory-agent',
            jsonb_build_object('meetingId', NEW.meeting_id)
        );
    END IF;
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE OR REPLACE TRIGGER queue_directory_agent_after_insert_update
AFTER INSERT OR UPDATE ON user_meetings
FOR EACH ROW
EXECUTE FUNCTION private.queue_directory_agent_for_meeting_trigger();

That then gets picked up by the job system, which then runs the task via Supabase Edge Functions.

There is a lot of code on this page – feel free to copy and paste it into an LLM to ask questions and customize. You can find all the code in this Github repository.

#Assumptions

This setup assumes you want to run a job in the permission context of each user. There's nothing to stop you having global jobs, I just didn't need/want them so they're not accounted for in this set up.

Every Edge Function needs to accept and respond with headers it receives from the job runner for tracking purposes (X-Job and X-Correlation-ID). I originally tried doing this with internal request IDs for pg_net, but they're just integers that are reset when the database is restarted, so not reliable.

#Some initial configuration

I'm making use of a few extensions and a private schema:

CREATE EXTENSION IF NOT EXISTS pg_cron WITH SCHEMA extensions;
CREATE EXTENSION IF NOT EXISTS pgjwt WITH SCHEMA extensions;
CREATE EXTENSION IF NOT EXISTS pg_net WITH SCHEMA extensions;

CREATE SCHEMA private;

And the supabase_url() helper function is something I picked up from example projects. It's useful for getting the URL for your REST endpoints within the database (part of how the system will execute Edge Functions):

CREATE FUNCTION supabase_url()
RETURNS TEXT
LANGUAGE plpgsql
SECURITY DEFINER
AS $$
DECLARE
  secret_value TEXT;
BEGIN
  SELECT decrypted_secret 
  INTO secret_value 
  FROM vault.decrypted_secrets 
  WHERE name = 'supabase_url';
  RETURN secret_value;
END;
$$;

You may have noticed this pulls a Supabase Vault secret. This is really just somewhere to keep a variable for the project URL. You can configure this locally with a statement in your seed.sql file like:

DO $$
DECLARE
    secret_value TEXT;
BEGIN
    -- Check if the secret already exists
    SELECT decrypted_secret INTO secret_value 
    FROM vault.decrypted_secrets 
    WHERE name = 'supabase_url';

    -- If secret_value is null, it means the secret does not exist,
    -- so create it
    IF secret_value IS NULL THEN
        PERFORM vault.create_secret(
        	'http://api.supabase.internal:8000',
        	'supabase_url');
    END IF;
END $$;

But if you're deploying this to production, you'll want to copy your supabase URL from the API → API Settings page:

Into Vault:

Due to security changes in November 2024, we also need a function for retrieving the JWT secret:

CREATE FUNCTION private.jwt_secret()
RETURNS TEXT
LANGUAGE plpgsql
SECURITY DEFINER
AS $$
DECLARE
  secret_value TEXT;
BEGIN
  SELECT decrypted_secret 
  INTO secret_value 
  FROM vault.decrypted_secrets 
  WHERE name = 'app.jwt_secret';
  RETURN secret_value;
END;
$$;

Again, you'll need to populate this secret value via the Vault interface. You can find the appropriate a few settings below the Project URL:

#Tables

I've defined three tables, job, job_config, and job_logs. Everything else is private functions for managing the state in those tables and in pg_net, and defining pg_cron jobs.

#job

This is the execution information for a specific job. Most of the column names are self-explanatory, but just to highlight that request_body is what will be send as a JSON payload to the defined Supabase Edge Function.
An RLS policy allows the user CRUD operations on the table for their own jobs.
Indexes are included which might be useful by the time your job system has been running for a while, but at the same time you might be just as well deleting older completed jobs.

CREATE TABLE job (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
    job_name TEXT NOT NULL CHECK (TRIM(job_name) <> ''),
    request_body JSONB,
    state TEXT NOT NULL DEFAULT 'pending',
    retries INT DEFAULT 0,
    max_retries INT DEFAULT 3,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    last_run_at TIMESTAMP WITH TIME ZONE,
    next_run_at TIMESTAMP WITH TIME ZONE,
    locked_at TIMESTAMP WITH TIME ZONE,
    CONSTRAINT chk_valid_state CHECK (state IN (
    	'pending', 'running', 'completed', 'failed', 'canceled'
    ))
);
ALTER TABLE job ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can manage their own job runs"
ON job FOR ALL TO authenticated USING (
    (SELECT auth.uid()) = user_id
) WITH CHECK (
  (select auth.uid()) = user_id
);

CREATE INDEX idx_job_user_jobname ON job(user_id, job_name);
CREATE INDEX idx_job_state ON job(state);
CREATE INDEX idx_job_locked_at ON job(locked_at);
CREATE INDEX idx_job_pending ON job(user_id, job_name)
WHERE state IN ('pending', 'running');

#job_config

This is used to control configuration for all jobs with a specific name, in this case enabling/disabling the jobs and controlling the concurrency. RLS is enabled, but no policy is added, meaning it is not directly accessible to users.

CREATE TABLE job_config (
    job_name TEXT PRIMARY KEY,
    concurrency_limit INT DEFAULT 1 CHECK (concurrency_limit > 0),
    enabled BOOLEAN NOT NULL
);
ALTER TABLE job_config ENABLE ROW LEVEL SECURITY;

#job_logs

Basic job logging. This could be made more useful – what it does at the moment is log when a job starts and finishes. RLS policy for user CRUD also included.

CREATE TABLE job_run_logs (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    job_run_id UUID REFERENCES job_run(id) ON DELETE NO ACTION,
    log_message TEXT,
    log_level TEXT NOT NULL DEFAULT 'INFO',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT now()
);

ALTER TABLE job_run_logs ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can manage their own job run logs"
ON job_logs FOR ALL TO authenticated USING (
    EXISTS (
    SELECT 1
    FROM job
    WHERE job.id = job_logs.job_id
    AND job.user_id = (select auth.uid())
  )
) WITH CHECK (
  EXISTS (
    SELECT 1
    FROM job
    WHERE job.id = job_logs.job_id
    AND job.user_id = (select auth.uid())
  )
);

#Public functions

As I mentioned, there's really only two functions I needed to use on a regular basis, one to queue up a new job, and another to remove a job from the queue. You could have functions to list jobs, etc, but I found just SELECT over the table was all I needed.

-- Public methods
CREATE OR REPLACE FUNCTION public.queue_job(
  _job_name TEXT,
  _request_body JSONB,
  _max_retries INT DEFAULT 3
)
RETURNS UUID
SET search_path = public, extensions
AS $$
DECLARE
  new_job_id UUID;
BEGIN
  -- Insert a new job for the current user
  INSERT INTO job (user_id, job_name, request_body, max_retries)
  VALUES ((select auth.uid()), _job_name, _request_body, _max_retries)
  RETURNING id INTO new_job_id;

  -- Log the creation of the job
  PERFORM public.log_job(new_job_id, 'job run created');

  -- Return the ID of the new job
  RETURN new_job_id;
END;
$$ LANGUAGE plpgsql;

CREATE OR REPLACE FUNCTION public.dequeue_job(
  _job_id UUID
)
RETURNS VOID
SET search_path = public, extensions
AS $$
BEGIN
  -- Update the job to 'canceled' if it is still in the pending state
  UPDATE job
  SET state = 'canceled', updated_at = now()
  WHERE id = _job_id
    AND state = 'pending';

  -- Log the cancellation of the job
  PERFORM public.log_job(_job_id, 'job run canceled');
END;
$$ LANGUAGE plpgsql;

#Management functions

All of these are created in a schema named private, which by default has no permissions attached to it, and is not presented via the REST API. That means (without specific configuration) they are executable only by special roles like the postgres user, which is exactly what we need.

#Helper: generate a JWT for a user

This is a helper function that lets your job management system create a valid JWT token that it can use to execute Edge Functions on behalf of a user.
This is handy, and also one you have to be very careful about. You don't want to accidentally allow anyone to mint a JWT for any user via the API just by suppling the user's ID 😅
Being in the private schema should prevent this, and the user_id is a UUID (so not amenable to iterating through like integers), but just keep in mind that you probably don't want a public schema version of this function.

CREATE FUNCTION private.generate_user_jwt(
	p_user_id UUID, p_user_role TEXT, p_user_email TEXT)
RETURNS TEXT
LANGUAGE plpgsql
SECURITY DEFINER
SET search_path = public, extensions
AS $$
DECLARE
  jwt_token TEXT;
  exp_time TIMESTAMP;
BEGIN
  -- Calculate expiration time (1 hour from now)
  exp_time := now() + interval '1 hour';

  -- Generate the JWT
  jwt_token := extensions.sign(
    payload := json_build_object(
      'sub', p_user_id,
      'aud', p_user_role,
      'role', p_user_role,
      'email', p_user_email,
      'iat', extract(epoch from now()),
      'exp', extract(epoch from exp_time)
    )::json,
    secret := (select private.jwt_secret()),
    algorithm := 'HS256'
  );

  RETURN 'Bearer ' || jwt_token;
END;
$$;

#Running jobs

These two functions handle job initialization. The http request lifecycle is managed via pg_net, the rest of the work is in checking job state and concurrency management.

CREATE FUNCTION private.run_job(
  _job_id UUID,
  _job_name TEXT,
  _request_body JSONB,
  _user_id UUID,
  _role TEXT,
  _email TEXT
)
RETURNS VOID 
LANGUAGE plpgsql
SECURITY DEFINER
AS $$
DECLARE
  timeout_milliseconds INT := 5 * 60 * 1000;
  auth_header TEXT;
BEGIN
  -- Generate the JWT for the current user based on their role and email
  auth_header := private.generate_user_jwt(_user_id, _role, _email);

  PERFORM
    net.http_post(
      url := supabase_url() || '/functions/v1/' || _job_name,
      headers := jsonb_build_object(
        'Content-Type', 'application/json',
        'Authorization', auth_header,
        'X-Correlation-ID', _job_id::TEXT,
        'X-Job', 'true'
      ),
      body := _request_body,
      timeout_milliseconds := timeout_milliseconds
    );
  
END;
$$;

CREATE FUNCTION private.run_jobs()
RETURNS VOID
LANGUAGE plpgsql
SECURITY DEFINER
SET search_path = public, extensions
AS $$
DECLARE
    job_group RECORD;
    max_concurrency INT;
    running_jobs INT;
    available_slots INT;
    job_enabled BOOLEAN;
    current_job RECORD;
BEGIN
    -- Fetch all user-job pairs with pending jobs
    FOR job_group IN
        SELECT job.user_id, job.job_name
        FROM job
        WHERE job.state = 'pending'
          AND job.locked_at IS NULL
          AND (job.next_run_at IS NULL OR job.next_run_at <= now())
        GROUP BY job.user_id, job.job_name
    LOOP
        -- Skip if job is disabled
        SELECT enabled INTO job_enabled
        FROM job_config
        WHERE job_name = job_group.job_name;

        IF NOT job_enabled THEN
        RAISE LOG 'job %s disabled via job_config', job_group.job_name;
          CONTINUE;
        END IF;

        -- Get the global concurrency limit for the job
        SELECT concurrency_limit INTO max_concurrency
        FROM job_config
        WHERE job_name = job_group.job_name;

        -- Default to 1 if not specified
        IF max_concurrency IS NULL THEN
            max_concurrency := 1;
        END IF;

        -- Count the number of currently running jobs for this user-job pair
        SELECT COUNT(*) INTO running_jobs
        FROM job
        WHERE job_name = job_group.job_name
          AND user_id = job_group.user_id
          AND state = 'running';

        -- Calculate available slots for this user-job pair
        available_slots := max_concurrency - running_jobs;

        IF available_slots > 0 THEN
            -- Select pending jobs up to the available slots
            FOR current_job IN
                SELECT job.id, job.request_body,
                			 job.job_name, u.id AS user_id, u.role, u.email
                FROM job
                JOIN auth.users u ON u.id = job.user_id
                WHERE job.job_name = job_group.job_name
                  AND job.user_id = job_group.user_id
                  AND job.state = 'pending'
                  AND job.locked_at IS NULL
                  AND (job.next_run_at IS NULL OR job.next_run_at <= now())
                ORDER BY job.created_at
                LIMIT available_slots
                FOR UPDATE SKIP LOCKED
            LOOP
                -- Update the job to 'running' and set locked_at
                UPDATE job
                SET locked_at = now(),
                		state = 'running',
                		last_run_at = now(),
                		updated_at = now()
                WHERE id = current_job.id;

                -- Log the start of the job run
                PERFORM public.log_job(current_job.id, 'job run started');

                -- Execute the job using pg_net
                PERFORM private.run_job(
                    current_job.id,
                    current_job.job_name,
                    current_job.request_body,
                    current_job.user_id,
                    current_job.role,
                    current_job.email
                );
            END LOOP;
        END IF;
    END LOOP;
END;
$$;

#Process jobs

This will check through pg_net's internal _http_response table for requests that have been annotated with the X-Job header.
From there, it matches up the X-Correlation-ID header to the corresponding job table entry, and decides whether the job was successful based on the HTTP status code returned.

CREATE OR REPLACE FUNCTION private.process_jobs()
RETURNS VOID
LANGUAGE plpgsql
SECURITY DEFINER
SET search_path = public, extensions
AS $$
DECLARE
  response RECORD;
  job_record RECORD;
  normalized_headers JSONB;
BEGIN
  FOR response IN
    SELECT * FROM net._http_response
    FOR UPDATE SKIP LOCKED  -- Lock the response to prevent concurrent processing
  LOOP
    -- Normalize headers to lowercase
    SELECT jsonb_object_agg(lower(key), value) INTO normalized_headers
    FROM jsonb_each_text(response.headers);
    IF normalized_headers ? 'x-job' THEN
      -- Find and lock the corresponding job record
      IF normalized_headers ? 'x-correlation-id' THEN
        SELECT * INTO job_record
        FROM job
        WHERE id = (normalized_headers->>'x-correlation-id')::UUID
        FOR UPDATE;
        IF FOUND THEN
          DELETE FROM net._http_response WHERE id = response.id;
          IF response.status_code = 200
          OR response.status_code = 201
          OR response.status_code = 204 THEN
            -- Success: Update job to 'completed'
            UPDATE job
            SET state = 'completed', locked_at = NULL, updated_at = now()
            WHERE id = job_record.id;
            -- Log the successful completion
            PERFORM public.log_job(job_record.id,
            	'job run completed successfully');
          ELSE
            -- Failure: Handle retries or mark as failed
            PERFORM private.fail_job_with_retry(job_record.id);
            PERFORM public.log_job(job_record.id,
            	'job run failed and will be retried');
          END IF;
        END IF;
      ELSE
        RAISE LOG 'job run failed due to a missing X-Correlation-ID header. '
              'This is a permanent failure and will not be retried.';
        DELETE FROM net._http_response WHERE id = response.id;
      END IF;
    END IF;
  END LOOP;
END;
$$;

#Logging

This is relatively barebones, and just tracks job starting/finishing.

CREATE OR REPLACE FUNCTION public.log_job(
  _job_id UUID,
  _log_message TEXT,
  _log_level TEXT DEFAULT 'INFO'
)
RETURNS VOID
AS $$
BEGIN
  INSERT INTO job_logs(job_id, log_message, log_level)
  VALUES (_job_id, _log_message, _log_level);
END;
$$ LANGUAGE plpgsql;

#Handling failed jobs

Jobs fail, the system will handle failures with configurable retries, and reset jobs where the edge function never returned a status (due to resource limits, this can happen).

-- mark a job as failed, and queue for a retry 
CREATE OR REPLACE FUNCTION private.fail_job_with_retry(
  _job_id UUID
)
RETURNS VOID
SECURITY DEFINER
AS $$
DECLARE
  _retries INT;
  _max_retries INT;
BEGIN
  -- Fetch the current retries and max_retries for the job
  SELECT retries, max_retries INTO _retries, _max_retries
  FROM job
  WHERE id = _job_id;

  IF _retries + 1 >= _max_retries THEN
    -- Mark job as permanently failed
    UPDATE job 
    SET state = 'failed', locked_at = NULL, updated_at = now()
    WHERE id = _job_id;
  ELSE
    -- Increment retry count and schedule next retry
    UPDATE job 
    SET retries = _retries + 1, 
        state = 'pending',
     		-- Exponential backoff
        next_run_at = now() + INTERVAL '5 minutes' * (2 ^ _retries),
        locked_at = NULL,
        updated_at = now()
    WHERE id = _job_id;
  END IF;
END;
$$ LANGUAGE plpgsql;

-- When a job has expired, reset its status to pending
CREATE OR REPLACE FUNCTION private.reset_stuck_jobs(
  _timeout INTERVAL DEFAULT '15 minutes'
)
RETURNS VOID
SECURITY DEFINER
AS $$
BEGIN
  UPDATE job
  SET locked_at = NULL, state = 'pending', updated_at = now()
  WHERE locked_at < now() - _timeout
    AND state = 'running';
END;
$$ LANGUAGE plpgsql;

#pg_cron

With pg_cron enabled, you can configure the management functions to execute on a schedule that suits your workloads.
Below I've chosen to run the jobs very frequently because I wanted a relatively high throughput, but it can be tweaked to your preferences. One thing though: I would try to have run-jobs and process-jobs run out of sync with each other. You don't really want the job that picks up work running at the exact same time as the job that determines whether the work is completed, as it might introduce delays.


SELECT cron.schedule(
  'run-jobs',
  '20 seconds',
  $$
  SELECT private.run_jobs();
  $$
);

SELECT cron.schedule(
  'process-jobs',
  '6 seconds',
  $$ 
  SELECT private.process_jobs();
  $$
);

SELECT cron.schedule(
  'reset-stuck-jobs',
  '*/8 * * * *',
  $$
  SELECT private.reset_stuck_job_runs('8 minutes');
  $$
);

#Edge functions

This is a barebones edge function that contains only the logic required to successfully process a job.
The important thing is that it responds in a way that the management functions can process. In the Postgres functions above, this means accepting and responding with specific headers to identify the request as coming from the job runner, and returning HTTP status codes to indicate whether the job was successful or not.

import "@supabase/edge-runtime";
import { createClient } from "@supabase/supabase-js";

Deno.serve(async (req) => {
  const { data } = await req.json();

  // X-Job and X-Correlation-ID are used as part of the Job Runner system.
  const correlationId = req.headers.get("X-Correlation-ID");
  const isJob = req.headers.get("X-Job");

  if (!correlationId || !isJob) {
    console.error("Missing required Job Runner headers");
    return new Response(
      JSON.stringify({
        error: "Missing required Job Runner headers",
      }),
      {
        status: 400,
        headers: { "Content-Type": "application/json" },
      },
    );
  }

  console.log("X-Correlation-ID: ", correlationId);
  console.log("X-Job", isJob);

  const authHeader = req.headers.get("Authorization")!;
  const supabase = createClient<Database>(
    Deno.env.get("SUPABASE_URL") ?? "",
    Deno.env.get("SUPABASE_ANON_KEY") ?? "",
    { global: { headers: { Authorization: authHeader } } },
  );
  const token = authHeader.replace("Bearer ", "");
  const {
    data: { user },
  } = await supabase.auth.getUser(token);

  /**
   * Only run if we have a user context
   */
  if (!user?.email) {
    console.error("No valid user token received");
    return new Response(
      JSON.stringify({
        error: "Unauthorized",
      }),
      {
        status: 401,
        headers: {
          "Content-Type": "application/json",
          "X-Correlation-ID": correlationId,
          "X-Job": isJob,
        },
      },
    );
  }
  
  // This is about where the rest of your worker logic will go.
  const success = !!data;
  
  if (success) {
    console.log("Successfully processed request");
    return new Response(null, {
      status: 204,
      headers: {
        "Content-Type": "application/json",
        "X-Correlation-ID": correlationId,
        "X-Job": isJob,
      },
    });
  }
  
  console.error("Failed to process request");
  return new Response(null, {
    status: 500,
    headers: {
      "Content-Type": "application/json",
      "X-Correlation-ID": correlationId,
      "X-Job": isJob,
    },
  });
});

#Caveats

For me, this has worked best for tasks that are mostly I/O-bound – API calls, reading from the database, saving to the database, transforming JSON. Supabase Edge Functions have a few limits, but working around the two second CPU time one is particularly awkward. Forget running ML tasks, and decompressing a large-ish file won't work either.

The good news is that it seems Supabase will be adding flexibility there in 2025:

We have a very exciting roadmap planned for 2025. One of the main priorities is to provide customizable compute limits (memory, CPU, and execution duration). We will soon announce an update on it.
– Supabase blog

In the mean time it is prudent to break jobs up into discrete units of work. For example, instead of a single job that does a given task for all users, create a "router" task that queues up the task for each user.

There's plenty of ways you can extend this – I never added recurring jobs, for example, but I don't think it would be too tricky. You might also not like other decisions I made, like wiring the job names directly to the functions, but that is an intentional choice on my part to try and ensure the functions didn't end up too large.

Most importantly, this is a system that worked for me. A a job system goes, it is, shall we say... no frills. But it might be interesting to some others.

There is currently no comments system. If you'd like to share an opinion either with me or about this post, please feel free to do so with me either via email (ross@duggan.ie) on Mastodon (@duggan@mastodon.ie) or even on Hacker News.

Corrections and suggestions also welcome, you might prefer to use the accompanying Github repository if so.

Ignoring good advice and building my own blog (again)

2025-02-11T00:00:34.000Z

For various reasons, I stopped blogging about ten years ago.

I ended up redirecting the energy into coding, and occasionally writing posts for the blogs of companies I worked for. But after Barricade was acquired by Sophos in 2016 I stopped writing almost entirely.

My current company, Clearword, is winding down and I'm lucky enough that I don't have to line up any work immediately, so I've decided to start writing again – and build some software along the way.

It's kind of a classic developer mistake to build a blog before they start writing. As Jeff Triplett writes:

"Write and publish before you write your own static site generator or perfect blogging platform. We have lost billions of good writers to this side quest because they spend all their time working on the platform instead of writing."

This is good advice. I am just preternaturally incapable of following it.

The first time I build any significant software was when I cobbled together my own blogging system in college. It was styled with tables and rounded corner gifs and stitched together with PHP 4:

Mad skillz.

After college I used Wordpress, Blogspot and Medium as I moved away from writing web apps and into managing web infrastructure and writing backend services. For me, writing my own blogging system again ~20 years later feels like coming home.

#Anti-goals

When I was jotting down ideas, I put some of these under the heading "anti-goals" – stuff I wanted to consciously avoid.

I didn't want to use a hosted third-party platform. I've gone down that route a couple of times now, and the results have always been unsatisfactory.

I also wanted to explicitly avoid building anything that was throwing up newsletter popups, social logins, invasive analytics scripts, engagement tricks, progress bars and the inevitable creep of AI writing assistance.

On Ghost

One thing that I missed entirely in my first survey was Ghost. I remember looking into it a few years ago and not liking it for some (probably inane) reason. It's marketed as a professional publishing platform, with subscriber content, newsletters, etc., none of which is what I want. However, I ended up checking it out after I'd built a good fraction of my own blog and found they'd made similar choices to me, which means I think they are pragmatic and have excellent taste 🧑‍🍳.

Something else I wanted to avoid was writing everything in Markdown and committing to git. There are understandable reasons why many developers choose it – they do not (as a rule) like running databases. Markdown is text, and git is basically a database for text without all the hassle of a live process and SQL.

The idea of writing long-form English posts in Markdown is just anathema to me, even as a developer. It's barely a step above writing BBCode (shots fired!) and feels like giving up too much of the experience of writing. Fortunately this is the web, and we can all make different choices 🙂

What I do want out of my blog is still a work in progress. Partly what I want from it is for it to be a work in progress, not a publishing platform. I've spent the last fifteen years building software for other people, and I'm keen to get back to building software that is just for myself. Not that I won't share parts of it when I think I have something useful to share. However, I don't want to become a blogging platform maintainer. I don't want users. I don't want customers.

#Dual stack

Maybe it sounds obvious, but a blog is two software stacks – one for reading, and one for writing. It's much more obvious with static site generators, since you are perhaps using a text editor to write your posts, committing to git, and then the rest is taken up by a build process in Github, which creates the HTML, CSS, etc.

I only really considered this when I started thinking about what I wanted from a blog, and two stand out goals were a rich Notion-like authoring experience, but a fast, cacheable, low-Javascript experience for readers. These goals seemed to be in conflict.

Application developers build for multiple audiences all the time, but when you're building a B2B SaaS app that may just mean API consumers and logged in humans. Blogs are interesting because the largest visual component of the system should appear very similar for both sets of users, it's just that the author also needs a bunch of bells and whistles for managing the text.

For me, the ideal writing experience sits somewhere between the minimalism of Medium and the digital Swiss Army Knife documentation authoring of Notion (sans the slightly too in-your-face AI bits).

I used to be very online, and specifically very online on Twitter. That has waned in recent years, but I'm interested in where things are going with Mastodon and Bluesky. I have a preference for Mastodon, partly because Bluesky has more visible US political drama, and partly because I have an anarchist streak in me that wants to see social media unbundled.

As a result, I want to make the blog have a native understanding of at least ActivityPub. I love the idea that my blog could be followed on Mastodon (still working on this). It will probably be a little complicated to provide a legible variant of the posts, but perhaps not much more complicated than Atom/RSS.

Speaking of which, I also wanted to provide an Atom/RSS feed, even though I'm not convinced there's a large audience. I always wanted a nicely styled, standards-compliant feed though, so it's there.

#Passkeys

I follow Ricky Mondello on Mastodon, and they have a nuanced perspective on password managers and WebAuthn. As a result, passkeys were unusually present in my thoughts when I was building the system, and so I included passkey support using the excellent (if search-resistant) Better-Auth library.

Better-Auth has support for passkeys, but last I checked the user must first register with a password, which means passkeys are only a second-factor – not ideal. I haven't checked whether this can be easily patched yet, though it's on my list.

#Experiments and fun

I also wanted to have some fun, muck around and get deep into various parts of the stack. There's folk wisdom amongst software developers that code is a liability, but knowledge is an asset. The idea is that code requires maintenance, and the more of it you have the harder it is to manage effectively. It may even become an impediment to building what you need in the future. However, what you learn writing that code can have compounding value, making for better developers and better teams.

That's not to suggest that I'm going to religiously account for every tangent as a "learning opportunity" – I'm my only real audience here. I don't have to attend a standup and sheepishly tell people I spent a day or two making a kaleidoscopic rainbow button on a whim before discarding it as a bad idea. Or that while mucking around with SVG animations I accidentally created a noisy "O" effect on my 404 page and kept it because it reminds me of the Holy Grail from Fate/stay night.

A lot of the original idea was just writing down developer experience goals like "I want to style everything with Tailwind" or "I want to use shadcn for editor components" and then doggedly pursuing those goals in the face of all headwinds just because it's an aesthetic choice I like.

#Technical choices

I'm in two minds about whether to even write these down at this stage, but maybe a quick overview is informative about where I started versus where I ended up? No blanket technological judgements intended 🙂

It's odd to realize this, but as someone with a long history in operations, operational simplicity was not an explicit goal when I began – I was initially more interested in how quickly I could put it together.
I think that's reflective of the last half a year or mad dash building Oggam.

I started with Next.js and Supabase because that's what I picked for Oggam, and I found them to be very powerful as someone who has not done much frontend dev for the last 15 years. Ultimately, though, after a couple of weeks I switched out to Astro and SQLite.

I had started asking myself if the complexity of the Supabase self-hosted stack was something I actually needed for something as architecturally simple as a blog, and I felt Astro would give me more flexibility and control over the HTML that was being served. I'm also entertaining the idea that I can use Astro's static site building capabilities to regularly produce an entirely static failover/backup for the live version of the system. That would be pretty amazing.

On Supabase

I would pick Supabase again in a heartbeat if I were building another SaaS application. There are some things I would change in their stack around Edge Functions (the hard CPU time limits are frustrating to work around), but I was very lucky to have picked this just based on a handful of Hacker News mentions and a YC podcast.

If you embrace RLS and Edge Functions you can produce some sophisticated behaviours while keeping infrastructure costs very low.

I cycled through several text editors (TipTap, PlateJS, BlockNote) for authoring, but found that many of them required payment for the functionality I wanted, or were too opinionated, focused on collaborative editing, or looked tricky to make modifications.

I've been drawn to Lexical since I first found it, though since it's pitched as a framework for building editors I thought it would be overkill. I'd been steering clear of it in the name of keeping things easy, but in the end, a framework is actually what I needed.
Definitely a bigger investment of effort than the other editors, but has enabled me to be as idiosyncratic as I wanted in my choices, including rewriting chunks of it to use Tailwind and shadcn.

#Deploying

I'm not particularly misty-eyed over the days when hosting meant buying a server and hauling it into a rack myself, but there is something primordially right about being able to run everything on a single server, and copy files around.

At the moment the whole thing is deployed on a $6 Hetzner VPS via Github Actions, managed via Docker Compose and running behind nginx and Cloudflare. To me, this is a simple, powerful setup. With some tricks, it even allows me to get maybe-zero-noticeable-downtime deployments 😏

You can configure Docker compose to do rolling deploys (!):

    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:4321/health"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 5s
    deploy:
      replicas: 1
      update_config:
        order: start-first
        failure_action: rollback
        delay: 0s
    stop_signal: SIGTERM
    stop_grace_period: 60s
    logging:
      options:
        max-size: "10m"
        max-file: "3"

However it did still result in 5-10 seconds or so of visible Origin Unreachable errors from Cloudflare. Since this is a blog though, not a complex multi-user web app, I can cheat a little by getting nginx to serve "stale" cached content for the posts while the app backend is down:

        # Enable caching globally
        proxy_cache cache;
        # Cache validity (adjust as needed)
        proxy_cache_valid 200 301 302 10m;

        # Serve stale content if upstream is down
        # This does not serve stale if upstream is healthy.
        proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504;

There are still plenty of bugs, but the bugs are all of my own creation, and most of them affect only me, so it's kind of great?

Hello!

2024-12-15T11:35:55.000Z

I'm still putting things together here, but I've got an about page that gives a brief summary of who I am.

@duggan

Build Everything

#Combinations and permutations

#I can move through phases more quickly

#It's easier to be more ambitious

Building a Stripe dashboard with an ESP32 desktop clock and Rust

#First pass: AWTRIX and a Raspberry Pi

#Artwork

#Captive portal

microgpt on the ESP32 – but... why?

#What's the point?

Cognitive debt in AI coding

I built a terminal monitoring app and custom firmware for a desktop clock with Claude

#A year ago

#December 2025

#Christmas break, structured prompts

#The Yegge Inflection Point

Self-hosting git and builds without running a bunch of web services

#Hosting a git repo

#Building an image on push

#Hosting an image

#Deploying from a private registry

New Year's Resolutions 2026

#Run 5km twice weekly

#Weights twice weekly

#Eat less meat

#Drink less, and less frequently

#Read more adventurously

#Write every day

#Publish every week

Moving Cloudflare out of the critical path

10GbE

#Fast 5

#10Gb is not necessarily RJ45

A year of not really blogging

Sync new purchases to iPod Classic

VAT invoice generator

Fixing a problem at 40 that stumped me as a 10 year old

#Footnotes

Japan May 2025 – Hokkaido and Kyushu

Goodbye Hokkaido, next stop... Okinawa?

#Kyūshū

Preparing for the Japan trip

#Skipping the detailed itinerary

#Researching a trip in 2025

#Backpack or suitcase? 🎒か🧳？

#Learning Japanese 🇯🇵の📚

Traveling to Japan for three months because life's too short

#Fast forward a few years

#2025, the year we make contact

Hacking together a Job Runner using Supabase Edge Functions

#Background jobs

#Cobbling together a job runner

#Assumptions

#Some initial configuration

#Tables

#job

#job_config

#job_logs

#Public functions

#Management functions

#Helper: generate a JWT for a user

#Running jobs

#Process jobs

#Logging

#Handling failed jobs

#pg_cron

#Edge functions

#Caveats

Ignoring good advice and building my own blog (again)

#Anti-goals

#Dual stack

#The next social web

#Passkeys

#Experiments and fun

#Technical choices

#Deploying

Hello!

#
First pass: AWTRIX and a Raspberry Pi