I finally got tired of not knowing whether anyone reads this thing, so I spent a Saturday afternoon standing up Umami in the homelab. The install was the easy part; the instructions are dead simple.

Then I got to the bit where you expose it to the internet. I went along with the advice everyone gives, stopped halfway and decided it wasn’t good enough for me. So, I did what I normally do and stubbornly wandered off to my own path.

Quick bit of context for anyone who hasn’t gone down this particular hole. Umami is a self-hosted analytics platform: a small Node app with a PostgreSQL database to maintain persistence sans the cookies and third parties slurping up all the data. It’s as simple as dropping one script tag on your site. It posts a little blob of JSON on each page view and you get a dashboard. My install runs in an LXC on a member node of my homelab’s Proxmox cluster.

I landed on it for the “normal” reasons. Cloudflare’s Analytics are free but limited. They don’t give me precisely what I’m looking for and they’re a bit too slow for my liking. And, I’m not even going to give Google a single thought; they have enough of my data already.

Which leaves the question: how does a script tag on a public website safely and securely reach a container in my house without punching a hole in my router?

The answer everyone gives you.#

The standard answer is a Cloudflare Tunnel. A small daemon, cloudflared, runs next to your service and dials out to Cloudflare. No dicking around with port forwarding, firewall rules or opening up your router to the world. Traffic arrives at Cloudflare, goes down the pipe your daemon already opened and lands on your service. It’s genuinely lovely and it costs nothing. And since I already use Cloudflare to currently host my static websites and domains it was just the pragmatic option.

I think it’s worth noting there is a real trade off here. A tunnel means Cloudflare terminates your TLS. Since they decrypt at the edge, they could inspect whatever they like and they re-encrypt on the way down the pipe. For page view pings carrying a URL and a screen size, I genuinely do not care. For anything with secrets in the payload I would care enormously and so should you.

Anyway, Umami has an admin interface. An admin interface typically has a login page. So, most guides you’ll find after searching around will tell you to put something like Cloudflare Access in front of it. Access is an authentication layer at the edge. Basically, someone hits your hostname, Cloudflare intercepts, they sign in against an identity provider and only then does the request continue to your box.

I was about to wire it to my IDP when I actually stopped to read my own ingress config a bit more closely.

Tunnels match on path.#

The important little detail I almost skimmed past was that a tunnel’s ingress rules do not just match on hostname, but on path.

I had written this, which is what everyone starts with:

ingress = [
  {
    hostname = "analytics.nightcity.network"
    service  = "http://umami:3000"
  },
  {
    service = "http_status:404"
  },
]

You write a single hostname and everything on it goes straight to the app while anything else gets a 404. Ok.

But my analytics service only needs to expose two things to the public internet; the tracker script and the collect endpoint. Nobody on the internet needs to see /login or the dashboard, the settings, the user management or the API the dashboard talks to. So, why was I publishing everything and then buying into another service to place in front of it?

ingress = [
  {
    hostname = "analytics.nightcity.network"
    path     = "^/bundle\\.js$"
    service  = "http://nginx:80"
  },
  {
    hostname = "analytics.nightcity.network"
    path     = "^/api/v1/data$"
    service  = "http://nginx:80"
  },
  {
    service = "http_status:404"
  },
]

I only need precisely two paths out while everything else gets met with a lovely 404.

My admin interface still exists, of course ( I am not typing SQL to read my own page views ). It sits on my home network behind my own reverse proxy, reachable from the couch or over my established VPN.

Drawn out, the whole arrangement is two seperate paths that happen to share a name:

cloudflared decides what gets through and it’s only aware of two paths. My side of the picture never touches Cloudflare, or the rest of the internet, at all. That shared fork at the top is possible with split horizon DNS and which route your request takes depends on how you get to that point. I’ll explain a bit further down.

Why I think this is the better trade.#

I want to be fair to Access here, because it’s a great product and there are plenty of setups where it’s the right call. If you genuinely need to reach an admin panel from anywhere on a machine you don’t control, without a VPN, Access is exactly the kind of tool that’ll get you there.

But if you don’t need that, consider what you’re actually buying in to.

With Access, /login is on the internet. It returns a challenge instead of a form, which is much better than nothing, but the attack surface is still there. There’s an auth flow to configure, an IDP to keep working and an additional sign-in every time. Umami doesn’t consume the Access token, so you authenticate to Cloudflare and then authenticate again to Umami. Nobody has time for that nonsense.

With path scoping, /login returns a 404. There is no flow to misconfigure because there is no flow. There is nothing to leave accidentally open when you change something else eighteen months from now.

The thing I keep coming back to: an attack surface you removed cannot be misconfigured later. A control you added can. This is all about shrinking the attack surface, which is an idea that’s far older than me. We’re not doing anything new here. But a standard installation path is built to get the typical user up and running quickly. However, quick doesn’t necessarily mean appropriate for something like this.

Worth being precise about which of these is which, though. The 404 on /login is absence. There is nothing behind it to find no matter how hard you look. Umami does allow you to rename its default tracker paths as well, but that’s plainly obscurity and it buys me nothing against anyone who actually takes the time to read my page source. Outside of that, renaming dodges a blocklist that matches on names and known patterns.

Does it work though?#

The nice part about this setup is that you can test the public path without leaving the house. Using curl --resolve lets you skip your own DNS and dial the Cloudflare edge directly, while still sending the right hostname, so the request takes the same road a real visitor does.

curl -sI \
  --resolve analytics.nightcity.network:443:104.21.x.x \
  https://analytics.nightcity.network/login | head -1

Run that against a handful of paths and you get:

/                  404
/login             404
/bundle.js         200
/script.js         404
/api/v1/data       405
/api/send          404

That 405 is the collect endpoint telling me it only accepts POST, which is exactly what I want to see from a GET. It does admit the endpoint exists, where a 404 would not, but that one has to be findable anyway. Everything else gets a polite middle finger.

Meanwhile, from inside the house, the same hostname gives me the full dashboard. The same two path as before and the split falls out of the DNS I already run for network-wide adblock via a Technitium cluster.

Something worth pointing out.#

I updated the ingress config, re-ran my checks and /script.js came back with a 200. Which was alarming, because I had just watched it 404.

It was cached. Umami serves its tracker with a 24-hour cache header. My earlier testing had pulled it through the edge and Cloudflare was dutifully serving me the copy it already had. Which, to be fair, is exactly what it should normally be doing. A request with a junk query string came back 404 immediately confirming the origin was doing its job.

Worth knowing if you ever unpublish something: the edge does not find out until its copy expires. Cache invalidation strikes again!

Hark! A plot twist!#

Just after I shipped the script tag and confirmed real traffic was hitting Umami, Firefox showed me this:

Sir, this is my own site from my machine on my home network. How dare you?

As I mentioned earlier, I run split horizon DNS. Inside my network, analytics.nightcity.network resolves to a private address on my LAN so I get the dashboard directly. Outside, where you better be reading from, the same name resolves to Cloudflare and goes down the tunnel. That’s what makes the two-path thing work. I also mentioned this before in my previous article My Blog Now Ships From My Homelab! and it’s one of my favourite aspects about my setup.

But when I load my public blog from my own house, the browser sees a page served from a public origin trying to load a subresource from 10.x.x.x. Browsers have started treating that as exactly the attack it usually is: a website on the internet quietly poking at your router, your printer or your NAS. Firefox calls it Local Network Access and blocks it by default. Chrome is heading the same way.

So the one place on earth where my analytics silently do not work is the chair I’m sitting in which is precisely how it should work. If it ever bothers me, the fix is to give the tracker its own hostname in a domain my internal resolver doesn’t answer for, so it goes out to the edge from everywhere including my lounge room. I won’t be doing that as I’m all too happy skipping my own page views.

The one thing path scoping does not fix.#

Moving the admin interface off the internet does nothing for the collect endpoint. That endpoint has to accept anonymous POSTs from every visitor’s browser, or it isn’t an analytics endpoint. Umami rejects requests carrying a website ID it doesn’t recognise, which stops idle nonsense, but my real website ID is sitting in the page source of every page on this site and Plant🌱Smart. Literally anyone can read it.

So the only real control is applying some kind of rate limit. Cloudflare’s free tier, which I’m currently on because I’m cheap and actually trying to reduce my subscription costs, permits one rule at a ten second window and it insists on counting per data centre rather than globally. It’ll stop something stupid. But, it will not stop something determined.

Basically, path scoping shrinks the surface area enormously and then stops. What’s left is the stuff that’s supposed to be open. Though, the worst that can happen if the service gets hammered is fill my disk with garbage data points. Which would no-shit make me laugh.

… so, naturally I put Nginx in front of it.#

I told myself this was about the rate limit which was a lie. It took a few hours for two better reasons to turn up.

The origin is blind.#

A tunnel terminates the connection at the edge and opens a fresh one to your box, so every request arrives from the connector sitting next to your service. Umami sees 172.16.x.x, the Docker address of cloudflared, for the entire internet. That’s also why the usual advice of “just put fail2ban on it” doesn’t really apply. Fail2ban blocks source addresses with a firewall rule and no packet ever arrives from the address you’d want to block.

Cloudflare does pass the real client along in a CF-Connecting-IP header. Nginx can promote that header back into being the actual client address, which makes both the logging and the limiting mean something:

set_real_ip_from 172.16.0.0/12;
real_ip_header   CF-Connecting-IP;

limit_req_zone $binary_remote_addr zone=collect:10m rate=5r/s;

The set_real_ip_from range tells Nginx only the connector may assert that header. Nginx answers cloudflared and nothing else here and my internal route goes straight to Umami without passing through it. Meaning nothing on my LAN can forge a client address at me.

Umami logs nothing at all. Zilch.#

Its own logs are four lines of startup and then a blank stare into the void. Which means that until I put a proxy in front of it, the only record of what hit my analytics endpoint was… my analytics.

Nginx gave me an access log within about ten seconds of starting and the very first thing it told me was that I had no idea what my traffic was.

In which I am humbled by a robot.#

I had been suprised with my initial visitor numbers. Then I looked properly and roughly ~90% of it was a single machine in Singapore hammering one tiny post:

browser  os      device  screen      country  hits  sessions
chrome   Mac OS  laptop  1366x1366   SG       53    51

There are a few tells here. Not only is the screen size a perfect square, 50ish sessions with just as many hits from the same region with the same browser settings smells like a bot crawl. It was Kagi, near as I can tell, rendering the page to build a preview for Kagi Small Web. I have no real objection to that. It reaches my tracker at all because it runs the JavaScript, which an ordinary crawler never would. This is exactly the sort of thing that pollutes a dataset while you sit there feeling popular.

I don’t care about the bots. The point is that I only found it because I’d added logging. I only added logging because I was chasing a rate limit I probably didn’t need.

The small detail I liked most.#

Nginx has a default location block and mine looks like this:

location / {
    return 444;
}

444 is an Nginx special. It doesn’t return a status, but closes the connection quietly.

That rule is doing the same job as the catch-all 404 in my tunnel ingress. It holds exactly the same line only hop further in. Two independent things now have to be wrong at once before anything reaches my admin interface.

So, the tunnel is Cloudflare’s. The edge rate limit is Cloudflare’s. The Nginx config is a text file that’s mine and it doesn’t care in the slightest what is in front of it. Which matters, because I’m not 100% sold on keeping Cloudflare around longer-term.

None of the idea is Cloudflare-specific either. Any reverse proxy has a path-scoped location block and any tunnel worth the name matches on more than a hostname. Tailscale, Pangolin, NetBird or even vanilla WireGuard will get you there. I picked Tunnels as a convenient stop-gap until I move on to something a bit more “self-hosty”. The vendor is incidental. Publish only what has to be public.

In closing …#

None of this is novel. Tunnels have matched on path since forever, it’s in the docs and I’m certain plenty of people are already doing exactly this. I just hadn’t thought about it properly, because the well-trodden advice is “put an auth layer in front of it” and this kind of consensus is usually good enough that you stop thinking.

But “protect the admin panel” and “publish the admin panel and then protect it” are not the same sentence and you should be aware of the difference.

If you’re running anything through a tunnel right now, it’s worth five minutes with your ingress config. Ask yourself which paths actually need to leave your network. For a lot of self-hosted things the honest answer is “fewer than all of them”. The best answer is “none”. And if you’d rather find out than wonder, that curl --resolve trick works against any hostname, including yours. Start with /login and see what comes back.

And if you’re about to tell me the browser permission dialog is a bug, it isn’t. It’s three correct systems arguing and I’ve decided that’s a feature.

Would you like to know more?#

I kept the theory light in the post, because it kind of goes against the vibe of the site and my own casual style of writing. But the ideas underneath this are old and much better argued elsewhere, so here’s where I’d start.

• The Protection of Information in Computer Systems, Saltzer and Schroeder, 1975. The source of fail-safe defaults ( deny by default, allow by exception, which is exactly what that catch-all 404 rule is ) and economy of mechanism ( fewer moving parts means fewer parts to get wrong ). It’s a fifty year old paper and it reads like one, but section I is short and it has aged as disgracefully as I have.
• Attack Surface Analysis, OWASP. The plain-English version of the whole post, minus my nonsense. Useful if you want a structured way to ask “what am I actually exposing” about something larger than a script tag.
• Tunnel configuration file, Cloudflare. The ingress rules reference. This is the page I had skimmed past twice before noticing that path was sitting right there next to hostname.
• Local Network Access, WICG. The spec behind the permission dialog that made me raise an eyebrow. If you’d rather have prose than a spec, Chrome’s New permission prompt for Local Network Access covers the same ground and explains why browsers decided this needed fixing.

If you only read one, make it Saltzer and Schroeder. Almost everything I thought I worked out on that Saturday turns out to be in there, but described better by people who got to it first and who are far smarter than me.

Some background.#

For three years every plant page on Plant🌱Smart ended with the same two phone numbers and both of them were for the US. That never really sat right with me. I even flagged it as roadmap work when I rebuilt the site, then left it sitting there. The site’s whole reason for existing is for the moment your cat eats something and you need an answer now. For most of the people who land there from a search engine, I was answering with a number they can’t dial. So, I recently sat down to address that gap, assuming I’d spend a few minutes filling in a table of hotlines and be done with it.

Every single country had a speed bump.#

• Sweden’s poison centre stopped answering questions about animals in July 2018 because the human call volume got too high.
• The Dutch line only takes calls from vets, so if you’re a pet owner in Rotterdam, the correct advice is “ring your vet and let them ring the line”, which is not a phone number at all.
• Belgium answers animal calls only during the day and says outright on its own site that it isn’t funded for animal work.
• The Australian helpline I’d have sworn was free actually starts at $75. This is a bit embarrassing because I live here and should know this.
• The UK’s fee changes depending on the time of day you call.
• The ASPCA doesn’t publish its consultation fee anywhere on its own page, so the figure everyone quotes online comes from third parties.

The list goes on.

I’d have got at least half of these wrong from memory, which is a genuinely unsettling thing to realise about emergency information.

Once again, I had to collate a bunch of disparate data and create a shape to support it before munging it all together. Every entry in the hotlines list now cites the operator’s page it came from and the date I read it which is the same rule I put on the plant records in the last post. A Python script holds the whole list and nags me when an entry goes over a year old and it runs as part of the automated deployment. So, the build gives me a big’ole bonk on the nose whenever the list goes stale.

The boring technical stuff.#

The engineering ended up being the easy half and mostly a matter of deciding what fails safely. Hugo writes every country into the HTML as a partial. A small script then lifts the relevant one out and folds the rest away. It guesses in order: a country you’ve pinned, then the location filter if it names exactly one country, then your browser locale.

It never asks permission for anything, because a permission prompt at 2am is the last thing you need while you’re panicking about your pet. And, personally, I hate browser prompts asking for location tracking. Hard pass. If the script doesn’t run, or if the service worker hands you a stale page, you get all countries instead of the wrong one.

There’s also a new emergency page for the first five minutes before you get through: what to do, what not to do and what they’ll ask you. The guidance follows the ASPCA and the Pet Poison Helpline which is also cited and linked. After all, the one thing I’m definitely not qualified to write is clinical advice.

Another free gift: the hotlines API.#

There’s really no obvious centralised place online that collates all this information into a single data set. I’ve at least done the work of bootstrapping the handful of most common countries that have helplines and the list will definitely grow over time. So, I’ve exposed a new “hotlines” API endpoint with its own documented shape.

{
    "countries": {
        // ... more countries ...
        "US": {
            "checked": "2026-09-10",
            "name": "United States",
            "services": [
                {
                    "audience": "owner",
                    "display": "(888) 426-4435",
                    "fee": "A consultation fee applies",
                    "hours": "24 hours, every day",
                    "org": "ASPCA Animal Poison Control Center",
                    "source": "https://www.aspca.org/pet-care/animal-poison-control",
                    "tel": "+18884264435"
                },
                {
                    "audience": "owner",
                    "display": "(855) 764-7661",
                    "fee": "$89 for each incident",
                    "hours": "24 hours, every day",
                    "org": "Pet Poison Helpline",
                    "source": "https://www.petpoisonhelpline.com/about/",
                    "tel": "+18557647661"
                }
            ]
        }
    },
    "notice": "Emergency telephone numbers for animal poisoning. Each country cites the operator page the entry came from and the date a person read it. Services close and numbers change, so check an entry before you rely on it. Coverage is not global. A country in this file with an empty services list has been checked and has no service an owner can call. A country that is absent has not been checked.",
    "updated": "2026-09-10"
}

I felt wrapping it in an envelope was the correct approach here. It leads with the notice and the date I last changed anything. A .countries object follows, keyed by ISO 3166-1 alpha-2 code. At the very least, it gives me room to change a country’s metadata later without breaking the top-level shape.

The audience field on each service is what carries the Dutch problem into the data. It reads either owner or vet. A vet entry means the number exists but you can’t ring it yourself, so the entry tells you to phone your vet and let them make the call.

Anyway, along with some stylistic changes and code cleanup, that’s pretty much all there is to it for this update. I’ll be giving Plant🌱Smart a rest for a bit while all the changes settle in. This gives me some time to work on other fun things!

Enjoy, nerds!

The database lost some weight.#

Originally, the plant database held around 480 records. It now holds around 280, so roughly 200 records are gone. About 170 of them came from a single symptom list and all of them included “cardiac failure”. That one symptom pushed every associated record to the top severity level. They read as “critical” because of the shared symptom list, not because of the plant itself. The list came from older sourced data that I never properly scrubbed and vetted, so I nixed those records entirely from the primary data set.

Sucks, but a smaller database you can trust beats a bigger one you cannot.

How I source vetted data.#

At the moment, I check each record against the following authoritative data sources:

• The ASPCA toxic plant list. It gives the clinical signs for dogs, cats and horses. This is the original reference that started the project way back in December of 2022.
• The Guide to Poisonous Plants from the College of Veterinary Medicine and Biomedical Sciences at Colorado State University. It gives the clinical signs for each body system and it names the animals that the plant affects. It is stronger than the ASPCA list on horses and other farm animals.

Every one of the 280 or so records that remain traces back to at least one of these two references. This is a hard requirement. If a plant can’t clear it, it doesn’t get a record.

Both references are copyrighted material. I cite them and link to them directly without publishing any of their text. Each record holds my own symptom names only. If you’re curious, the attributions page lists every licensed source used to build the site.

If you know of another authoritative data set that covers animals, the plants that are toxic to them and the associated symptoms, please let me know in the comments below or on the contribute page.

What I removed, specifically.#

I removed the inaccurate records and enriched and corrected the rest. These changes break down into three groups.

1. The old data set covered seven animal types. The update reduces coverage to cats, dogs and horses. That doesn’t mean I’ve given up on birds, fish, reptiles and small mammals. If I find good data for any of those groups, they go straight back in. Until then, they’re parked.
2. I also changed the rule that sets the severity level of each record. The old rule just took the worst symptom on the record. Now there’s an extra condition: a record with a single “critical” symptom and no “severe” symptoms gets marked “severe” instead. Nothing huge, but I felt it was worth mentioning.
3. A handful of records turned out to be duplicates, so I merged them.

The plant index is now a “Field Guide”.#

Reddit user u/Abbot_of_Cucany mentioned that their bird guide indexes each species twice: the common name in plain type and the scientific name in italic type. I thought this was a great idea, so I built it. Of course, I got a little carried away, so the page now also holds a filter box. Type part of a name and the page shows every matching plant on record. A letter row sticks to the top of the screen while you scroll and it marks the letter you’re currently reading through.

The front page got some filter updates!#

Some people requested more filters, so I delivered. The additions cover severity, plant shape and the geographical regions where you might come across a plant in the wild. Those last two data points were already sourced, but not really in use. At least not in any obvious way. I also added a newer, tighter, photo-centric grid view for smaller screens. Personally, I think it looks good, but I’m not sure if I’m going to keep it. Let me know what you think!

The extra dropdowns squished everything together in the filter bar, so I had to rethink how to display them. I replaced all the individual dropdowns with a single multi-level filter menu. You can now click around and filter as you go. I also shrank the icons a bit to save more space, but they expand when you hover over them with a mouse or tap them on a small screen.

Also, worth noting: your filter selections stay in the browser between visits.

The data for the “Found in” filter comes from GBIF, the Global Biodiversity Information Facility. GBIF counts the wild sightings of each plant in each country. A country counts as a match when it holds one percent or more of the sightings for that plant. It’s a totally arbitrary, non-scientific threshold that I imposed to keep the country list as tight as possible.

Safe plants get a facelift!#

The safe plants list now holds over 30 common household plants. The new entries include the spider plant, the bamboo palm, sage and baby’s breath, among others. A new entry joins this list only when the ASPCA marks the plant as non-toxic and only when the plant is absent from my own database. Each entry also carries a note that names the toxic plant people confuse it with. For instance, bamboo palm is safe while sago palm is deadly.

Based on a couple of user suggestions, each safe plant also includes a small gallery of three related photos sourced directly from the naturalist community at iNaturalist. Clicking a photo opens a lightbox with a zoomed-in view along with attribution and licensing information.

It now has a blog… sort of.#

This part wasn’t a suggestion. In addition to the updates page, I thought some kind of small blog would make sense. The articles I write about the site live here, where visitors to Plant🌱Smart will most likely never read them. So, instead of building actual blogging functionality, I decided to syndicate the articles from here. I updated my Hugo templates to generate an RSS feed for each tag. Every article about Plant🌱Smart carries the plantsm.art tag, so the site can ingest all the relevant content on its own.

The page shows one featured note first, just the latest entry in the list. Five recent notes follow as cards. Finally, an archive section gives one row per note, grouped by year. There’s just not enough content at the moment to fill that section out, so it stays hidden for now. Also, something you can’t see just yet: a text filter appears after 15 or so entries and works just like the one in the field guide.

Finally, some changes to the API.#

The API gives one file for each animal in the database. Since the data scrub, four of those files no longer exist: birds.json, small-mammals.json, reptiles.json and fish.json. The database itself no longer holds plant records for those animals. The API page documents the files that remain. Every other endpoint and every other shape stays the same.

What’s next?#

I want the other four animal types back. A rabbit owner needs this data as much as a dog owner does. I’m on the lookout for a reference that gives the symptoms per plant for birds, fish, reptiles and small mammals, but there’s just not a lot of authoritative data out there. If you know of one, tell me in the comments below or on the contribute page.

I also want those 170 records back, but each one needs a reference that names the plant and gives the clinical signs. Until then, they stay on the back burner.

That pretty much covers it. It’s been a fairly hectic week of coding and rolling out updates, but it’s been a lot of fun. At the time of writing, the Reddit post sits at over 530 upvotes! It’s always risky sharing something you’ve made with the world, but more often than not, people appreciate it. It really put a smile on my face.

Till next time!

Well, I finally did the thing.

Three and a half years ago I wrote Why I Built Plant🌱Smart. A free and searchable database of plants that are toxic to pets. I built it over a holiday break to answer a simple question, “Can I bring this plant home without endangering the fluffy little gremlin that runs our household?” It was also my excuse to learn SvelteKit, TypeScript, TailwindCSS and Vite, because my frontend peers wouldn’t shut the hell up about them.

The site then chugged along quietly and untouched for years, which sounds like a compliment to its architecture and very much is not one to the maintainer.

The toolchain aged like fine milk.#

The thing no one really thinks about when they build something like this with shiny new frontend tools is that it doesn’t rust, it curdles. When I finally came back to give Plant🌱Smart a fresh coat of paint, the build no longer ran. Not “a few deprecation warnings” didn’t run. It didn’t run at all. Two years of an unattended package.json had fermented into something of a cheese-like consistency.

My original requirements list from 2022 said the site must be fast, static, ( almost ) free to run and open with its data. Nowhere did it say “must still compile in two years”.

So, I decided to spend a few weeks off and on to throw out the toolchain and give it a much-needed refresh. Just like this site, Hugo now builds the entire thing. There’s a single hand-written stylesheet and a few small scripts of delicious vanilla JavaScript. No npm install, because there is no longer anything to install. If I disappear for another two years ( likely ), the site will build exactly the same the day I come back.

First things first, absolute parity.#

The rebuild had one rule that saved me from myself: the first pass had to be a 1:1 replica of the old site. It needed the same pages, filters, URLs and quirks. The pass was meant to be boring on purpose. I had to resist the temptation of doing both the replatforming and redesigning all in one go.

My primary constraint was the plant data. Plant🌱Smart’s whole gimmick is what I called a “dumb API”. The entire primary database lives in one JSON file with other, smaller, supplemental files you could use as lookup tables. Since this was all hosted on Cloudflare’s CDN it was effectively free to use for others without keys or annoying rate limits. The old derivations were originally done by a pile of Go magefiles. The new site had to reproduce them exactly, down to the deliberately unsorted first-appearance ordering, or every downstream consumer would notice.

Hugo, it turns out, can do all of it. A content adapter reads the database and births every plant page directly with no intermediate files. A handful of templates re-implement the old Go derivation logic and regenerate the API on every build. I diffed the generated files against the originals and they came back value-identical on the first honest attempt.

Then came my favourite commit of the whole project:

retire the sveltekit stack: remove src, magefiles and the node toolchain
566 files changed, 112 insertions(+), 9905 deletions(-)

I deleted nearly ten thousand lines and the site did more than before. This is every developer’s favourite kind of commit.

I made the site cute on purpose.#

With the replica shipped, the redesign could actually be fun. The old site was fine but it was very much “2022 Tailwind starter” vibe. A lot of cool greys, hard shadows and gradients on anything that stood still. Meanwhile the logo, a randomised squishy little pastel potted plant with a face, deserved better surroundings.

So, I set out to make the logo the design brief. Cream paper instead of white with warm espresso ink instead of a dull grey. Sage and moss greens with honey and clay accents were all lifted straight from the icon set. Every shadow is tinted warm because plain black shadows on cream look like stickers. The corners got a bit rounder and the controls became pills. The whole thing is set in Fredoka, a rounded display face that weighs about 30kB which I thought fit perfectly with the cute little mascot.

Here are a few before and after shots of the main content pages, with a bonus shot of the new pill navigation that smaller screens finally got:

The data enrichments will continue until “Morella” improves.#

Get it? No? Ok, I’ll see myself out.

The database had severity ratings for every plant, computed from symptom groupings and the old site displayed them precisely nowhere. Now, every card has a severity pill rated from Mild to Critical. The pills are also clickable filters on the main page’s plant cards. Search happens as you type and if you fumble the Latin a bit, a little Levenshtein pass offers “Did you mean Lilium?”. I thought this was a little bit more helpful than what the old site did after literally joking about spelling mistakes in its empty state.

A few other mentionable updates:

• A safe plants list, because the site only ever told you what not to buy. Every entry has to clear the ASPCA non-toxic list and be absent from my own toxic database before it’s allowed in.
• A symptom finder that allows you to perform a plant search backwards. You can click on multiple symptoms and it’ll filter accordingly.
• An emergency strip on every plant page with the poison-control hotlines. Unfortunately, for now, these are US numbers. Localising them by region is on the roadmap.
• Wikipedia descriptions for nearly every plant credited under CC BY-SA.
• Around 3,000 common-name redirects, so /plant/peace-lily/ finally lands somewhere useful.
• Because it made sense, the whole thing is now a PWA and works completely offline. So, now you can use the site in a greenhouse with no signal, which is precisely where this site is most likely to get used.

Once I started auditing the data properly, I started to see a few additional gaps. There were several plants with multiple entries under different, but similar, names. I deduped and merged the symptom data and also updated the severity groupings to make more sense.

I also quickly realised that merging seizure into seizures would have silently promoted over a hundred plants to “Critical”. The severity groups treated those two spellings as different levels. The little cleaner script I threw together caught it during a dry run. The script grew a rule about never merging across severity levels as a result. The plants that genuinely deserved promotion got one. For instance white snakeroot, the plant that killed Lincoln’s mother, was somehow rated “Severe”. The script properly re-rated it to “Critical”.

The enrichment didn’t stop there. I sourced proper taxonomy for every record via GBIF, per-plant toxicity principles with a glossary and little world maps showing their native origins.

There was also quite a bit of fat to trim.#

Somewhere in all this I noticed every page weighed over 200kB. This included pages that were basically just copy. The culprits were painfully self-inflicted. There was an 85kB inline script shipping all ten animated logo SVGs to every single page. The same animal icon inlined seventy times on the front page. Oh, and let’s not forget my personal favourite, the attributions page carrying 149kB of pure indentation that a template loop had quietly emitted. I was shipping whitespace at scale.

The fixes were old-school and very satisfying. A single fingerprinted and cached JS bundle, SVG sprites so each drawing only ships once and one well-placed whitespace trim yielded the following results:

No framework was harmed, or indeed present, in the making of this facelift.

We ship from the homelab now.#

The last box to tick from the original post was the bittersweet one. In 2022 I wanted the project “open-source and community-driven” on GitHub. In practice, the community contribution was me, at midnight, fixing my own typos. So, the repository followed this blog into my homelab using the exact same moving parts as outlined in My Blog Now Ships From My Homelab!. It just made sense after this site’s migration. The data remains as open as ever through the API, which was always the part worth opening. That will never change.

While migrating I had a small panic about the 315MB of plant photos sitting in my working tree, imagining every CI build hauling them across the network. Turns out my 2023 self had already gitignored them and the entire repository clones at 7.5MB. Every once in a blue moon past me does something right. I’ve decided to let sleeping dogs lie and not investigate what else he buried in there.

Was the juice worth the squeeze?#

Very much so. The site is faster, cuter and finally says the most important thing it knows on every card: how dangerous is this plant, not just whether. It builds from nothing with a single binary and deploys itself when I push. The data is cleaner and more robust than it has ever been and enriched well past what 2022 me had the patience for.

But the honest win is the same one as the blog demolition. The whole thing is now boring to operate and boring is what lets a hobby project survive its maintainer’s attention span.

If you have a plant-curious pet, Plant🌱Smart is free, the API is free and the safe list might even let you buy something nice for yourself. And if four years from now there’s a third post in this series, may it be shorter than this one.

Anyways, adios…

So, having been bitten several times by intermittent outages and service disruptions, I figured a small personal win would be to migrate the repository for this site to the homelab. Now, it lives on my own Forgejo forge and the builds run on my own Woodpecker cluster. The only things that leave the network are static build artefacts that get pushed up to Cloudflare Pages.

The switch was surprisingly straightforward and took less than 30 minutes overall.

Before anyone reaches for the comment box, no, you don’t need a homelab for any of this. Forgejo and a Woodpecker cluster ( server and at least one agent ) will happily run on a spare mini PC, an old laptop, that Raspberry Pi you bought with the best of intentions or even as a single Docker Compose file running on the machine you use every day.

How complex can this possibly be?#

The first useful thing I did was ask myself what GitHub was actually doing for me when it comes to managing this site. After some mulling about, I could only really list the following:

• Hosting a git repository.
• Hosting the comment threads, via giscus Discussions.

That’s pretty much it. I don’t use Actions and GitHub alone never built this site. Cloudflare Pages watched the main branch and did the building itself. This is something I covered back in My Blog Publishing Setup. GitHub’s one job was holding a bunch of markdown files.

That’s a strange thing to accept as a single point of failure.

The new shape of things.#

The replacement looks like this:

• I push to Forgejo, which lives inside my homelab network.
• Forgejo fires off a message to the Woodpecker Server over a webhook. Also inside the network.
• The Woodpecker Server assigns the job to an available Woodpecker Agent, which clones the repo, builds the site with Hugo and pushes the result to Cloudflare Pages with wrangler.
• Cloudflare serves the files at the edge, exactly as before.

I just added support for mermaid diagrams, so of course I’m not going to let the opportunity to show it off slide:

The part I want you to notice is the direction of travel. Under the old setup, Cloudflare reached into GitHub to pull my source. Under the new one, nothing reaches in at all. The forge and the CI server accept no traffic from the internet. The only packet that crosses the network boundary is an outbound upload of compiled static assets.

That reversal is the entire security model which was pretty much the point. What looks like “the old way but more steps” allows me to control every aspect of the pipeline up to just before we ship the build artefacts. A push-based deploy means self-hosting your forge requires exposing exactly nothing. No reverse proxy gymnastics, no VPN for the webhook and no port forwarding required.

If my homelab bursts into flames mid-afternoon ( a real possibility as I do live in Queensland, Australia ) Cloudflare keeps serving the last deploy and nobody visiting the site would ever know. That being said, nobody actually does visit this site, so…

A small intermission.#

A short aside, because it’s a question I’d ask. My internal services hang off a domain I genuinely own, but resolving it depends on where you’re standing. Inside the network a locally hosted 3-node Technitium cluster runs the hosted zone and the router sends all DNS requests through it. Initially, I used this for network-wide adblock, which works an absolute treat. It also means the forge and the CI cluster resolve to their internal addresses. Outside the network, the public zone points at a landing page hosted elsewhere.

Same hostname and two completely different worlds depending on which side of the wall you’re on. Split-horizon DNS is nothing new, but it’s what lets me use real TLS-friendly hostnames for internal services without those services ever being reachable from the internet.

If I did decide to open some services to the outside world, like my Navidrome server, I could use an overlay network like Netbird to provide friends and family access via a familiar naming convention without ever opening a port on the router.

The part Cloudflare doesn’t clearly advertise.#

A Pages project is either connected to a git provider or it accepts direct uploads. Never both. As long as your project is wired to GitHub, wrangler pages deploy will be rejected and you will get screamed at.

Disconnect the git integration in the project settings and the project quietly converts to “Direct Upload” mode. It keeps its name, its custom domain and its whole deployment history. It just stops watching a repository and starts waiting for you to hand it those delicious files. While you’re in there, make sure the production branch is properly specified: main in my case. This matters because Wrangler tags each upload with a branch name. An upload whose branch matches the production branch goes live on the site. An upload under any other name becomes a preview deployment with its own URL instead.

After that, the deploy is one command requiring two secrets:

• An API token scoped to Cloudflare Pages: Edit
• Your Cloudflare account ID.

Both go into the Woodpecker Server as repository secrets.

Finally, our favourite! YAML.#

The whole thing is just one file named .woodpecker.yml that squats in the repository root.

when:
  - event: [push, manual]
    branch: main

clone:
  git:
    image: woodpeckerci/plugin-git
    settings:
      partial: false
      tags: true

steps:
  diagrams:
    image: minlag/mermaid-cli:11.16.1
    commands:
      - ./bin/render-diagrams

  build:
    image: hugomods/hugo:debian-git-0.163.3
    environment:
      HUGO_ENV: production
      HUGO_ENVIRONMENT: production
    commands:
      - git config --global --add safe.directory '*'
      - ./bin/changelog
      - hugo --gc

  deploy:
    image: node:22-slim
    environment:
      CLOUDFLARE_API_TOKEN:
        from_secret: cloudflare_api_token
      CLOUDFLARE_ACCOUNT_ID:
        from_secret: cloudflare_account_id
    commands:
      - >-
        npx --yes wrangler@4 pages deploy public
        --project-name=wilhelm-codes
        --branch=main
        --commit-hash="${CI_COMMIT_SHA}"
    when:
      - event: push

Only build off main.#

I test design changes and new entries locally, so a push to any other branch doesn’t start a pipeline.

We want a full clone, not a shallow one.#

This site’s changelog page renders the git log and Hugo’s enableGitInfo reads commit dates for every page. This is something I wrote about in A Changelog That Builds Itself. CI systems love shallow clones and a shallow clone here means I can’t convey the full historical picture on the page. Worse, enableGitInfo derives every article’s dates from that same truncated log, so they all come out wrong besides. Setting partial: false makes Woodpecker fetch the entire history.

Diagrams render before anything else.#

Articles on this site can embed Mermaid diagrams, like the sequence diagram further up the page. They render to static SVG at build time, not in your browser, so the site ships zero diagram JavaScript. A small script hashes each diagram’s source, renders anything that has no matching SVG yet and prunes any SVG nothing references any more. I run it locally and commit the SVGs alongside the content, which means on a clean commit this step does precisely nothing. It exists as a safety net for the day I inevitably forget.

So when I said the diagram was rendered by the pipeline it describes, I meant it literally. If I ever edit that diagram and forget to render it, this step is what quietly saves the deploy.

The build step is a stock Hugo image.#

Nothing is installed on the agent itself unless you count Docker image pulls. The image pins the exact Hugo version, ships the extended edition and includes git and bash. Both of which the changelog script that generates the data requires. The safe.directory line exists because the cloned workspace is owned by a different user than the one inside the container and git these days refuses to read a repository it thinks you stole.

The deploy step is a stock Node image.#

npx pulls Wrangler at run time. Wrangler then reads the two secrets from the environment and pushes public/ up to Pages and that’s pretty much it. Dependencies are snagged and cached at build time, which means nothing to maintain on the agents. Either step’s version gets bumped by editing one line.

Complete parity with what Cloudflare’s own build pipeline was doing, except now I can read every line of it and make it do whatever I need.

I did run into some speed bumps along the way.#

For the record, it took only three tries to get the pipeline to a “green” state.

In order of discovery:

• The plain version tags of the Hugo image are the extended edition. The reg- prefix means regular and none of them include git unless the tag says git. The tag you guess first ( exts-<version> ) doesn’t exist. It’s an odd convention, which is why it threw me off.
• Woodpecker substitutes ${VAR} expressions in the YAML before the shell ever runs. Anything it doesn’t know becomes an empty string. My safe.directory "${CI_WORKSPACE}" quietly became safe.directory "". Hence the asterisk / glob in the YAML.
• The changelog script opens with #!/usr/bin/env bash and the default Hugo images are Alpine. env: can't execute 'bash' is the whole error message you get, so I just went with the Debian variants instead which include bash out of the box.

None of these are hard problems, but worth pointing out.

I’m not deleting the old repository… completely.#

The GitHub repository still exists if only to provide a place for the giscus integration to store comments. It offloads most of this functionality to GitHub’s Discussions feature. Delete the repo and every comment ever left on this site goes with it; all 2 of them.

It no longer needed the full source history to do that job either. It was ported on over to my local forge with Forgejo’s native GitHub repository migration feature. So, I force-pushed the whole history into a black hole, leaving a single commit containing only a README. The remaining husk also has a second job coming; it’ll eventually host the companion code for tutorial content, so readers can clone examples without ever touching my forge.

Each service kept exactly the job it’s uniquely good at. Cloudflare serves files from the edge better than my house ever could and no fucking way am I publicly opening ports on a router. I’d rather lick the rim of a pub toilet. GitHub Discussions gives commenters an identity they already have. Everything else now lives at home.

In closing …#

Was any of this necessary? For a static blog that deploys in under a minute, probably not. The old setup worked fine and if yours does too, keep it. I’m not here to convince anyone.

There’s a special kind of satisfaction in watching a pipeline run end to end on hardware you can physically point at, knowing the only cloud dependency left is the one actually earning its keep. The next GitHub outage can happen without me. At least for this project anyway.

Let’s get v0.1.5 out of the way first.#

There’s not much to see here, honestly. This is a routine housekeeping and dependency bump release. The only change worthy of a mention is is a bump of golang.org/x/text to address GO-2026-5970. This is the sort of thing you patch promptly even when the practical exposure for a tmux wrapper is nil ( ha-ha-ha ). Alongside that, the Go toolchain moved up to 1.26.4 and testify, urfave/cli and a stack of GitHub Actions all got their routine nudges courtesy of Dependabot. Hey, thanks little buddy!

Download the latest release, replace your current binary and you should be good to go.

v0.1.4 is where the features live.#

Back in July I wrote about adding typed variable blocks to Glazier. That work shipped on July 17th as v0.1.4.

The short recap, if you didn’t read that post is that profiles can now declare the inputs they accept as first-class variable blocks. Just like, you guessed it, Terraform. Each block can carry a primitive type (string, number or bool), a default and a description. No default means the variable is required. Pass a --var the profile never declared and you get a proper located error.

Values are read through the var. namespace and only that namespace:

variable "district" {
  description = "the district the gig is themed after"
  type        = string
  default     = "watson"
}

variable "fixer" {
  type = string
}

session {
  name = "gig-${var.district}"

  window {
    name = "${var.fixer}-ops"

    pane {
      commands = ["echo ${var.fixer} has the next job"]
    }
  }
}

$ glaze up --var fixer=wakako
$ glaze up --var district=arasaka --var fixer=wakako

That post covers the design reasoning, the type coercion and the breaking namespace migration in detail. So, no need to reshash it all here. What it doesn’t cover is everything else that snuck into the release after I hit publish button.

Support for locals.#

Variables are inputs. They cross the boundary from the outside world into your profile via --var flags, var files or defaults. But the moment I had proper variables I ran into their natural companion problem; derived values. The thing you compute from an input once and then want to reuse in five places without copy-pasting the same expression five times.

Terraform solves this with locals and, because Glazier remains an unapologetic love letter to Terraform’s parser, it does as well:

variable "district" {
  default = "night city"
}

locals {
  slug    = lower(replace(var.district, " ", "-"))
  session = "gig-${local.slug}"
  logfile = "${path.pwd}/logs/${local.slug}.log"
}

session {
  name = local.session

  window {
    name = "${local.slug}-ops"

    pane {
      commands = ["tail -f ${local.logfile}"]
    }
  }

  window {
    name = "editor"

    pane {
      commands = ["nvim"]
    }
  }
}

You declare named values in a locals block at the top level and read them back through local.<name>. Plural block and a singular reference is exactly how Terraform does it.

A local can reference the var.*, env.*, path.* namespaces, the whole function library and, crucially, other locals. In any order. This works fine:

locals {
  session = "gig-${local.slug}"                    # references slug...
  slug    = lower(replace(var.district, " ", "-")) # ...declared after it
}

Under the hood resolution just keeps iterating, evaluating whatever it can each pass until the end. Whatever’s left over then reports its real evaluation diagnostics, so a genuine fat-fingered mistake surfaces as the actual error rather than being masked by ordering machinery. If you accidentally declare the same local twice you’ll get told exactly where both declarations live.

The one thing you can’t do with a local is set it from the command line and this is by design. Variables are the contract with the outside world; locals are private. If a value should be overridable, it’s a variable. If it’s just an expression you’re tired of repeating, it’s a local. Having the language enforce that distinction is one of those small things that keeps a profile clean as it grows.

They also pair nicely with the new random function and HCL’s inline comprehensions, both of which landed in this release too:

locals {
  editors = ["nvim", "hx", "vim"]
  greeting = random([for g in ["hello", "choom", "wake up samurai"] : title(g)])
}

random(list) returns a uniformly random element of a list as a string. Did anyone ask for this? Absolutely not, but you deserve nice things.

lol… lmfao.#

The July post ended with me musing about adding *.tfvars-style functionality and asking, and I quote, “Surely, I won’t fall for this again?”

Yeah, so v0.1.4 also ships with --var-file support:

# gig.vars
district = "japantown"
fixer    = "wakako"

$ glaze up --var-file gig.vars
$ glaze up --var-file gig.vars --var fixer=dino

A var file is plain HCL; a name = value attributes written once per line. I originally supported JSON files too and then ripped that out before release, because maintaining a second parse path for a format nobody was going to use failed the smell test. In other words, “YAGNI”.

Precedence works the way you’d expect: defaults go first, a var file overrides defaults and an explicit --var flag always has the final say. In the second command above fixer comes out as dino no matter what the file thinks.

Strictness from the flag side applies here too. An entry in a var file that names a variable the profile never declared is an error. Values are coerced to their declared types and every problem in the file is reported all at once for convenience.

Our first contributor has entered the chat!#

This release contains the first fix from an actual outside contributor. ThreeToes tracked down an annoying initialisation bug where the first window in a profile would be ignored and cleaned up on startup. Leaving you with either a stray default terminal or only the subsequent windows.

Someone who isn’t me not only ran the thing, they read the source and fixed it. That’s a genuinely lovely milestone for a hobby project. Thanks, man!

Oh, and the repo finally has a proper SPEC.md. A full reference for the profile format describing every block, namespace and function.

In closing …#

Release notes are like backups. Everyone agrees they’re important and nobody does them until it’s embarrassing.

As always, it’s up on GitHub under MIT. If you’ve got Go installed:

$ go install github.com/wilhelm-murdoch/glazier/cmd/glaze@latest

Or, grab a prebuilt binary from the releases page, checksums and provenance attestations are included. Small note on this, I do plan on adding support for all your favourite package managers to make this process a bit more intuitive. Homebrew first as a test run, then all the other you’d expect.

If you’ve opinions on locals, var files or what Glazier should learn next, the comments are right below.

P.S. - I’ve another secret project in the works and I’m using it to declaratively generate Open Graph social cards for the blog. I thought I’d create a format dedicated to Glazier releases.

So, of course just weeks later I have this burning desire to nuke it all from orbit!

To be clear, the June cleanup wasn’t wrong. The pipeline was genuinely tidy. But, a tidy pipeline is still a pipeline and somewhere between then and now I started asking a more annoying question: why does a personal blog, a pile of static text, need a JavaScript toolchain at all? Why do I need to buy into the Tailwind framework when I knew full well how to write vanilla CSS with my own hands? Every npm install was a little tax that I’d eventually have to pay with interest the next time I wanted to update the site’s dependencies. I felt as if I wasn’t maintaining a blog. I was maintaining the machinery that produces a blog and the machinery had some very strong opinions.

So, I did a hard reset with a very satisfying amount of deleting.

The demolition …#

Here’s the bill for the redesign commit:

230 files changed, 3951 insertions(+), 33365 deletions(-)

That’s roughly a 10-to-1 ratio of deleted to written. Which, as a software engineer, is my favourite kind of ratio. I happily added the following the to chopping block:

• Tailwind v4 and the typography plugin. Replaced by one hand-written CSS file. The whole thing gzips to under ~10kB with syntax highlighting included.
• The entire Node toolchain. The package.json, lockfile, Prettier and its plugins. There is no npm install step anymore because there is no npm anymore.
• Fuse.js and the ⌘K search palette. Nobody was searching this blog. I checked. It was me. I was nobody.
• Two self-hosted webfonts. More on this in a second, because it’s the biggest single win.
• The changelog page. This pulled from the GitHub events API and shipped with an 18,016-line JSON fixture for local dev. Eighteen thousand lines of someone else’s API response, committed to my repo. So, a page barely anybody visited could render in development. I mean, I added it back becase I missed it, but it’s much more efficient now.
• 68 of the 79 icon SVGs. A 390-line drawer menu and a taxonomy I’d stopped using.

The layouts went from 2,868 lines of template across 48 files to about 800 lines across 21. Not because I got cleverer, but because most of that code was written for the joy of it. Which, look, is a fine reason to build something. It’s just a bad reason to keep serving it to strangers. And with all that complexity and cruft came what felt like a lot of brittleness.

The fonts had to go too.#

This one hurt a little. I like Inter and Rubik. Together they were 449kB of woff2 riding along on every first visit. Which made them, by an enormous margin, the heaviest thing on the site.

So, I dropped them and switched to the system font stack which, to my surprise, actually looked better on the site. The actual typeface was doing very little. Your operating system already ships a perfectly good set. All lovingly hinted by people with far more patience and experience than myself. Best of all it costs zero bytes to use!

Hugo, finally home alone.#

Thanks to all the trimmed fat, the build process is effectively just hugo. No more extended binary, SCSS, image processing or defining NODE_VERSION in Cloudflare Pages required. Fewer dependencies mean fewer moving parts and that’s always an improvement.

Numbers, or it didn’t happen.#

Right after the deploy I proudly measured the new site and announced it was “under 100kB”. Which would have been true if the production site were served by my dev server, uncompressed, with a 40kB livereload script attached. I made the mistake of measuring the network stats on my local development server. Womp, womp.

The real numbers, from the live site with Cloudflare’s brotli doing its thing:

The single largest asset on the home page is now the favicon. 7.5kB; roughly a third of the total weight. I think you’re allowed to stop optimising when your largest single asset is your favicon.ico. It’s an image of my gorgeous mug. It stays. I’m quite attached to it.

An ambitious first pass.#

In retrospect, I wanted to make everything simpler and unintentionally over-compensated in the opposite direction. I stripped out too much and was now staring at a sad little blog with zero personality.

So, the second half of the job was building the personality back and making my selections a bit more deliberate. One thing led to another and I think I’ve produced my finest work yet on a personal blog. It’s small and lightening fast. I’m not sure where else I can optimise without drastically affecting the overall vibe of the design; the law of diminishing returns… returns.

The thing about now having such a light frame is adding to it stops feeling like a burden, or something future Wilhelm will have to pay. For example, here are the biggest things I’ve added and they barely increased the overall “weight” of the design.

Series#

A proper taxonomy for multi-part writing. Built because I’ve been wanting to write a Cyberpunk-themed set of tutorials for writing advanced HCL in Go. The series will be about eight posts long and outside of sharing a tag, I had no way to string them together. Series posts wear a stacked-sheet card, a segmented progress meter that is absolutely not a cyberdeck RAM readout and a panel showing every part in the run, including the ones that don’t exist yet.

The unpublished parts of a series ship as glyph noise and decode, left to right, when you point at them. The real titles sit in aria-label the whole time, so a screen reader is never handed the static. The browser tab pulls the same trick on every page load, because a title bar is just a very small marquee nobody was using.

Try moving your mouse pointer over some of the “encrypted” titles on the new dedicated page.

Tired LEDs#

The lit chips in the series meters, static leaders in the main page’s hero section and a scattered handful of cells in the activity graph flicker like hardware that has seen some things. Their animation clocks share no common factors, so the pattern never visibly repeats. The same no-RNG randomness as the heading glitch. On page load the whole graph boots like an old panel, dark, then a sputter per cell, then steady stream of blinking boxes. Reminiscent of the old monochrome screens and beige boxes of my youth.

Christ, I’m getting old.

Changelog, resurrected#

Yes, the one from the butcher’s block above. However, instead of hitting the associated Github repository directly at build time using a PAT, the new one doesn’t call anyone. Commit data is sourced directly from Cloudflare Pages’ shallow clone it checks out during build time. There’s a simple 20-or-so-line shell script reads git log and Hugo renders the result. HEAD gets a lit node that flickers, because why the hell not?

Image shortcodes#

Something I’ve been meaning to add is support for various ways to display images. Each image can now be clicked-to-zoom with attribution in the following forms:

• Masonry.
• A scrollable, horizontal display.
• Last, but not least, the typicla single image display.

There’s actually a sneaky, super-secret page I use to test all my shortcodes and typography stylings where you can see everything for yourself.

Even with all these complex additions, it all adds up to a few kilobytes of CSS and inline script. Which is to say the entire second wave of features weighs an order of magnitude less than one of the webfonts I deleted.

My new favourite fidget toy.#

The part I didn’t expect was to glue my eyeballs to the Firefox throttle menu under its network tools panel.

I flipped it to a 2G profile just for shits and giggles - call it a generous 50kb per second - and did the napkin math. The old site’s 750kB works out to between 60 to 90 seconds of staring at a blank viewport. The new site lands in about four seconds on a connection profile most of the industry stopped thinking about a decade ago.

I have reloaded this page on simulated garbage networks far more times than any reasonable person should, and it is satisfying every single time. The page just… appears. Like a website. Remember plain’ole websites?

None of this is novel, I know. The “your blog doesn’t need 2MB of JavaScript” essay has been written a hundred times. Usually on a blog serving 2MB of JavaScript. I’m not even the hundred-and-first person to do this. But, there’s a difference between nodding along to the idea and watching your own site load over a simulated tin-can connection before you can finish blinking.

In closing …#

The funny thing about the June post is that it ended with me feeling like the blog was finally sorted. And it was! For the architecture it had. It just turned out the architecture itself was the thing that needed to go.

The site is now boring in the best possible way. It builds with one command, it has no dependencies to rot behind my back and the whole design fits in one stylesheet I can actually hold in my head ( not really ). Fewer moving parts, fewer things to forget, fewer surprises the next time I touch it in six months. Best of all, it looks fucking great!

Set-and-forget, but this time with almost nothing left to forget. … Right?

There’s a line in my shell history that goes back to 2022: go get github.com/wilhelm-murdoch/go-collection. For years it was the first dependency into almost every Go project I tinkered with, sometimes before I’d even give the idea a solid shape. I’d open Neovim, initialise a module and then my little collection library got pulled in. Just like muscle memory.

Today I’m archiving it. Not because it broke and not because I got bored of it, but because the Go standard library quietly walked up and did its job better than it ever could. This post is part explanation and part eulogy, because I think we’re generally quite bad at ending software on purpose and it’s worth practising in public.

Why even write it in the first place?#

Waaaay back in 2022 Go 1.18 had just shipped generics after roughly a decade of the community asking, arguing and writing increasingly unhinged interface{} workarounds. I wanted to actually learn the new type parameter machinery rather than just read about it and I was also deeply tired of writing the same for loop to check whether a slice contained a thing for the hundredth time.

So go-collection happened. A single generic Collection[T] type wrapping a slice, with all the conveniences I kept reaching for: Contains, Find, Filter, Map, Sort, Batch, Push, Pop and a few dozen friends. All chainable, fluent, tested and small.

That sentence was doing more work than I realised at the time. It wasn’t trying to compete with the big functional-utility libraries. It was scratching a personal itch and for a few years it scratched it well. Then Go’s standard library grew and slurped most of it up.

Taking a trip to the morgue.#

Cause of death is easy to establish here, because it happened in three well-documented releases. Go 1.21 shipped the slices package. Go 1.22 and 1.23 finished the job. Let’s walk through it, method by method, like the nerds we are.

Does it have the thing?#

The bread and butter. Probably eighty percent of my actual usage of this library was some flavour of “is this thing in there?”:

fruits := collection.New("apple", "orange", "strawberry")

fruits.Contains("orange") // true

fruits.FindIndex(func(i int, item string) bool {
	return strings.HasPrefix(item, "str")
}) // 2

As of Go 1.21, the standard library does both on a plain slice with no wrapper type in sight:

fruits := []string{"apple", "orange", "strawberry"}

slices.Contains(fruits, "orange") // true

slices.IndexFunc(fruits, func(item string) bool {
	return strings.HasPrefix(item, "str")
}) // 2

No New, no .Items() to unwrap at the end when some other API wants a real slice. It’s just my function with better ergonomics and a compiler team maintaining it. I’m fine with this.

Sorting, where I don’t even get to feel bitter.#

Here’s my Sort. I want you to look at what using it actually required:

numbers := collection.New(3, 1, 4, 1, 5)

numbers.Sort(func(i, j int) bool {
	left, _ := numbers.At(i)
	right, _ := numbers.At(j)
	return left < right
})

Index-based comparators, so you had to reach back into the collection you were currently sorting to get at the values. I inherited that design from the old sort.Slice idiom and it was clunky then too. The modern equivalent:

numbers := []int{3, 1, 4, 1, 5}
slices.Sort(numbers)

And when you’re sorting something with actual structure, SortFunc hands you the two elements directly, with cmp.Compare doing the boring part:

slices.SortFunc(people, func(a, b Person) int {
	return cmp.Compare(a.Age, b.Age)
})

This isn’t a case of the standard library catching up to my library. It blew my version right out of the water.

The killing blow came with iterators.#

Go 1.22 added slices.Concat, which retired my Concat. Fine, that one was three lines anyway. But Go 1.23 shipped range-over-function iterators and with them slices.Chunk, and that’s the release where I stopped pretending this was still a contest. Batch was one of the few methods I was genuinely proud of:

records.Batch(func(batch, index int, item Record) {
	// process item as part of batch N
}, 100)

Now it’s a language feature wearing a standard library hat:

for chunk := range slices.Chunk(records, 100) {
	// chunk is a []Record of up to 100 items
}

A real for loop. You can break out of it, continue past things and return early. My callback-based version couldn’t do any of that without contorting itself. The trouble is that a wrapper library can only ever be as expressive as the language it wraps and the language just grew.

The stuff that never needed a library.#

An honest confession while we’re standing over the body: a decent chunk of the API never deserved to exist in the first place. Push, Pop, Shift, Unshift. I wrote JavaScript for years before Go was ever a public thing and apparently nobody walks away from that unscathed.

c.Push("e")         // s = append(s, "e")
item, ok := c.Pop() // item = s[len(s)-1]; s = s[:len(s)-1]

The comments on the right are the entire implementation. Idiomatic Go slice handling was already good at this in 2012. Those methods existed because my fingers missed Array.prototype, not because Go was missing anything.

The “survivors”, if you could even call them that.#

Here’s the wrinkle that makes this more interesting than a straight obituary. Map, Filter, Reduce, Some, None; the functional stalwarts still aren’t in the standard library, all these years later. On paper, that’s the corner of the market my little module could have retired to. A niche! Sustained relevance!

Except, no. First, because my Map had a secret shame:

func (c *Collection[T]) Map(f func(int, T) T) (out Collection[T])

See it? T in, T out. Go methods can’t introduce new type parameters, so a method-based Map can never change the element type. Strings to strings, ints to ints. A Map that can only map onto itself is a Map in vibes only; the moment you want lengths of strings you’re back to writing a loop anyway.

And second, more fundamentally: the Go community collectively shrugged and decided the loop was fine. The proposal discussions happened, the experiments ran and the ecosystem largely settled on this:

names := make([]string, 0, len(ducks))
for _, duck := range ducks {
	names = append(names, strings.ToUpper(duck))
}

Four lines. Obvious to anyone who’s read any Go at all, no import, nothing to learn, nothing to maintain and debugger-friendly. Even where go-collection wasn’t superseded, it turned out to be unnecessary, which is somehow a more thorough defeat.

Software is a tool, not a legacy.#

So that’s the technical half. Here’s the part I actually wanted to write about.

We don’t really have a culture of finishing software. A project is either “actively maintained” or it’s “abandoned”, with all the guilt that word drags behind it. Issues accumulate, badges rot and the README slowly becomes a lie because nobody wants to be the person who admits the thing is done, or no longer necessary. I’ve had this module sitting in that limbo for a while now, still getting pulled into new projects out of habit while a strictly better replacement sat in the standard library the whole time.

But software isn’t a legacy; it’s a tool. Tools serve a purpose. This one’s purpose was to teach me generics in their first year of existence and to spare me a few thousand for loops while the language sorted itself out. Purpose served on both counts. And of all the ways for a library to die, being absorbed by the standard library is the best one available. It means the gap you filled was real and now it’s just gone, fixed at the correct layer, for everyone and forever. That’s not a failure state. That’s the mission succeeding so hard the mission ceases to exist.

Keeping it alive from here would mean maintaining a slightly worse, slightly slower, personally-branded copy of slices out of pure sentiment. Nobody needs that, least of all me. I’m busy enough and would much rather move on to newer, more interesting things.

The practical bits.#

So today, the repo gets the full send-off:

• A deprecation notice at the top of the README, pointing anyone who lands there at the slices package and at this post.
• The repository gets archived on GitHub. Read-only, clearly signposted and locked in eternal stasis.

If you’re one of the however-many people with this module in a go.mod somewhere nothing breaks. The Go module proxy caches published versions more or less permanently, so v1.0.11 will keep resolving long after we’re all dust. Archiving just makes the end of our relationship official rather than leaving it implied.

If you’ve got a little module of your own in the same situation that has been superseded, purpose spent, kept alive out of habit, then consider this your permission slip. Write the notice, hit archive and go build that next thing. An honest ending is a kindness to your users and to yourself. It’s OK to let go.

Here is an example of me tearing go-collection out of my very recent Glazier project. This one stung a little at how easily it was replaced.

In closing …#

Thanks, little buddy. You were there before the ecosystem knew what generics were supposed to look like, you appeared in more of my go.mod files than any dependency I didn’t write, and you were, right to the end, exactly as comprehensive as I needed you to be.

go get in peace.

So, over the course of the past few days Glazier learned a new trick. Profiles can now declare the variables they accept, give them primitive types, mark them as required and read them back through a proper var. namespace.

Out with the old.#

Technically speaking, Glazier has had variable support since day one. You could pass --var region=watson and reference ${region} anywhere in your profile and that was that. Anything you passed got dumped into a flat namespace and any name you referenced, but forgot to set, quietly resolved to an empty string.

That’s fine right up until you fat-finger ${reigon} and spend ten minutes wondering why your session name has a hole in it. The whole reason I built this thing was to get Terraform’s “here is exactly what you did wrong and where” experience.

Letting variables fail silently just felt a bit like an own-goal.

Profiles can now declare what they accept.#

Because this whole thing is kind of a love letter to Terraform’s parser, the idea behind variable definitions is functionally the same. You declare a variable block, it sits at the top level next to your session and that’s the input you’re allowed to pass:

variable "district" {
  description = "the district the gig is themed after"
  type        = string
  default     = "watson"
}

variable "fixer" {
  type = string
}

session {
  name = "gig-${var.district}"

  window {
    name = "${var.fixer}-ops"

    pane {
      commands = ["echo ${var.fixer} has the next job"]
    }
  }
}

First, you reach a variable through var. and only var. now, so it reads exactly like it would in a .tf file. Second, district has a default and fixer doesn’t, which turns out to matter quite a lot in a second.

$ glaze up --var fixer=wakako # district falls back to "watson"
$ glaze up --var district=arasaka --var fixer=wakako

So, here you are using the same templated profile to define two seperate sessions decided entirely by flags.

Pass it something it doesn’t know and it says so.#

If you pass a --var for a variable the profile never declared, you no longer get a silent shrug. You get a proper error:

Error: Undefined variable

A value for "ghost" was passed with --var, but the profile declares no
variable "ghost". Add a variable "ghost" {} block, or remove the flag.

I went back and forth on this one. Being strict about undeclared flags is the sort of thing that feels pedantic until the day it catches a typo you’d have otherwise chased for half an hour. In this case strict won.

A --var you can’t explain is almost always a mistake, so Glazier now treats it like one.

No default means you have to mean it.#

A variable without a default is required. Leave it unset and up refuses to do anything until you supply it:

Error: Missing required variable

  on .glaze line 6, in variable "fixer":
   6: variable "fixer" {

The variable "fixer" has no default, so a value must be supplied with
--var fixer=<value>.

This is the bit that makes a profile a genuine contract rather than a suggestion. If a layout is useless without a fixer, declare fixer with no default and the tool will make absolutely sure you provided one before it touches tmux.

Proper type-checking.#

Every variable declares a type. Use one of the bare keywords string, number or bool. The value you hand over on the command line is coerced into that type and rejected if it doesn’t fit:

variable "base_index" {
  type    = number
  default = 1
}

$ glaze up --var base_index=two

Error: Invalid variable value

  on .glaze line 1, in variable "base_index":
   1: variable "base_index" {

The value passed for variable "base_index" with --var cannot be used as
number: a number is required.

two is not a number, so you find out before anything launches rather than after tmux has already swallowed a garbage option and started behaving oddly. Booleans get the same treatment: true and false are fine, anything else is shown the door. Unfortunately, I decided not to go with truthy or falsey value coercion.

I kept it to the three primitives on purpose. The moment you add list(string) and friends you’re also signing up for coercing comma-soup off the command line into nested types. That’s a much bigger can of worms than a tmux helper needs to open today.

Though, obviously, if you disagree you’re more than welcome to leave a comment below!

A namespace for everything.#

I’ll be honest about the consequence here. This is a breaking change and pretending otherwise would be rude. The old flat ${region} style is gone. If a value comes from a declared variable, you read it as var.region.

Which raised a genuinely interesting design question I sat with for a while. If variables are only ever used inside a session, why not declare them inside the session block too? It feels more intuitive at first though, but it’s also wrong.

However you nest the declaration, the reference is still flat and global; you write var.fixer, never session.var.fixer. Declaring something file-global but reading it block-scoped is incoherent and a variable is really an input to the invocation, sitting conceptually above the session and not a property of it. So they live at the top level, exactly where Terraform puts them. I borrowed both the syntax and the reasoning.

Where did the environment variables go?#

They also got their own namespace. Previously GLAZE_ENV_token showed up as a bare ${token}, sharing the same flat namespace as everything else. Now it lives under an env. namespace, which makes the three sources nicely symmetric:

• var.* for variables you declared and passed with --var
• env.* for GLAZE_ENV_* environment variables
• path.pwd & path.base the unchanged built-ins

session {
  name = "host-${env.box}"

  window {
    pane {}
  }
}

$ GLAZE_ENV_box=nightcity glaze up

session = host-nightcity

There’s no declaration needed for env.*; the environment is the environment. Only the things you pass with --var have to be declared, because those are the inputs you are claiming the profile accepts.

Tearing down a session.#

If a required variable now blocks up, doesn’t that wreck glaze down? I recently taught the down command to evaluate only the session name so it doesn’t need every variable buried deep in the profile just to kill a session. Surely required variables undo that?

They don’t and this was the fiddly bit to get right. down resolves variables leniently. A variable used solely in some pane command, far away from the session name, is neither required nor evaluated when you’re tearing things down:

variable "beep" {
  type = string
}

session {
  name = "daemon-run"

  window {
    pane {
      commands = ["echo ${var.beep}"]
    }
  }
}

$ glaze down
INF nothing to do; session is not running session=daemon-run

If beep isn’t provided, the command just accepts it and moves on, because down never needed it. up enforces the full contract; down only asks for what the name actually depends on. Obviously, the exception here is if a variable is used to construct the actual session name. Other than that, this is an idempotent no-op.

Validation has been updated too.#

glaze format --validate decodes a profile and reports diagnostics without ever touching tmux and it now enforces the entire variable contract. Miss a required variable and validation fails right there:

$ glaze format --validate
Error: Missing required variable
  ...

$ glaze format --validate --var region=us-east-1
# clean. nothing to report.

So, you can lint a parameterised profile in CI, or just before committing it and know it holds together before you ever try to bring it up.

This literally broke all my current profiles.#

And I regret nothing. The flat-namespace migration touched pretty much everything; sample profiles, the docs, a pile of tests and all the profiles I actually use day to day. Normally this is the part of a post where I’d sketch out a careful migration path and apologise profusely.

But, the entire userbase of this tool is almost, as far as I can tell, me. So the migration path is “I’ll fix all my profiles tomorrow morning over coffee.”

To migrate is easy enough, just define your variables and prefix all references with var.. This is still currently in beta after all.

In closing…#

Under the hood this turned into a more interesting refactor than I expected. hcldec wants to decode a whole file body against one spec and it flatly refuses to tolerate a variable block sitting next to the session it doesn’t know about. The trick was to stop handing it the whole file, pull the session block out myself and decode just its body, which leaves the variable blocks to be gathered and resolved in their own quiet little pass beforehand. There’s a tidy PartialContent implementation in there that was heaps of fun to figure out.

None of which a tmux wrapper strictly needed, of course. But “strictly needed” stopped being the bar around the time I added a fuzzer. The point was to feel out how Terraform turns a typo into a friendly, located error and now Glazier does a respectable impression of it for variables too.

I’m still ironing out all the kinks and ensuring I still have an 80% baseline in testing and code coverage, but I’m planning to release this and a few bug fixes and dependency bumps this weekend. Tomorrow-me gets to read this back with fresh eyes and decide how much of it past-me oversold. Very nice.

Until I merge it in, you can play with the latest release here.

And now I’m thinking about adding *.tfvars-like functionality. Surely, I won’t fall for this again?

So I built Glazier; a small command-line tool that lets me describe a tmux workspace once and recreate it on demand. Type glaze up and the sessions, windows and panes I described spring back into existence exactly how I left them.

This has been a slow-burning labour of love for the better part of two years and it’s finally in a state where I feel comfortable letting other people look at it. So let’s talk about why it exists, what else is out there and how this one is different.

It’s just a config file, right?#

That was the idea, at least. I just wanted to stop rebuilding the same layouts over and over. But, as is tradition, I didn’t want to make it too easy for myself.

There was a second, more selfish motivation. As a platform engineer, there isn’t a day that goes by where I don’t work with Terraform. I’ve always been quietly fascinated by how it parses and validates its configuration. That whole experience of getting a precise, friendly error pointing at the exact line you fat-fingered, rather than a stack trace and a 🖕. I wanted to understand how that machinery actually worked.

So, I’m a heavy tmux user and I wanted to learn HCL parsing from the inside. These two things lined up a little too perfectly. So Glazier’s profiles aren’t YAML; they’re HCL. The same configuration language Terraform uses and parsed with the same underlying library.

Here’s a basic profile:

session {
  name = "daemon-run"

  window {
    name   = "ice-breaker"
    layout = "main-vertical"

    pane {
      commands = ["nvim ./payloads"]
    }

    pane {
      commands = ["watch -n1 netwatch --target arasaka-mainframe"]
    }
  }
}

Drop that in a file called .glaze, run glaze up next to it and you’re jacked in.

I’m not the first to do this; not even the 3rd… or the 4th.#

This is a thoroughly-solved problem and I’d be doing you a disservice if I pretended otherwise. There’s a whole shelf of mature, battle-tested tools that do effectively the same thing:

• tmuxinator is the one most are familiar with. Written in Ruby with YAML profiles. Probably what most people reach for.
• teamocil is also written Ruby; also uses YAML.
• smug is written in Go and uses YAML and is the closest in spirit to Glazier if we’re being honest.
• tmuxp is written in good’ole reliable Python and it’ll happily eat YAML or JSON.

If you already use and trust one of these, I’ll be straight with you: there isn’t a compelling reason to switch. Keep using what works. I’m not here to convince anyone to rip out a tool they’re happy with.

But if you’re still reading, here’s what I like about mine.

So what’s actually different?#

The profile validates itself!#

This is the part I set out to build, so it’s the part I’m fondest of. Because Glazier is built on HCL, it inherits Terraform-style diagnostics for free. Mistype a layout, point a starting directory at somewhere that doesn’t exist or forget a required block and you don’t get a vague “something went wrong fuck you”. You get told exactly what and where you messed up:

Error: Invalid layout specified

  on .glaze line 4, in session.window:
   4:     layout = "main-plumbus"

The layout value of "main-plumbus" is not a supported preset
(even-horizontal, even-vertical, main-horizontal, main-vertical,
tiled) nor a valid tmux layout string.

There’s a glaze format command that rewrites your profile into a canonical style and, with --validate, reports any of these diagnostics without touching tmux at all. Both of these scratch exactly the itch that started the whole project.

Variables, templates and string functions! Oh, my!#

A static layout is useful. A templated one is better. Profiles can reference variables and you can feed those in from --var flags or GLAZE_ENV_* environment variables:

session {
  name               = "ops-${region}"
  starting_directory = path.pwd

  window {
    name = upper(region)

    pane {
      commands = ["k9s --context ${region}"]
    }
  }
}

$ glaze up --var region=ap-southeast-2

Look familiar? If you work with Terraform it does!

There’s a handful of built-in string functions too. upper, lower, replace, trimspace, join and friends which act as thin wrappers over the same go-cty standard library Terraform uses. Plus, a couple of freebies like path.pwd and path.base so a profile can adapt to wherever it’s run from.

It doesn’t lie to you about timing.#

This is the bit of engineering I’m quietly proudest of, even though nobody will ever see it. When you fire a sequence of commands into a tmux pane, the naive approach is to blast them in with a sleep between each one and hope the previous command finished. That’s flaky and it’s how a few other tools handle it.

Glazier instead serialises commands through tmux’s own wait-for signalling, so each command genuinely waits for the previous one to finish before the next is sent. There are no fixed sleeps and no races. The one exception is the final command in a list, which is sent fire-and-forget. If your last command is a long-running dev server or tail -f, waiting on it would hang up forever.

I learned that last part the hard way.

It can mostly save a session!#

Run glaze save inside a live session and it’ll capture the structure back out into a profile: windows, panes, names, layouts, focus and starting directories. The “mostly” is doing some load-bearing work in that sentence and it’s a deliberate choice, not a missing feature.

save will not export your pane commands, environment variables, hooks or tmux options. Why? Because each of those is a footgun:

• Commands would re-execute on the next up. A forgotten rm -rf captured from some pane could ruin your whole day on replay.
• Environment variables can only be read as the entire session environment. This means inherited secrets, tokens and keys getting written into a file you might commit. That’s a big fat no from me, dawg.
• Options read back as effective state, hopelessly tangling up with your tmux.conf and manual tweaks.

So, a saved profile is a scaffold. It gets the geometry right and you add back the commands and config you actually want by hand.

A real profile.#

Enough talk. Here’s the profile I actually use when working this website:

session {
  name = path.base

  envs = {
    HUGO_GITHUB_TOKEN        = "${github}"
    HUGO_ACTIVITY_GRAPH_DEMO = "${demo}"
  }

  window {
    name  = "editor"

    pane {
      commands = ["nvim"]
    }
  }

  window {
    name  = "terminal"
    focus = true

    pane {}
  }

  window {
    name = "server"

    pane {
      commands = ["hugo server --disableFastRender"]
    }
  }

  window {
    name = "git"

    pane {
      commands = ["lazygit"]
    }
  }
}

Running glaze up --var github=*** --var demo=true gives me the following windows:

• My editor of choice; NeoVim.
• A dedicated terminal session.
• The Hugo server along with some HUGO_ specific environment variables; values sourced from the CLI.
• Finally, lazygit to manage and commit my changes.

Further, the --var arguments aren’t really necessary as you could just export GLAZE_var_name as well and Glazier will pick it up automatically.

Anyways, because the session is just a named thing, the rest of the lifecycle is tidy too. List what’s running with glaze ls:

$ glaze ls
NAME      WINDOWS  PATH
glazier*  2        /home/wilhelm/Development/wilhelm.codes
scratch   1        /tmp

The asterisk marks the session I’m currently attached to. When I’m done, I tear it down by profile:

$ glaze down

down is idempotent and that’s on purpose. Bringing down a session that isn’t running is a no-op, not an error, so it’s safe to drop in scripts without defensive checks.

Some over-engineered bits …#

To be frank a tool that shells out to tmux did not strictly need a fuzzed HCL parser, build provenance attestations on its release binaries or a CI pipeline that runs the test suite against multiple Go versions and operating systems.

But, that was never really the point. The point was learning how Terraform’s parser ticks, working out how to drive tmux reliably without sleeps and over-engineering the ever-loving-shit out of an already-solved problem because it was fun. Every constraint I imposed upon myself taught me something new. This is ultimately the only metric I actually care about for a hobby project like this.

Where to get it?#

It’s up on GitHub with a shiny MIT license. If you’ve got Go installed:

$ go install github.com/wilhelm-murdoch/glazier/cmd/glaze@latest

Or, grab a prebuilt binary from the releases page. I currently build for Linux and macOS on both amd64 and arm64. Each one ships with a checksum and a signed provenance attestation, because of course it does.

In closing …#

I would confidently say Glazier has moved on from “experimental” to “stable”. It works and I use it every single day. But, there are rough edges and there may be any number of unencountered failure modes. The down and ls commands only landed recently and I’m not sure if the latter should remain. I’ve also got a running list of ideas I haven’t talked myself out of yet. Like, something similar to Terraform’s *.tfvars files or defining typed variables.

If you’re already happy with Tmuxinator or Smug, then stick with them. But if the idea of a declarative, self-validating, slightly-too-clever tmux profile appeals to you, or you just want to read some Go that wraps tmux in ways it was probably never meant to be wrapped, I’d love for you to take it for a spin.

I sincerely hope you find Glazier as useful as I had fun building it.

So let me finally show you my bits.

What even is a bit?#

A bit is the smallest unit of “I made a thing” I’m willing to commit to. It could be a quote that stuck with me, a link worth keeping, the odd YouTube video, or a one-line thought too small to earn its own long-form entry. Each one is a little markdown file in /bits and the only thing it really has to declare is what kind of bit it is:

---
type: quote
date: 2026-06-17
source: "Edsger Dijkstra"
---
"Simplicity is a great virtue but it requires hard work to achieve it."

type is the whole trick that everything else hangs off.

One shape per thought.#

The thing I didn’t want was for a pithy quote to render like a bare link or to render like a video. They’re different shapes of thought, so they ought to look different.

I’d already learned this lesson building the changelog, which leans on one tiny partial per event type. So I stole from myself. There’s a single lookup table mapping each type to an icon, an accent colour and a label:

{{ $meta := dict
  "quote" (dict "icon" "quote-right"    "colour" "rose"    "label" "quote")
  "link"  (dict "icon" "arrow-up-right" "colour" "blue"    "label" "link")
  "video" (dict "icon" "youtube"        "colour" "red"     "label" "video")
  "blurb" (dict "icon" "pen-nib"        "colour" "emerald" "label" "blurb")
}}

It then matches a micro-partial per type that decides how the content actually renders. Adding a brand new kind of bit is now “add one row, add one tiny template”, which is about as many steps as I’m willing to tolerate.

Hugo, why are you like this?#

My bits started life with two perfectly reasonable front-matter fields: type and url. Hugo took one look and quietly robbed me of both.

It turns out url is a reserved key which Hugo uses to treat as the page’s permalink. So, the moment I put a https://... in there, the build fell over with a stern little message about unsupported protocols. type doesn’t even have the decency to error. It silently moves out of .Params.type and into .Type, which also hijacks the layout lookup. So my .Params.type was resolving to nothing and every single bit was quietly rendering as the fallback.

Turns out hte fix for this was simply to rename url to link and read .Type instead of .Params.type. Half an hour of my life dedicated to two words I didn’t know were already spoken for.

Coding is my passion.

Bits flapping in the wind.#

Rather than dumping bits into the same fold-out list as the GitHub noise, I pulled them out as their own first-class timeline rows. The lower-signal changelog chatter stays tucked behind the “N changelog events in between” disclosure. So, the home page now reads in three tiers:

• the loud headline articles
• the medium-volume bits
• the quiet changelog hum

The same interstitial machinery I built last time, but bits just get to stand a little taller than a commit.

The tag that went nowhere.#

Bits are deliberately render: never in Hugo. They live inline on the bits page and never get their own URL. Except “no page” also quietly means “no place in the taxonomy”, which means a tag only ever used by a bit has no /tags/... page to point at. If I link it anyway I’ve shipped a 404.

So, the tags only become links if there’s actually somewhere to go:

{{ with site.GetPage (printf "/tags/%s" (urlize .)) }}
  <a href="{{ .RelPermalink }}">#{{ .Data.Term }}</a>
{{ else }}
  <span>#{{ . }}</span>
{{ end }}

A tag with a real page becomes a link and a bit-only tag stays as plain text. No broken links and the nice part is it heals itself the moment a proper article picks up the same tag.

In closing …#

The front page has quietly turned into a proper little stream. Long-form when I’ve actually got something to say, bits when I don’t and a year of squircles up top keeping a tally of it all.

Which is the entire point. The less effort it takes to post a half-formed thought, the more likely I am to actually post it. And the more I post, the more those gaps fill in.

And, as always, you can check everything out for yourself in the repo.

I want to fill those gaps in and not with more full-fat rows, but with a small line between each pair of articles. Something like “1 bit and 41 changelog events in between”; a kind of interstitial event timeline for all the work that never quite became a full blog post.

Why can’t I hold all these events?#

The trick to merging things that don’t look alike… You’re never going to believe this… is to make them look alike. I already pull my GitHub activity for the changelog, or, at least, the last 100 or so events. So, I reused that, threw the bits in alongside it, and normalised the whole lot into one boring, uniform shape. This data structure doesn’t hold all the data for each event, but just enough to cover the highlights.

{{ $events = $events | append (dict
  "kind"  "commit"
  "date"  (time.AsTime .commit.author.date)
  "title" (index (split .commit.message "\n") 0)
  "url"   .html_url
  "icon"  "code-commit"
  "colour" "green"
  "data"  .)
}}

Every piece of content on this site has at the very last these attributes. So created a unifying model is pretty straight-forward. A kind, a date, a title, a link, and enough leftover metadata to do something creative with later if I feel like it. I made a point of keeping the original object tucked away in data too; a gift to future Wilhelm.

Minding the gaps.#

With one big sorted pile of events, the rest is just bookkeeping. Walk the articles newest to oldest, and for each one work out the window between it and the article above it. Then, scoop up every event that falls within the relevant dates:

{{ $upper := $now }}
{{ if gt $i 0 }}{{ $upper = (index $articles (sub $i 1)).Date }}{{ end }}
{{ range $e := $events }}
  {{ if and ($e.date.After $article.Date) (not ($e.date.After $upper)) }}
    {{ $group = $group | append $e }}
  {{ end }}
{{ end }}

The newest article’s “window” runs all the way up to now, so whatever I’ve been doing since the last post shows up at the very top. If there’s an empty gap the event list doesn’t render.

Listing the interstitial events.#

A summary is nice, but I wanted to be able to actually see the events without leaving the page. Normally that’s where a pile of JS shows up. But, just as with the activity graph, we’re going to rely on pure HTML and CSS. The <details> element does the entire job for free:

<details class="group">
  <summary>... 41 changelog events in between ...</summary>
  <ul>
    <!-- one little row per event, complete with icon and link -->
  </ul>
</details>

Click the summary, the gap unfolds into a tidy little list of every commit, PR and bit. Each linked off to wherever it lives. The default disclosure triangle gets binned and replaced with a chevron that flips on open, courtesy of Tailwind’s group-open: variant. Still no JS and I’ll remain quietly smug about that.

Saving myself a small headache.#

Finally, there’s the the responsive question. This site’s overall design isn’t exactly “mobile first” and viewing it on a small screen strips away a lot of detail already. All these thin dividers and fold-out lists look great on a wide screen and turn into a cramped mess on a phone.

I thought about it for a while and weighed up some clever reflowing. In the end I did the only sensible thing and hid the whole timeline below the sm breakpoint. On a phone you get the clean list of articles, but on a desktop you get the full story between them.

That being said, I do need to return and focus on making the mobile experience a bit more palatable.

In closing …#

What I like about this is that it turns my worst blogging habit - vanishing for months and then resurfacing in a manic flurry - into something the site can actually narrate. The big rows are the headlines while the quiet lines between them are everything else.

It’s also wired up so I can grow it later without unpicking anything. Right now it’s counts and lists, but tomorrow it could filters, more details, or do something I haven’t thought of yet. All off the same pile of events.

For now, though, the gaps have something interesting in them. Which is a much nicer thing to scroll past than a year of silence.

I wanted something that summed up “Has Wilhelm actually been doing anything lately?” at a glance, without the density of 365 tiny day cells. Fifty-two squircles felt about right. Coarse enough to read across the room, fine enough to still give a picture.

What counts as a “week’s worth of activity”?#

The short answer is everything. The changelog already pulls my GitHub activity at build time, so I reuse that exact same data. Then, I throw in the things GitHub doesn’t know about; every type of blog post on this site.

Because the changelog fetching already lives in a tidy little partial, sourcing the everything is just a matter of asking for each one and collecting all the publish dates:

{{ $dates := slice }}
{{ range partial "changelog/fetch.html" (dict "url" $commitsUrl "fixture" $fixture) }}
  {{ $dates = $dates | append (time.AsTime .commit.author.date) }}
{{ end }}
{{ range where site.RegularPages "Section" "blog" }}
  {{ $dates = $dates | append .Date }}
{{ end }}

Nothing crazy going on here. I’m just creating a big list of timestamps from wherever I happen to leave a trail.

Sorting a pile of dates into weekly buckets.#

Each of these dates now need to land in one of fifty-two buckets. Working out which week a given date belongs to is just some boring epoch arithmetic; how many whole weeks ago was it?

{{ $ago := int (div (sub now.Unix $d.Unix) 604800) }}
{{ if and (ge $ago 0) (lt $ago 52) }}
  {{ $counts.Add (printf "%d" (sub 51 $ago)) 1 }}
{{ end }}

That 604800 is the number of seconds in a week. And yes, I did have to look that up. Anything older than fifty-two weeks just falls off the back and is quietly ignored.

Painting the squircles.#

My favourite part of this is there’s no JS involved. The whole thing is a CSS grid of twenty-six columns, and because each squircle is aspect-square, the rows just work and the squircles stretch to fill whatever container I drop the partial into:

<div class="grid grid-cols-26 gap-1.5">
  <!-- 52 of these green little dudes -->
  <div class="aspect-square rounded-full bg-emerald-400"></div>
</div>

Working out the shade was the fiddly bit. My first attempt simply scaled each week against the busiest one, which sounds sensible right up until you remember my data is basically one enormous week and a whole lot of flat nothing. That single monster week hogged the dark end and squashed everything else into the same pale green. So I did what GitHub does and reached for quartiles instead. You rank the weeks that actually saw some activity, chop them into four groups, and let a week’s colour come from where it lands in the pack rather than from some absolute number. Empty weeks stay a faint emerald-100; the rest climb through four steps of green up to emerald-600. The part I like is that it’s relative to me; a busy week is only busy compared to my other weeks.

The little tooltip that pops up when you hover over a squircle is also pure CSS. A group on the wrapper, a group-hover:opacity-100 on the popup, a transition is all I needed. Each squircle now gives a little scale on hover too, just because it’s nice.

The graph’s painful honesty.#

Now on to the more embarrassing part. When I first rendered it with real data, I got one lonely green squircle and fifty-one empty ones. Surely, you’ve noticed it on the front page.

For the curious, this is what it would look like if I didn’t have commitment issues.

At the time I assumed I’d done something wrong. But, to my great shame, I hadn’t. Turns out that when you vanish from your own website for close to 18 months and then cram an entire renovation into a single week, the graph renders exactly that. A long, flat, pale stretch of road ending with one pathetic little green emerald.

There’s an extra little indignity baked into the quartiles, too. They need a spread to rank against, and with exactly one active week there’s nothing to compare it to. So my massive renovation-cramming week doesn’t even get to be properly dark green. It turns up as a polite, middling shade.

I effectively built a little a tool whose entire job is to hold up a mirror to my own lack of consistency and commitment. Very cool! 😬👌

Drop it in anywhere.#

This whole thing is a single self-contained partial. It was waaaay easier to build out than I had originally thought. And, thanks to Tailwind I didn’t even have to fall back on any JS! I count that as a bonus.

For the moment, it’ll live on the home page, but I can now just place this anywhere in my Hugo site and it’ll work:

{{ partial "activity-graph.html" . }}

I might even build it out a bit more to support different colour schemes or specificy types of targeted site content. So, the more I write, the more those squircles fill in.

Consider yourself warned, me.

Confession Time#

While poking around the build, I discovered something a little embarrassing. My Tailwind setup - the source, the config, and the entire node_modules directory - was living inside Hugo’s static/ folder.

If you know Hugo, you already know where this is going. Everything in static/ gets copied, verbatim, into the final site. Which means I had been cheerfully publishing my whole build toolchain - megabytes of it - to the live site on every single deploy. So, yeah. Production was shipping node_modules. Coding is my passion.

Nobody noticed, nothing broke, and the world kept turning. But it’s the kind of thing that, once you see it, you can’t un-see. To be fair to myself, when I originally put this Hugo site together, I only learned enough to get something shipped.

Letting Hugo do the heavy lifting.#

The reason that mess existed in the first place was that I’d wired up Tailwind as a separate, manual build step that spat out a compiled stylesheet for Hugo to pick up. It worked, but it was a second moving part I had to remember existed.

The good news is that recent versions of Hugo can drive Tailwind itself, natively, as part of the normal asset pipeline. Combined with Tailwind v4 - which finally ditches the JavaScript config file in favour of configuring everything in CSS - I got to delete a lot of stuff:

$ git diff --shortstat main...modernize
64 files changed, 1872 insertions(+), 40197 deletions(-)

The whole stylesheet now starts its life as a single entry point:

@import "tailwindcss";
@plugin "@tailwindcss/typography";
@source "hugo_stats.json";

That hugo_stats.json bit is the clever part. Hugo writes out a list of every utility class it actually emits, and Tailwind reads that to decide what to generate. No more pointing Tailwind at my templates and hoping it guesses right.

Then a small partial hands it all off to Hugo to compile, minify and fingerprint:

{{- with (templates.Defer (dict "key" "css")) }}
  {{- with resources.Get "css/main.css" }}
    {{- $opts := dict "minify" (not hugo.IsDevelopment) }}
    {{- with . | css.TailwindCSS $opts }}
      {{- /* ...do very cool things... */ -}}
    {{- end }}
  {{- end }}
{{- end }}

The templates.Defer wrapper is there because the CSS can’t compiled ( transpiled? ) until Hugo has finished rendering every page and knows the full list of classes. So, in a very real way, Hugo solves an annoying 🐔 and 🥚 problem.

This means no more standalone Tailwind config, no committed stylesheet, no node_modules in static/, and no build toolchain leaking onto the live site. Very cool!

So. Many. Deprecations.#

Of course, nothing that’s been left alone for a year comes back to life cleanly. Bumping Hugo to the latest release lit up the console like a Christmas tree.

A few of my templates were leaning on things that have since been politely shown the door:

• resources.GetRemote ... .Err for the changelog page - that pattern was removed in favour of a shiny new try keyword.
• .Language.LanguageCode and .Language.LanguageDirection, both deprecated in favour of .Locale and .Direction.
• The _build and cascade._target front matter keys, now just build and cascade.target.

None of it was hard to fix, but it’s a good reminder that “it still builds” and “it builds without complaints” are two very different bars.

A Footgun!#

Here’s a fun one. The changelog page pulls in a Github event fixture file during local development by fetching it over http://localhost:1313. Effectively, from the very dev server that’s trying to build the page.

Those of you who are familiar with such things can probably see the problem. Hugo builds the site before it starts listening on that port, so the build sits there waiting for a server that doesn’t exist yet. A deadlock of my own making. The obvious fix was to just read the file off disk instead of asking the network nicely.

Some honourable mentions.#

A grab-bag of smaller wins while I had the hood up:

• Fonts are now served as woff2 instead of raw ttf, with font-display: swap so text shows up immediately instead of hanging around invisible. This alone shaved the font payload down by about 60%.
• I also deleted a few MB of fluff that wasn’t being loaded by anything.
• Prettier got a nice version bump and I taught it to sort my Tailwind classes, so I can stop pretending I do that consistently by hand.

Was the juice worth the squeeze?#

Aside from a few cosmetic updates here and there, the site should look pretty much the same as it did before. Which is, weirdly, the whole point; all of this work was about the parts you can’t see. I got a leaner build, faster page loads, and a project I can come back to in another year without wincing; famous last words, etc…

For now, the house is clean. Very nice.

If you use Github, you know it quietly records nearly everything you do as a stream of events. Better still, for a public repository, that stream is available over a public, unauthenticated API endpoint through a simple GET request.

So the plan more or less writes itself. We fetch the stream at build time, group the events by day, and let Hugo render them. Hugo even has a tidy little function for pulling in remote resources that works like so:

{{ $url := "https://api.github.com/repos/wilhelm-murdoch/wilhelm.codes/events" }}
{{ with try (resources.GetRemote $url) }}
  {{ $events := .Value | transform.Unmarshal }}
  {{/* ...range over them and render... */}}
{{ end }}

Because this all happens at build time, the visitor never waits on GitHub. By the time the page reaches a browser it’s just static HTML like everything else. The changelog is always current as of the last deploy, and I never have to think about it.

That’s the part that worked. Now for the parts that didn’t.

… Then, production happened.#

I’ve been more or less absent from this site for close to a year, but this past week I’ve decided to breathe a bit more life into it. I made a few changes to modernise the stack, pushed my changes up and waited on Cloudflare to do its thing and…

ERROR error building site: ... error calling GetRemote:
failed to fetch remote resource from 'https://api.github.com/...': Forbidden

I was greeted with a 403. Except… I could paste that exact URL into my browser and get a perfectly happy wall of JSON back. So what gives?

Rate limiting, that’s what. GitHub’s unauthenticated API is capped at 60 requests per hour, per IP address. My build doesn’t run on my IP. It runs on a shared build machine alongside who-knows-how-many other people’s deploys, all of them hammering GitHub from the same handful of addresses. By the time my build rolled around, that bucket was bone dry.

Honestly, a 429 instead here would have saved me a bit of investigating, but I digress.

The solution was to created a properly scoped Github PAT. Using an authenticated request gets 5000 requests per hour, so I went about implementing support and handed it to the build as an environment variable, and taught the template to send it along:

{{ $opts := dict }}
{{ with os.Getenv "HUGO_GITHUB_TOKEN" }}
  {{ $opts = dict "headers" (dict "Authorization" (printf "Bearer %s" .)) }}
{{ end }}
{{ $remote := try (resources.GetRemote $url $opts) }}

It’s worth noting that Hugo won’t read just any environment variable. Its security policy only lets os.Getenv see variables prefixed with HUGO_. Name your token GITHUB_TOKEN and you’ll get a confusing fistful of nothing; name it HUGO_GITHUB_TOKEN and it works. Ask me how I know.

Hark! Another Footgun!#

With the token in place, the fetch succeeded and the build promptly fell over somewhere new:

error calling len: reflect: call of reflect.Value.Type on zero Value

This never showed up locally, which tells me I should do myself a favour and do a quick local production deployment as a preflight before I push to Github and trigger an automated build. Originally, in development I rendered the changelog from a single large fixture file stored locally on disk. This was before I implemented the PAT so I wouldn’t rate limit myself locally when testing. The live stream, however, contains event shapes my fixture simply didn’t. One of them was a push event carrying no commits at all, and my template did this without a second thought:

{{ if eq (len .payload.commits) 1 }}

Call len on something that exists and isn’t there and Go has a small panic about it. The fix is boring; stop assuming the field is there. Hugo’s with only enters the block when its argument is actually… something:

{{ with .payload.commits }}
  {{ if eq (len .) 1 }}
    {{/* the one-commit case */}}
  {{ else }}
    {{/* the many-commits case */}}
  {{ end }}
{{ end }}

Since I’ve implemented PAT support, I’m not so concerned about being rate-limited during local development, though I now use the fixtures as a fallback if any request fails. This allows me to keep working locally without disruption.

Don’t let someone else’s server break your build.#

The real personal lesson is the moment your build depends on a third party at build time, you’ve effectively ceded control of your deployment to them. GitHub rate-limits you, or has a wobble, or changes a payload shape, and suddenly your perfectly good site won’t deploy and you’ll have a hard time.

So the changelog no longer treats GitHub as load-bearing. If the fetch fails for any reason it shrugs, logs a warning, and falls back to that saved fixture instead of taking the whole deploy down with it:

{{ $remote := try (resources.GetRemote $url $opts) }}
{{ with $remote.Err }}
  {{ warnf "changelog: GitHub fetch failed (%s); using the fixture" . }}
  {{ $response = os.ReadFile "static/github.json" | transform.Unmarshal }}
{{ else with $remote.Value }}
  {{ $response = . | transform.Unmarshal }}
{{ end }}

The try keyword is the hero here as it catches the error that GetRemote would otherwise throw and hands it back to me as a value I can actually do something with, rather than a smoking crater where my build used to be. Worst case, the page shows slightly stale history. That’s a trade I’ll take every single time over a red deploy or disruption to my local flow.

In conclusion…#

Ironically, this is something I’ve dealt with quite frequently at work. Github & AWS API rate limits ( yes, we frequently got rate limited by the VPC API of all things ), Yarn will throw a 5xx and even Sentry will chimp out during source map uploads. All of these things can disrupt deployments.

The point is just assume these things will happen and then build defensively around them. I, ehhhh, just need to apply this wisdom to my personal stuff. 😅

Anyway, the changelog still builds itself. It just doesn’t get to take the rest of the site down with it anymore.

In this case, what I really needed was a simple way to assign an ordinal to an arbitrary number. For instance, if I have a value of 2, I might want to tack on a nd as a suffix, eg; 1st, 540th or 9001st and so on.

Specifically, I’d like to use this with dates, but from what I can tell, Hugo doesn’t support this out-of-the-box. Luckily, the framework gives you a few options to extend its functionality.

Shortcodes#

With shortcodes you can create snippets that act as functions which can be used to dynamically inject HTML – among other things – directly into your rendered markdown. You can even pass both named and positional arguments through the shortcode to modify their behaviour as needed.

For instance, I have this custom shortcode used for displaying styled block quotes like:

I also have this one that let’s me print out some fancy callouts:

Hugo ships with a default set of shortcodes covering a variety of additional kinds of embeddings.

Unfortunately, for my purposes, I’m not planning on using dynamic numeric ordinals in my markdown files. I need this to work with templates and for that, we use…

Partials#

Unlike shortcodes, partials are small re-usable HTML components that are typically used to keep code duplication down. They are effectively context-aware templates that can accept arbitrary data which can be used in generating desired output.

Here is a small example of how I use partials for this blog. It’s a small data card component you might find scattered throughout the site. Partials let you quickly change a UI component in one place while having it propagate everywhere else.

For the purpose of this article, they can also be used to create custom template “functions” like this which solves my very specific problem:

{{- if and ( eq ( mod . 10 ) 1 ) ( ne ( mod . 100 ) 11 ) -}}
    st
{{ else if and ( eq ( mod . 10 ) 2 ) ( ne ( mod . 100 ) 12 ) -}}
    nd
{{ else if and ( eq ( mod . 10 ) 3 ) ( ne ( mod . 100 ) 13 ) -}}
    rd
{{ else -}}
    th
{{ end -}}

This may look a bit unreadable to people who aren’t super-familiar with Hugo’s template syntax, but it effectively resolves to:

const number = 10
let ordinal = "th"
if (number % 10 == 1 && number % 100 != 11) {
	ordinal = "st"
} else if (number % 10 == 2 && number % 100 != 12) {
	ordinal = "nd"
} else if (number % 10 == 3 && number % 100 != 13) {
	ordinal = "rd"
}

console.log(number + ordinal)

// prints 10th

Anyways, I have this saved as partials/functions/ordinal.html and can reference this in any of my templates like so:

{{ partial "functions/ordinal.html" $number }}

Where $number is any arbitrary number I’d like an ordinal suffix for. Take the following example template which generates a random range of numbers and prints them out using my ordinal partial:

{{ range seq 10 }}
  {{.}}{{ partial "functions/ordinal.html" . }} 
{{ end }}

Which generates:

1st 2nd 3rd 4th 5th 6th 7th 8th 9th 10th

Ground-breaking work! I can finally use ordinals in dates. Not exactly something I expected to write an article about, but here we are. 🤷

First, a Small Rant#

Before you call me a Luddite, let’s be clear here, I don’t have an issue with the technology itself. I’m an engineer. I think it all has its uses, but force-feeding it into almost every aspect of our lives with no regard to any social and environmental impacts with frequently no chance of being able to easily opt-out does not sit right with me one bit.

We’ve seen this happen over the last decade with touchscreens, IoT, blockchain, NFTs, Web3 the list goes on. All promoted by the endless parade of interchangeable, nameless faceless talentless hacks and disingenuous grifters who only care about making “BIG LINE GO UP”.

It’s all so tiring, so perhaps you can understand why I’d immediately recoil in disgust and go my own way with an alternative I can control.

Or, to put it in even simpler terms:

The “Stack”#

I suppose it’s technically a “stack”, but it seems a bit funny to use the term when referencing a blog setup. Just as with my Plant🌱Smart project, the goal is to automate as much as possible while keeping maintenance requirements and hard- and soft-dollar costs as low as possible. For this, I need only use a handful of tools to keep this space operational.

As far as the question over “cost”, outside of time spent, it’s about ~$100 AUD per year for the domain name. This blog is a very small and inconsequential part of this domain, so the overall cost is absorbed by “other stuff”.

So, the greatest cost is… time? I guess 🤷

Obsidian#

While I won’t be going into what Obsidian is and how it works, I will say it’s been a personal boon in how I keep notes and track of ideas. I have a lot of fleeting / ephemeral thoughts I that would otherwise lose instantly if I didn’t immediately jot them down using this app.

So, it makes perfect sense for me to use my personal vault to store all my blog content. The fact Obsidian content nothing more than Markdown files makes working with them using other bits of tech that much easier.

Oh, it’s free btw.

Hugo#

This is probably one of the more popular options when it comes to static site generators. It’s easy to install, is incredibly extensible and has loads of documentation to help you along. The template syntax sits upon Golang’s templating engine, so if you have a strong background as a Go developer like myself, you’ll be right at home.

However, knowing Go isn’t a hard requirement though it will make getting on top of things quite a bit easier.

What I enjoyed while learning about this project was I got to control every aspect of how I wanted my blog to look and function. Building the current design from the ground up with Hugo was incredibly fun.

Also, free. Very cool.

Cloudflare#

I already used Cloudflare to manage this domain’s DNS settings, so it only made sense to publish my static site to Cloudflare Pages over, say, Vercel or Github Pages. There’s nothing spectacular going on here outside of me just wanting to keep these two things in the same place.

That being said, I have no issues with migrating else where if the need should ever arise. Though, I doubt this blog will hit the 20k file limit of Cloudflare Pages any time soon.

Again, free for the purposes of this article. If you don’t have a dedicated personal domain, you will be provided a subdomain attached to the pages.dev apex.

The Good Stuff#

How is this all put together for day-to-day usage? Luckily, the Cloudflare stuff runs on auto-pilot, so it’s pretty much set-and-forget. I suppose you could say the same about the other components, but they’re the parts I touch the most.

I have a single vault in Obsidian. It’s where all my thoughts go. Stored within is a top-level Blog/ directory. Care to hazard a guess as to what it may contain?

Hugo has the concept of page bundles where you can group all resources associated with your blog articles within a single directory. You’ll notice above all directories mirror the blog posts hosted on this site. In my case, we can consider the directory names to be the human-friendly slugs you see in your address bar that point to the associated content. Within these directories, you’d see any other resource I may link to; source code, images, etc… The best thing about this is I only have to perform a relative reference to these resources. If I want to link to image-1.png, I only have to reference it as ![](/blog/my-blog-publishing-setup/image-1.png) without worrying about specifying an absolute path; very nice.

When I want to write a new article, I first create a new directory here. I may already have the title of the article in mind, but it can be in flux until I decide to publish it. In the new directory, I create a file called index.md. This file contains all the content of the associated article written using Markdown.

I then use an Obsidian template dedicated to new blog posts and apply it to the new file. This ensures I have all front matter properties ready to go. This makes configuring my posts in the editor that much easier.

All that’s left is writing my articles! Well, not really. I need a way to synchronise these files with my local Hugo instance. As you can see here, the content mirrors what I have stored in my Obsidian vault.

This can be easily addressed with 2 small apps:

1. fswatch which monitors a specified directory for changes and allows you to trigger subsequent commands for specific file system events. Basically, I want to watch for any changes in my Obsidian vaults Blog/ directory.
2. rsync to dynamically keep the target Hugo directory in sync with the Obsidian source directory.

I, of course, have this placed in a script that I have running in the background while I write. This is a great help during the drafting phase as I have Hugo dynamically processing and displaying these changes locally. This allows me to easily proof my work visually as I carry on writing.

Here’s the full script:

#!/usr/bin/env bash

SOURCE=${SOURCE:="${1}"}
export SOURCE

DESTINATION=${DESTINATION:="${2}"}
export DESTINATION

fswatch -o "${SOURCE}" | while read -r event; do 
    rsync -av --delete "${SOURCE}" "${DESTINATION}";
done

I keep this running whenever I’m writing a new article. Obsidian saves in almost realtime, so as I type the changes almost immediately sync across to the local Hugo server so I can review my changes.

You effectively run it as:

$ ./sync.sh /path/to/obsidian/blog/ /path/to/hugo/content/

For rsync to work as intended and keep the destination directory completely in sync with the source directory, remember to add a trailing slash to both directory arguments.

No Auto-Commit?#

Nope. Not here. There are a few other peeps with blogs out there that “commit on change”, but I prefer to have a bit more control over what actually gets published. For that, I simply use plain-old git commands to publish my new article:

$ git add -A
$ git commit -m 'some banal new bullshit screed'
$ git push origin main

Cloudflare monitors the associated repository, picks up the change and the auto-magic-ally builds and pushes everything to the public eye.

With this flow, I can see my changes locally in near realtime and push to “production” only when I’m happy with the results.

In Closing …#

I’m stoked to have my very own place again that I have complete control over. I’ve thoroughly enjoyed creating this new blog design and I may even open-source it one day.

That said, I’ve made a very loose commitment to post a new article every week this year of our lord 2025 and I’m hoping this will make things heaps simpler. I only want to worry about what I’m going to write and just get the content out there.

I sincerely hope I can keep this self-imposed weekly commitment. 😬👍

I have no idea if time is actually passing. Obviously, I can eyeball timestamps if available, but there are times when so many lines zip through the buffer that it’s easy to lose track or even go cross-eyed.

It can be tricky to notice that lines are still being tailed if the output doesn’t drastically change in some meaningful or noticeable way. Something I like to is intercept each line and then output some kind of divider whenever n lines have been added to the buffer.

It’s as simple as:

#!/usr/bin/env bash

lines=0
while IFS= read -r line; do
	echo "${line}"
	((lines++))

	if ((lines % 5 == 0)); then
		echo "----------"
	fi
done

Effectively, all this does is:

1. Intercept each line of output being piped into the script.
2. Keep a running tally of lines we’ve intercepted so far; $lines++.
3. If the current tally is divisible by n, or in this case 5, spit out an additional line containing a divider.
4. Keep doing this forever until the process is terminated.

If you were to save this in a file named as divider.sh and set it to execute with something like chmod a+x you could test it by doing something like:

$ while true; do echo "emitting a noop"; sleep 1; done | ./divider.sh

And you’ll see something like the following:

emitting a noop
emitting a noop
emitting a noop
emitting a noop
emitting a noop
----------
emitting a noop
emitting a noop
emitting a noop
emitting a noop
emitting a noop
----------

This is pretty dumb, but now you can see that output is still being placed in your terminal buffer. I’ve set it to every 5 lines, but you can update the script to make that configurable. You could also play a sound when the script places a divider in the buffer using something like tput bel.

Anyway… Enjoy.

Before we begin#

Today, I went ahead and made my Instagram profile private. I have no desire to delete my posts just yet, but decided to go ahead and unfollow everyone as a start. There are several ways to do this:

• API calls using an SDK, which requires a developer account.
• Manually deleting “handraulically” via the native app or browser, but that can quickly become tedious if you have more than a hundred or so follows.
• Random “GreaseMonkey” scripts off the web that may, or may not, work properly if at all.
• Reverse-engineering XHR calls from your browser and writing a simple Bash script to automate the process.

If you’ve read some of my previous blog posts, you probably can guess which one I’ll be going with.

Requirements#

This guide assumes you have some programming or scripting knowledge.

You will need the following on your machine:

• A shell terminal with Bash, or ZSH, support.
• curl to make API calls from the command line.
• jq to easily parse JSON-based responses from said API calls. This can easily be installed using Homebrew or some other supported package manager.
• A modern browser that supports a developer tools console to intercept XHR calls.

It’s worth mentioning that I am using a MacBook with the Chrome browser, but other webkit-based browsers should support similar functionality.

Fire up the browser!#

Open up your browser, or new tab, and navigate to your Instagram profile. Open your browser’s developer console and navigate to the “Network” tab. Clear out whatever requests are currently listed and then filter by “Fetch/XHR”.

Your following list#

We need to intercept an XHR request that returns a JSON body containing some of your followers. Click the “following” link and monitor the resulting requests that pop in the list on the “Network” tab.

You should see something like following/count=12... in the list. Right-click that item and select “Copy as cURL”. Paste the new value in your clipboard into a scratch file for reference later.

Be aware this command will contain all the headers required to make requests from your terminal on your behalf. Do NOT share these details with anyone. I haven’t checked how long until the tokens within the auth headers expire, so assume they are long(ish)-lived and treat them accordingly.

An unfollow request#

Next, we need to intercept an XHR request to unfollow someone. Going back to your following list, select a random user and unfollow them while once again keeping an eye on the “Network” tab.

You’re going to see something like the following; an XHR event making a POST request to “destroy” your chosen follower. Once again, you’ll right-click and “Copy and cURL”. Paste this into your scratch file as well for future reference.

Putting it all together#

Now that you have your two types of requests, we’ll need to script the following steps:

• Execute a curl request to fetch a JSON body containing the accounts you follow, one page of results at a time.
• Use jq to extract their Instagram IDs.
• Store the results in a variable named… drumroll, pls… $ids.
• Iterate through each $id.
• Execute a curl request to unfollow each $id.

Here is the meat of the script. I have included only the necessary headers required to successfully make these requests on your Instagram account’s behalf. You’ll need to swap out the ... with your own values.

You may also notice that I’ve change the count=... parameter to 100. It may be able to go higher, but I haven’t tested it.

ids=$(
  curl 'https://www.instagram.com/api/v1/friendships/.../following/?count=100&hl=en' \
    -H 'cookie: ...'           \
    -H 'x-asbd-id: ...'        \
    -H 'x-csrftoken: ...'      \
    -H 'x-ig-app-id: ...'      \
    -H 'x-ig-www-claim: ...'   \
    -H 'x-requested-with: ...' \
    -H 'x-web-session-id: ...' | jq -r '.users[].id'
)

while IFS= read -r id; do
  echo -n "Unfollowing user '${id}'"

  curl -s -o /dev/null "https://www.instagram.com/api/v1/friendships/destroy/${id}/?hl=en" \
    -H 'cookie: ...'           \
    -H 'x-asbd-id: ...'        \
    -H 'x-csrftoken: ...'      \
    -H 'x-ig-app-id: ...'      \
    -H 'x-ig-www-claim: ...'   \
    -H 'x-requested-with: ...' \
    -H 'x-web-session-id: ...' \
    --data-raw "container_module=profile&nav_chain=PolarisProfilePostsTabRoot%3AprofilePage%3A1%3Avia_cold_start%2CPolarisProfilePostsTabRoot%3AprofilePage%3A2%3Aunexpected&user_id=${id}"

  echo ' ... done!'
done <<< "${ids}"

echo "Finished"

You can save this as a file and make it executable, but I just paste this bad boy into your terminal. The above script will remove 100 accounts at a time. Just keep executing the script until you no longer see results like the following:

Unfollowing user '111'... done
Unfollowing user '222'... done
Unfollowing user '333'... done
Unfollowing user '444'... done
Unfollowing user '555'... done
Unfollowing user '666'... done
Unfollowing user '777'... done
Unfollowing user '888'... done
Finished

Caveats, gotchas & other things#

I’ve only had a few hundred accounts that I followed, so I didn’t feel the need to make this a bullet-proof solution. There’s quite a bit missing and things can go wrong. Here are some things to consider off the top of my head :

• The session tokens will expire eventually, so you will have to refer back to your “Network” tab in your developer tools console to get new ones.
• As this example only unfollows a static amount at a time, re-executing the script may become tedious for very large follow numbers. Perhaps, you can modify this script to add some basic pagination.
• There is no error handling here, so keep an eye out for potential rate limiting or expired token issues with the Instagram API.
• Constantly updating session header values can be made a bit simpler by resorting to variables instead.

In closing …#

Cleaning out old, unused or unwanted social media accounts can be liberating. I’ve recently gutted my Twitter presence and I haven’t been on Facebook in years, though I still do use Messenger to keep in touch with a handful of people. I’d prefer using Signal for this, but trying to convince other people to install yet another messaging app is like pulling teeth.

Anyway, I actually enjoy writing these kinds of posts. What other social networks should I cover? LinkedIn? Threads? What are some ways you can improve and build on the above? Lemme know in the comment section below.

Headings#

Sint sit cillum pariatur eiusmod nulla pariatur ipsum. Sit laborum anim qui mollit tempor pariatur nisi minim dolor. Aliquip et adipisicing sit sit fugiat commodo id sunt. Nostrud enim ad commodo incididunt cupidatat in ullamco ullamco Lorem cupidatat velit enim et Lorem. Ut laborum cillum laboris fugiat culpa sint irure do reprehenderit culpa occaecat. Exercitation esse mollit tempor magna aliqua in occaecat aliquip veniam reprehenderit nisi dolor in laboris dolore velit.

Heading two#

Aute officia nulla deserunt do deserunt cillum velit magna. Officia veniam culpa anim minim dolore labore pariatur voluptate id ad est duis quis velit dolor pariatur enim. Incididunt enim excepteur do veniam consequat culpa do voluptate dolor fugiat ad adipisicing sit. Labore officia est adipisicing dolore proident eiusmod exercitation deserunt ullamco anim do occaecat velit. Elit dolor consectetur proident sunt aliquip est do tempor quis aliqua culpa aute. Duis in tempor exercitation pariatur et adipisicing mollit irure tempor ut enim esse commodo laboris proident. Do excepteur laborum anim esse aliquip eu sit id Lorem incididunt elit irure ea nulla dolor et. Nulla amet fugiat qui minim deserunt enim eu cupidatat aute officia do velit ea reprehenderit.

Heading three#

Voluptate cupidatat cillum elit quis ipsum eu voluptate fugiat consectetur enim. Quis ut voluptate culpa ex anim aute consectetur dolore proident voluptate exercitation eiusmod. Esse in do anim magna minim culpa sint. Adipisicing ipsum consectetur proident ullamco magna sit amet aliqua aute fugiat laborum exercitation duis et.

Heading four#

Commodo fugiat aliqua minim quis pariatur mollit id tempor. Non occaecat minim esse enim aliqua adipisicing nostrud duis consequat eu adipisicing qui. Minim aliquip sit excepteur ipsum consequat laborum pariatur excepteur. Veniam fugiat et amet ad elit anim laborum duis mollit occaecat et et ipsum et reprehenderit. Occaecat aliquip dolore adipisicing sint labore occaecat officia fugiat. Quis adipisicing exercitation exercitation eu amet est laboris sunt nostrud ipsum reprehenderit ullamco. Enim sint ut consectetur id anim aute voluptate exercitation mollit dolore magna magna est Lorem. Ut adipisicing adipisicing aliqua ullamco voluptate labore nisi tempor esse magna incididunt.

Heading five#

Veniam enim esse amet veniam deserunt laboris amet enim consequat. Minim nostrud deserunt cillum consectetur commodo eu enim nostrud ullamco occaecat excepteur. Aliquip et ut est commodo enim dolor amet sint excepteur. Amet ad laboris laborum deserunt sint sunt aliqua commodo ex duis deserunt enim est ex labore ut. Duis incididunt velit adipisicing non incididunt adipisicing adipisicing. Ad irure duis nisi tempor eu dolor fugiat magna et consequat tempor eu ex dolore. Mollit esse nisi qui culpa ut nisi ex proident culpa cupidatat cillum culpa occaecat anim. Ut officia sit ea nisi ea excepteur nostrud ipsum et nulla.

Heading six#

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Paragraphs#

Incididunt ex adipisicing ea ullamco consectetur in voluptate proident fugiat tempor deserunt reprehenderit ullamco id dolore laborum. Do laboris laboris minim incididunt qui consectetur exercitation adipisicing dolore et magna consequat magna anim sunt. Officia fugiat Lorem sunt pariatur incididunt Lorem reprehenderit proident irure. Dolore ipsum aliqua mollit ad officia fugiat sit eu aliquip cupidatat ipsum duis laborum laborum fugiat esse. Voluptate anim ex dolore deserunt ea ex eiusmod irure. Occaecat excepteur aliqua exercitation aliquip dolor esse eu eu.

Officia dolore laborum aute incididunt commodo nisi velit est est elit et dolore elit exercitation. Enim aliquip magna id ipsum aliquip consectetur ad nulla quis. Incididunt pariatur dolor consectetur cillum enim velit cupidatat laborum quis ex.

Officia irure in non voluptate adipisicing sit amet tempor duis dolore deserunt enim ut. Reprehenderit incididunt in ad anim et deserunt deserunt Lorem laborum quis. Enim aute anim labore proident laboris voluptate elit excepteur in. Ex labore nulla velit officia ullamco Lorem Lorem id do. Dolore ullamco ipsum magna dolor pariatur voluptate ipsum id occaecat ipsum. Dolore tempor quis duis commodo quis quis enim.

Blockquotes#

Ad nisi laborum aute cupidatat magna deserunt eu id laboris id. Aliquip nulla cupidatat sint ex Lorem mollit laborum dolor amet est ut esse aute. Nostrud ex consequat id incididunt proident ipsum minim duis aliqua ut ex et ad quis. Laborum sint esse cillum anim nulla cillum consectetur aliqua sit. Nisi excepteur cillum labore amet excepteur commodo enim occaecat consequat ipsum proident exercitation duis id in.

Labore ea magna Lorem consequat aliquip consectetur cillum duis dolore. Et veniam dolor qui incididunt minim amet laboris sit. Dolore ad esse commodo et dolore amet est velit ut nisi ea. Excepteur ea nulla commodo dolore anim dolore adipisicing eiusmod labore id enim esse quis mollit deserunt est. Minim ea culpa voluptate nostrud commodo proident in duis aliquip minim.

Ipsum excepteur cupidatat sunt minim ad eiusmod tempor sit.

Adipisicing voluptate ipsum culpa voluptate id aute laboris labore esse fugiat veniam ullamco occaecat do ut. Tempor et esse reprehenderit veniam proident ipsum irure sit ullamco et labore ea excepteur nulla labore ut. Ex aute minim quis tempor in eu id id irure ea nostrud dolor esse.

Lists#

Ordered List#

1. Longan
2. Lychee
3. Excepteur ad cupidatat do elit laborum amet cillum reprehenderit consequat quis. Deserunt officia esse aliquip consectetur duis ut labore laborum commodo aliquip aliquip velit pariatur dolore.
4. Marionberry
5. Melon
   1. Cantaloupe
   2. Honeydew
   3. Watermelon
6. Miracle fruit
7. Mulberry

Unordered List#

• Olive
• Orange
  • Blood orange
  • Clementine
• Papaya
• Ut aute ipsum occaecat nisi culpa Lorem id occaecat cupidatat id id magna laboris ad duis. Fugiat cillum dolore veniam nostrud proident sint consectetur eiusmod irure adipisicing.
• Passionfruit

Horizontal rule#

In dolore velit aliquip labore mollit minim tempor veniam eu veniam ad in sint aliquip mollit mollit. Ex occaecat non deserunt elit laborum sunt tempor sint consequat culpa culpa qui sit. Irure ad commodo eu voluptate mollit cillum cupidatat veniam proident amet minim reprehenderit.

In laboris eiusmod reprehenderit aliquip sit proident occaecat. Non sit labore anim elit veniam Lorem minim commodo eiusmod irure do minim nisi. Dolor amet cillum excepteur consequat sint non sint.

Code#

Inline code#

Ad amet irure est magna id mollit Lorem in do duis enim. Excepteur velit nisi magna ea pariatur pariatur ullamco fugiat deserunt sint non sint. Duis duis est code in text velit velit aute culpa ex quis pariatur pariatur laborum aute pariatur duis tempor sunt ad. Irure magna voluptate dolore consectetur consectetur irure esse. Anim magna <strong>in culpa qui officia</strong> dolor eiusmod esse amet aute cupidatat aliqua do id voluptate cupidatat reprehenderit amet labore deserunt.

Tables#

Highlighted#

Et fugiat ad nisi amet magna labore do cillum fugiat occaecat cillum Lorem proident. In sint dolor ullamco ad do adipisicing amet id excepteur Lorem aliquip sit irure veniam laborum duis cillum. Aliqua occaecat minim cillum deserunt magna sunt laboris do do irure ea nostrud consequat ut voluptate ex.

package main

import (
    "fmt"
    "net/http"
)

func handler(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "Hi there, I love %s!", r.URL.Path[1:])
}

func main() {
    http.HandleFunc("/", handler)
    http.ListenAndServe(":8080", nil)
}

tmux set -g status-right "#[align=absolute-centre]#[fg=#f8f9f2]#W#[fg=#51cd97]#{?client_prefix,#[fg=#d0689d],#[fg=#51cd97]}.#[align=right]#{?window_bigger,[#{window_offset_x}#,#{window_offset_y}] ,}#[fg=#404040,underscore]#S#[none] "
tmux set -g status-style "bg=#1f1f1f,fg=#f8f8f2"
tmux set -g window-status-current-format "#{?client_prefix,#[fg=#d0689d],#[fg=#51cd97]}"
tmux set -g window-status-format "#[fg=#404040]"
tmux set -g status-left ' '
tmux set-window-option -g pane-border-style "fg=#404040"
tmux set-window-option -g pane-active-border-style "fg=#51cd97"

Ex amet id ex aliquip id do laborum excepteur exercitation elit sint commodo occaecat nostrud est. Nostrud pariatur esse veniam laborum non sint magna sit laboris minim in id. Aliqua pariatur pariatur excepteur adipisicing irure culpa consequat commodo et ex id ad.

Diagrams#

Mermaid turns text into diagrams. A fenced code block with the mermaid language renders one, and so does the mermaid shortcode. Each diagram is rendered to an SVG at build time and inlined into the page, so no JavaScript ever ships and the site keeps its no-external-requests rule.

Flowchart#

The example below is this site’s own deployment pipeline, end to end: a git push at the desk, through the homelab, out to the Cloudflare edge and finally into a reader’s browser. The full story lives in My Blog Now Ships From My Homelab!.

Sequence#

The same pipeline again, compressed into a handshake. This one is a plain mermaid fence instead of the shortcode. Both forms render the same way.

Inline elements#

Sint ea anim ipsum ad commodo cupidatat do exercitation incididunt et minim ad labore sunt. Minim deserunt labore laboris velit nulla incididunt ipsum nulla. Ullamco ad laborum ea qui et anim in laboris exercitation tempor sit officia laborum reprehenderit culpa velit quis. Consequat commodo reprehenderit duis irure esse esse exercitation minim enim Lorem dolore duis irure. Nisi Lorem reprehenderit ea amet excepteur dolor excepteur magna labore proident voluptate ipsum. Reprehenderit ex esse deserunt aliqua ea officia mollit Lorem nulla magna enim. Et ad ipsum labore enim ipsum cupidatat consequat. Commodo non ea cupidatat magna deserunt dolore ipsum velit nulla elit veniam nulla eiusmod proident officia.

Proident sit veniam in est proident officia adipisicing ea tempor cillum non cillum velit deserunt. Voluptate laborum incididunt sit consectetur Lorem irure incididunt voluptate nostrud. Commodo ut eiusmod tempor cupidatat esse enim minim ex anim consequat. Mollit sint culpa qui laboris quis consectetur ad sint esse. Amet anim anim minim ullamco et duis non irure. Sit tempor adipisicing ea laboris culpa ex duis sint anim aute reprehenderit id eu ea. Aute excepteur proident Lorem minim adipisicing nostrud mollit ad ut voluptate do nulla esse occaecat aliqua sint anim.

Incididunt in culpa cupidatat mollit cillum qui proident sit. In cillum aliquip incididunt voluptate magna amet cupidatat cillum pariatur sint aliqua est enim anim voluptate. Magna aliquip proident incididunt id duis pariatur eiusmod incididunt commodo culpa dolore sit. Culpa do nostrud elit ad exercitation anim pariatur non minim nisi adipisicing sunt officia. Do deserunt magna mollit Lorem commodo ipsum do cupidatat mollit enim ut elit veniam ea voluptate.

Reprehenderit non eu quis in ad elit esse qui aute id incididunt dolore cillum. Esse laboris consequat dolor anim exercitation tempor aliqua deserunt velit magna laboris. Culpa culpa minim duis amet mollit do quis amet commodo nulla irure.

Callouts#

Nostrud ex consequat id incididunt proident ipsum minim duis aliqua ut ex et ad quis.

Images#

Every image on this page is Unsplash stock, hosted here so the site keeps its no-external-requests rule. Click any of them to zoom in. Click again, or press Escape, to put it back.

Single#

A lone image takes the img shortcode: a figure, an optional attribution underneath and the zoom.

Aute officia nulla deserunt do deserunt cillum velit magna. Officia veniam culpa anim minim dolore labore pariatur voluptate id ad est duis quis velit dolor pariatur enim.

Strip#

A run of images scrolls sideways in the strip shortcode. Each image keeps its own zoom, and its credit follows it into the lightbox.

Labore ea magna Lorem consequat aliquip consectetur cillum duis dolore. Et veniam dolor qui incididunt minim amet laboris sit.

Masonry#

The masonry shortcode packs a wall of mixed heights into columns. Same zoom, same credits.

Ex amet id ex aliquip id do laborum excepteur exercitation elit sint commodo occaecat nostrud est.

Accumulation of Underlying Issues#

Over time, systems and processes can accumulate small issues, technical debt, or unnoticed problems. These issues can build up, leading to a higher likelihood of a significant failure or incident occurring as time goes on.

Complacency and Reduced Vigilance#

When a system or service has been running smoothly for an extended period, teams may become complacent and less vigilant. They might not be as proactive in monitoring, testing, and maintaining the system, which can increase the risk of failure.

Evolving Environments#

As technology and business environments evolve — as they inevitably do in our space —, the context in which a system operates also changes. What was once a stable and reliable configuration may no longer be suitable, leading to unexpected issues or failures when the system is finally pushed to its limits.

Regression to the Mean#

The law of large numbers suggests that over time, events tend to revert to their average or “mean” frequency. If you’ve experienced an unusually long period without incidents, statistics may suggest that you’re due for one soon, just as a run of heads in a coin toss doesn’t make tails any less likely on the next toss.

Maintaining Awareness#

Mitigation Strategies#

Recognize the importance of proactively addressing issues before they accumulate. This involves regular monitoring, capacity planning, load testing, and maintenance to reduce the likelihood of a sudden failure.

Risk Management#

Focus on identifying and managing risks, even during periods of relative stability. They plan for various failure scenarios and aim to minimize their impact through redundancy, graceful degradation, and fault-tolerant design.

Continuous improvement#

Promote a culture of continuous improvement, encouraging teams to learn from past incidents, conduct post-mortems, even live-fire exercises and apply those lessons to prevent similar issues in the future.

Metrics & Monitoring#

Use metrics and monitoring tools to maintain a vigilant eye on system health and performance. They set thresholds and alarms to detect anomalies early, regardless of how long it’s been since the last incident.

At any given point your production workloads may be operating under any number of unknown failure modes. Things break; it’s inevitable. Adjust your expectations accordingly and build around this fact.

In Conclusion#

The idea that the longer something doesn’t happen, the sooner it will is a reminder of the importance of vigilance, proactive maintenance, and risk management not only in site reliability engineering, but software engineering as a whole.

This may not be a deterministic law as it highlights the tendency for issues to accumulate over time if not addressed, making it crucial to maintain a robust and resilient system.

It’s as simple as that?#

That was the idea, at least. I just wanted a single place that had all the information I needed so I could make informed purchasing decisions. I also figured I couldn’t possibly be the only person who has this problem. So, I set off to make this project during the holiday break of 2022.

However, I didn’t want to make it too easy for myself…

A challenge!#

I work as a weird combination of SRE and DevOps engineer. I have plenty of smarts when it comes to the technical side of hosting and running things, but it’s been years since I’ve done any front-end work. Career-wise, I need to be able to speak the same language as the teams I have to support. So, understanding how far behind that portion of my skillset had become, I thought this would be the perfect opportunity to brush up.

The Requirements:#

• Must keep operational costs as close to zero as possible. The only money I’ve put down on this so far is the $20 AUD to purchase the domain name.
• Must be hosted on Cloudflare Pages. I could’ve chosen Github Pages to keep everything in one place, but automated Cloudflare builds & deployments work out of the box with minimal configuration. Besides, I’ve already worked with the latter and I wanted the challenge of trying something new.
• Must be completely static. There should be no server-side rendering, processing or other explicit backend dependencies to manage. For this, I use the pre-rendering functionality that comes packaged with SvelteKit. I’ve been working with this for only a few weeks now and I’m a full convert.
• All data must be served statically as well. The entirety of the data set is contained within a single JSON file, which you can view at /plants.json. This is the source of truth for all derivative data sets and lookup tables used on this site. It’s effectively what I call a “dumb API”. Check out the API documentation if you’d like to know more about it.
• Must use SvelteKit, TypeScript, TailwindCSS and Vite. I had zero working knowledge of any of these and my frontend peers can’t seem to shut up about them. So… why not?
• Must be fast. Everything is static, compressed, cached and sitting behind a world-class CDN. I’ve worked in a network performance and load testing SaaS for close to 5 years now. I wouldn’t be able to look myself in the mirror if I couldn’t easily do this one. 😅
• Must be open-source and community-driven. At one point, I would like to take the hands off the wheel and see if other interested parties would like to get involved and help out with managing datasets and fixing bugs. GitHub allows for pretty much all of this. Check how to contribute or see the latest contributions.

So far, it’s going quite well. I haven’t had any issues with meeting any of these self-imposed development constraints.

Any Caveats?#

Definitely. The most obvious one would be image storage which has a direct effect on not only repository size — which currently clocks in at over 1.5GB — but, also build and deployment speeds. I could shell out $5 - $10 for object storage and image processing, but that would go against the first constraint. For now, image data will live in the GitHub repository as a perfectly reasonable compromise.

Where did you source all this data?#

There are quite a few sources I’ve collated from, but these are the main ones.

1. iNaturalist is the best source of high-quality, community-driven creative commons license photography. All images have been sourced from this site along with licensing and attribution data.
2. ASPCA was used to initially prime the first dataset. This is also where I sourced most of the common name and symptom data.
3. Wikipedia is the best source of scientific classification data out there.

All of this disparate data was collated and munged together by several processing scripts written in Go as Magefiles. It got me about 95% there, but it still needs quite a bit of handraulic finessing.

Where to go from here?#

I think I’ve met most, if not all, of my requirements. The datasets for the project still need a lot of love and I plan on supporting listings for a variety of other pet species. I already have the data; just need to go through it with a fine-toothed comb. Not to mention responsiveness for smaller screens needs a solid amount of work.

I’m having loads of fun at the moment learning new things. I hope I can keep doing this for a while longer. However, I do have other things planned for the future and will be using what I’ve learned here as a kind of launching pad.

I sincerely hope you find Plant🌱Smart as useful as I had fun making it.

Let’s leave out all doubt regarding our god-tier levels of snarkiness.

Today, we’re going to write a laughably-simple Bash script that lets our coworkers know exactly what we think. Along the way, you’ll learn a little bit more about Bash such as:

1. Setting some default flags.
2. Reading text from stdin.
3. Parameter expansion.
4. Looping through each character of a string.
5. Creating random numbers.
6. Swapping character types using the tr command.
7. And, finally, making your long-suffering coworkers’ eyes roll.

Here We Go!#

First, I’m going to just paste the entire script here and then we’ll go through all the important bits line-by-line:

#!/usr/bin/env bash

set -eo pipefail

read text

for (( i=0; i < "${#text}"; i++ )); do
  if [[ $(( "${RANDOM}" % 2 )) -eq 0 ]]; then
    echo -n "${text:${i}:1}" | tr '[:lower:]' '[:upper:]'
  else
    echo -n "${text:${i}:1}" | tr '[:upper:]' '[:lower:]'
  fi
done

echo

Alright, let’s take it from the top. All Bash scripts should start with a “shebang line”. This tells your terminal which environments and runtimes your script should run under. There are more traditional versions of this — #!/bin/bash, for instance — but, our way is considered to be the most portable overall.

#!/usr/bin/env bash

Next, we setup some environmental flags. I use at least the following for all of my personal scripts:

set -eo pipefail

Here is what they do:

1. set -e: Instructs Bash to immediately exit if any command has a non-zero exit status. This is how it works in most languages, but with Bash, it just keeps on trying to execute subsequent commands. This is generally acceptable on the command line, but not in a script. If we encounter an error, we want to exit immediately.
2. set -o pipefail: This tells Bash not to mask errors that may appear in a pipeline of commands. We want any failed command’s exit code in a pipeline to bubble up to the script itself and then exit with that code.

Speaking of pipelines, we want to be able to pipe text to this script so we can do something like the following:

echo "wilhelm, i asked you to patch the server." | ./spongebob
wiLHELm, I AsKEd yOu TO PatCh The seRvEr.

Let’s halt the script and wait for user input and then assign that input to variable text:

read text

Now that we have some text, we need to start randomly-swapping between upper and lower case characters. In order to do that, we need to know the number of characters in our string so we can build a nice loop:

for (( i=0; i < "${#text}"; i++ )); do
  # ... sweet code goes here 
done

We could do something in a sub-shell here like $(echo "${text}" | wc -c) to get the character count, but why do that when we could get the same result with "${#text}". This lovely bit of “shell parameter expansion” helps us avoid sub-commands and sub-shells.

Next, we want to be able to randomly swap the capitalisation of each character in the string to get the appropriate effect. A character is either upper- or lower-case, so minimum we need only to swap randomly between 2 values; 0 and 1. We can get this effect in Bash by using the internal ${RANDOM} function like so with the modulo ( or “mod” ) operator:

if [[ $(( "${RANDOM}" % 2 )) -eq 0 ]]; then
  # ... do something
else
  # ... do the opposite
fi

We’re now at the point where we want to modify the character associated with the for loop’s current iteration, but how do we get it from the text variable? Once again we use some parameter expansion in the form of ${text:offset:length}. We have the value for “offset” already; it’s ${i}. We only want a single character returned, so we use 1 for “length”.

echo -n "${text:${i}:1}"

This spits out the current character for each iteration of our loop. The -n in the echo statement simply stops Bash from adding a newline to the end of the result. Otherwise, you’d get a line per character as output.

Finally, we want to do case swapping. For this, we pipe the output of the above echo command into the tr command. Within the above if statement, if our random number equals 0, let’s swap a lowercase [:lower:] character with an uppercase [:upper:]:

echo -n "${text:${i}:1}" | tr '[:lower:]' '[:upper:]'

And, then, we do the opposite for any other result:

echo -n "${text:${i}:1}" | tr '[:upper:]' '[:lower:]'

You’ll notice a final echo command at the bottom of the script. Thanks to the final echo -n ... command from the previous for loop, you may find your results prepended to your command prompt. This ensures a newline makes it to the end of your 🧽 output.

Testing Time#

Save the script as spongebob and make it executable with chmod a+x spongebob. That should be it! Here are a few of my results:

$ echo "abandon all hope, ye who enter here." | ./spongebob
abaNDON ALl Hope, yE wHO EnTer heRE.
$ echo "Wilhelm, that last deployment failed. Could you roll it back, please?" | ./spongebob
WilhelM, THAT LASt dEployMeNT fAILED. coUlD YOu RoLL It BaCk, PlEaSE?
$ echo "Wilhelm, I am your manager. Please, stop mocking me." | ./spongebob
wIlHElM, i aM yOUr MANagER. PlEasE, sTOP mOCKINg mE.
$ echo "Wilhelm, should we use Kubernetes for this?" | ./spongebob
WilHELM, should We Use KuBerNeTEs for THiS?

In Conclusion…#

Ok, obviously this was all a clever ploy to get you to learn a few more Bash things. Definitely do not use this new knowledge to frustrate and annoy your coworkers. Please, be considerate of other people’s mental well being. I mean, what I meant to say was:

There are any number of ways you could change this script. Instead of liberal use of echo, you could just build a string assigned to a variable and spit that out at the end. Instead of using else you could use continue to skip the final if fallback. Try a few and see what changes.

For the purposes of this article I felt the above sequence of commands was clear enough for most people to follow along.

I hope you learned something!

1. Bash for portability.
2. jq to filter JSON objects from RESTful APIs.
3. AWS CLI as I cannot stand dealing with the web console.
4. curl ( with wget as a reasonable fallback ) to interact with various APIs.
5. Terraform for most of my IaC needs.

It wouldn’t be an exaggeration to say I literally use these tools every day. Specifically, the first 3 items. Furthermore, to say that manually sorting through Docker containers is a practice in tedium would be a massive understatement. Because of this, not a day passes where I am not grateful to have found jq.

In this case, my favourite duo is Docker and jq… which is what this article is about. Let’s learn some fun filtering patterns to make your life a bit easier if you’re stuck in a terminal all day like myself.

Setting Up#

First and foremost, you’re going to need to install jq in your test environment. If you’re on most common Linux distributions:

apt-get install jq

Or, on MacOS:

brew update && brew install jq

I’m assuming that if you’re reading this you already have Docker installed in your test environment. If not, head out to their website and read their installation documentation. It tends to vary wildly depending on your OS.

Let’s spin up some containers we can play around with. I use redis for stuff like this:

for i in {1..5}; do docker run -it --rm -d redis; done

Environmental Variables#

Sourceable Blocks#

There may be times I wish to collate all environmental variables associated with a set of containers and stick them a .env file to source later. Here we create a block for all the redis containers we just spun up:

docker inspect $(docker ps -q) | jq -r '
    .[].Config.Env
  | flatten 
  | .[]
'

This one will generate a lot of duplicates as all our test containers are effectively clones. What if we want a distinct set of instead? We can use the unique filter:

docker inspect $(docker ps -q) | jq -r '
	[
	  .[].Config.Env
	] 
  | flatten 
  | unique 
  | .[]
'

What if I want a set from specific containers?

docker inspect $(docker ps -q) | jq -r '
    [
	    .[] 
      | select([.Id] | inside([
	      "747c2c92855f88a8e9aa9709dcdf3a01f1677e70bf4c0bf0e520eb38ac502876",
	      "2cf70261ef62bc36d19aba02f8ef7b8d7aabfcb1e9f4593a919baa17f80aca5b"
	    ]))
      | .Config.Env
	] 
  | flatten 
  | unique 
  | .[]
'

How about filtering by a specific ip address for the default bridge network? Using a different network? Just replace bridge with the alternate network name.