Ben's Blog

Passing Behavior Through A Network

Wed, 01 Jul 2026 00:00:00 GMT

Ben's Blog - Passing Behavior Through A Network

Passing Behavior Through A Network

Jul 1st, 2026 Ben

You can pass a description through a network. You can't pass behavior or code through a network. With a strong declarative and semantic language, building the code on both ends of your network to allow a description of the behavior (your declarative language) to inform both sides to make it feel like you're passing the behavior itself through.

HTML is a great example of this. Add the readonly attribute to an input element in your HTML and now the input behaves differently (you can't edit the field). Your readonly attribute doesn't actually make it not-editable but tells the browser engine to render it that way and disallow typing.

On the web, Custom Elements are a great way to extend the html engine. Adding a star-rating component or segmented-control element via JS and customElements.define can then be declaratively invoked by your HTML. It's never been easier! This is a key conceptual point behind HTMX too, with custom attributes instead of custom elements.

JSON Schema is less semantically rich out of the gate, but has support for attributes on fields that can be used in a very similar way. You need to create the engine that understands those attribute semantics. This gives you more flexibility than HTML provides at the expense of building it yourself.

React Server Components also fit this model. React is the engine deployed via javascript bundle, your components provide the semantics, and some form of json is the component description over the network.

Handoff Between Release and Production

Fri, 12 Jun 2026 00:00:00 GMT

Ben's Blog - Handoff Between Release and Production

Handoff Between Release and Production

Jun 12th, 2026 Ben

Most days as software engineers we don't think of how our release actually makes it to production. If we have one of numerous GitOps integrations, we just push to Github. Maybe someone wrote a script that runs or an action is manually fired. Occasionally you might find a slower release cadence with some more ceremony around it. Only once have I ever "thrown it over the fence" to another engineer dedicated to the job (it was a very old product by that point).

Lots of companies have made it their business to help you deploy because you want to develop an app, not develop a deployment pipeline, right? At least, that's the general salse pitch I hear. Using their process means releasing on their infrastructure, paying their prices. You may or may not be able to develop well with their system. It might be somewhat of a black box. I don't want to attribute anything malicious to them, their goal is to make it seem seamless and magical to you. But as engineers, we know that it isn't magical. And we pride ourselves in being able to take apart the internals when we need (sometimes when we want!).

What I've Tried

If you aren't using a provider, how might you set up a deployment pipeline? For years now with this personal site I had a Digital Ocean Droplet I had set up manually with Caddy, then I just built a Jekyll site on my computer and rsync'd the files up. As rudimentary as it might sound, it worked great for me. I never had any downtime (I would've noticed, I think, because it wouldn't have come back up on its own) and I could focus on writing these posts.

That doesn't "scale" past static sites, and it doesn't really tell you what was released when. For some personal projects, I started using Kamal. That worked really great for Rails applications once I got a registry set up, but it didn't work very well for my static sites. Working with containers was very nice.

Looking at something like Kubernetes, I ended up going with podman quadlets instead. I thought it would be just a bit easier, and I still think it is. And it introduced me to the power of systemd. I had all the power of container deployments and all the power of systemd, so I wrapped all my static sites in a caddy container and shipped it up to my Droplet. This worked great, until I realized I had to deploy all my sites in order to deploy any of them. I couldn't have multiple containers all sharing ports 80 and 443, so back to the drawing board I went.

Using caddy as a reverse proxy, I can now deploy all my sites individually. Combining the powers of systemd, podman, and caddy, I can deploy static sites and containers with equal ease, and manage them with the same commands. I don't think I would want to deploy a rails app directly on to the machine, but I shouldn't ever need to. Containers cover that case amazingly well. Caddy also has some fastcgi directies I might try eventually, to add interactivity to my static sites without a whole web app.

Moving Deployment Control to the App Repo

With those in place, I didn't want to go back to just rsync'ing the static files back to the Droplet. I wanted something a little more controlled than that. The droplet runs Ubuntu and nfpm makes it trivial to build debain packages. Using a debian package, I can decide where all my files should be placed and installation will run a postinstall script. I can put my caddyfile in place, and systemd unit files, podman quadlets, static files, etc into the debian package. I can rsync that to the server then run dpkg -i to install.

How's that different that rsync'ing the files up directly? It moves where the control of the release is. My "deploy" scripts now live in an infrastructure repo. But my apps need to be released more often than that. I want to be able to change what the app needs with impunity, without having to modify a different repo. I've taken a hard dependency on the expectation of caddy and podman being present, but that doesn't seem different than other deployment processes. There are usually some release assumptions baked into the app repo. I'll only need to change the deploy scripts if I change something about the computer it's running on. Worst case, I change distros, but nfpm makes it trivial to build a rpm or other distro packages.

With this setup, I can even add container images to the debian package and load them with the postinstall script. Or pull them from a registry.

Using systemd and caddy, I can install a sensitive file in /etc then decrypt it at runtime into /run.

I can set up systemd timers or path files to perform backups on a schedule or reload services when files change.

From what I've read about Kubernetes, I have 90% of what I would use on my personal sites. And even if I'm not in K8s, I think I'm getting a taste for what they provide and why, if not necessasrily how. But I also don't need to run the whole service K8s, or even minikube, require.

Versioning

With containers under your control, you might pin to a latest tag so an auto-update picks it up. Debian packages are the first deployment strategy I've used that feels like it strongly benefits from version numbers. Maybe I feel I need versioning now because debian pacakge don't have sha's of any kind like containers do (checksums, I suppose). Mostly I feel like it's an important way to talk about releases, so I wanted to have something similar.

I'm using CalVer because nobody is consuming these sites based on SemVer rules. I'm using git tags to keep track of it. 5 lines of bash is all I need to query and calculate the next version.

# find the current/latest tag
git tag -l 'v*' | sed 's/^v//' | sort -V | tail -1

# create next tag
prefix=$(date +%Y.%m)
last=$(git tag -l "v${prefix}.*" | sed "s/^v${prefix}\.//" | sort -n | tail -1)
next=$((${last:-0} + 1))
version="${prefix}.${next}"

Release

Creating a release is a mise task that checks for a clean git worktree, calculates the new version number, runs my build task with the version number, then creates the git tag. The file is not very long, even with checks and confirmation. It builds a file to my local ~/.cache directory, which I think it appropriate since the release could easily be recreated by running the build pipeline again. In a larger system, or if you ran this on your git forge, this might become an artifact you download during deployment. Since my deployment is from my machine, I use ~/.cache as my place to share the file.

Deploy

After I have a file with the version number as the name, my deployment script can simply look in the shared folder, grab the lastest version number, then deploy it. It's as simple as collecting the necessary information out of my OpenTofu state, resync'ing the package up, and running dpkg -i. If you had a CI pipeline, the rsync might be a wget command. If you wanted more control, you could set up a apt repository. Then your actual deployement would just be an apt update; apt upgrade . I use rsync because I'm keeping everything local for now.

Watch out for name collisions!

Wed, 10 Jun 2026 00:00:00 GMT

Ben's Blog - Watch out for name collisions!

Watch out for name collisions!

Jun 10th, 2026 Ben

While upgrading my websites, I noticed my caddyfile was gone. What happened?? It looks like dpkg decided to upgrade my package without my knowledge and there was something else named "staticsite" in apt already. Scary! I think this was mostly harmless to my site, but it could have been bad. I'll have to double check for name collisions before creating anymore deb packages.

June 2026 Tech Stack

Wed, 10 Jun 2026 00:00:00 GMT

Ben's Blog - June 2026 Tech Stack

June 2026 Tech Stack

Jun 10th, 2026 Ben

I like writing these out to see how they change over time. I've added a lot of components to them over the years as I learn more about tools. I think I might finally be in a place where I could take something from nothing to deployed without too much click ops, in a way that can grow. And fast, cheaply. I know I better understand each part of the "stack" and tradeoffs made along the way.

The site

I'm mostly building websites, so this section is geared towards that. It's also the place with the most latitude here... Rails, Phoenix, and Laravel are big players and pretty full featured. I like the idea of Golang for some of my smaller stuff.

Well known route, server rendered

ruby
rails (active record, active job, solid queue, etc.)
hotwire
omniauth (? for oauth)

Client side rendered

I'd reach for preact or solid if I needed to move fast, but maybe Lit or Svelte if I had a chance to try some new things. I'd only reach for this if I was planning offline functionality a la PWA.

The new hotness -- A Golang stack

I think this would be lightweight and fast. It has lots built into the standard lib, pretty well.

golang - language
cobra - command line tool, so it could do more than serve
viper - command line helper
sqlc/sqlx - start with sqlite
goose/dbmate - language agnostic migrations, with Go API so the app could actually migrate when starting up
SQLite via modernc.org/sqlite, unless I go postgres
backlite - background jobs
htmx? alpine? - some frontend interactivity
chi/stdlib - do I need a http framework? Or can I use the standard library?
templ/stdlib - do I need a templating framework? Or can I use the standard library?
oauth via coreos/go-oidc/v3 + x/oauth2 - so I can put this behind Authelia and not write auth myself.

Well trodden and quick

I could throw this together in an afternoon and have a demo for you. It wouldn't scale as well as the Rails app though and probably wouldn't be as fast the the Golang app

node
express
nunjucks
sqlite

Packaging / deployment

A brand new section for me, I thought it deserved it's own section because it sits somewhere between building the app and the infrastructure it runs on. They have different lifecycles, they deserve different sections but bridging the gap in a way that deployment doesn't have to rely on the app can be a tough problem. It boils down to creating an artifact that your deployment knows how to use. Containers are an easy answer, but for my static sites were actually way overkill. If I were using Kubernetes, that would affect this choice too. But deploying on my own VPS's had me "go native"

Packaging everything up in a native format for my VPS makes it easier to just copy over and run install from the infra side. Out of band secret management is a different story, it has its own section below.

buildah - building containers, part of podman the way I use it.
nfpm - building debian packages
tar - if all I need is a tarball

(what, I said native but I'm building containers??? See the podman item under infra)

The infra

A completely revamped section. I've felt mostly comfortable deploying to my own machine for a while now. Either with Kamal or some bash scripts. But Kamal was a little too constraining and my bash scripts never felt very polished. Recently, I've dropped Kamal but it could come back.

OpenTofu - provisioning infrastructure
cloud-init - getting my basic packages in place
mise tasks - uploading/deploying my packages, bash scripts with ways to use flags and envvars effectively.
systemd - process supervisor, much lighter weight than kubernetes or other options, often built in. Capable of running timers to process backups as well.
caddy - used as a reverse proxy for my apps, or serving them directly with a caddy file. can be run directly on the VPS as a systemd service. Allows me to reverse proxy or serve static files as I'd like.
podman - provide a container runtime, running containers as systemd services via quadlets (and their systemd generator).

Secret Management and Sensitive Values

I'm not sure how best I like doing this quite yet. sops is an easy answer for deploying sensitive values. Then age (with ssh) since I'm keeping it low cost for myself. I should probably re-encrypt the sensitive values as part of their deployment. In a case where I was using a KMS it would be a non issue. And a KMS would be an easy sell for business

sops
age
ssh

What Did I Forget?

What about all the things apps need, like a database? high availability? failover? telemetry? auth? uptime monitoring?

Those are great questions. I didn't include them above, the above allows me to more flexibly deploy any and all of these things. Caddy could give me some HA/Failover I think, but doesn't the way I'm using it.

Authelia - oauth provider, I want my users to be able to access all my apps with one log in.
Victoria Metrics - going to try instead of Prometheus
Jaeger
Grafana Loki
Uptime Kuma
Tailscale/Wireguard for secure comms
Zot - container registry, if I need one.
Seaweed FS - if I need an S3 bucket, or I could use Backblaze

There's a lot of Golang services in that list, which is a big part of what has me looking at Go. I'm not sure if it's fortunate or unfortunate that there isn't a big framework in Go, but a lot of the CNCF projects seem to do great in Go without it.

Dev Tools

Very often these posts list dev tools for me. This section hasn't changed very much, but let's list things out again. Commands I run in the course of a day. Apps I use for development.

ghostty
tmux
neovim
batcat
eza
fzf
git
mise
usage
bash
curl
jq

mise has been a huge productivity boost. Along with usage to define flags and envvars and running by default in a known directory are both huge quality of life improvements. I guess I don't need mise for usage, but the combination has been powerful.

From Containers And Back

Mon, 08 Jun 2026 00:00:00 GMT

Ben's Blog - From Containers And Back

From Containers And Back

Jun 8th, 2026 Ben

A month or two ago I revamped my deployment process. I was manually scp'ing files on to a server and I wanted something that felt less fragile than that. I'm familiar with containers so I figured I would build a container! I wrapped up my caddy server and decided to use podman because I thought I was familiar with their quadlets and that would be an easier than something like Kubernetes. That sent me down a whole rabbit hole learning about systemd and socket activation then OpenTofu and sops and age. It turns out I didn't know quadlets very well, but I know them much better now!

TL;DR: infra and apps/sites have different lifecycles; treat them differently. Make sure you can deploy all your apps/sites separately.

I didn't fully appreciate how scp'ing static files to the server gave me separate deployments for free. I didn't have my Caddyfile separated out, so they were still interconnected. But my Caddyfile changed so seldom that it wasn't a big deal.

Deploying a container was a pretty nice artifact to deploy, but I realized then I had to deploy all my sites and services together, the way I had set it up. That was a bad idea, I couldn't leave anything half finished! I needed to be able to deploy them separately again. Four separate deployments meant I couldn't have a single artifact to push up. I needed something in front to coordinate my sites. Something that didn't actually bundle them together so tightly, but each deployment could affect. Enter back in caddy and systemd.

I'm using caddy to front all my other sites/services. This is basically the same way I was doing it before, but this time around I broke the Caddyfile apart. I can have caddy include all the Caddyfiles in a particular directory. Leveraging this, each site can "install" its own caddyfile. If it's a service and shipping a container, maybe that holds a reverse_proxy directive. Maybe it's just some static files with file_server or even uses the templates directive. Caddy can terminate tls and then the sky is the limit! [^1]

I also learned a good deal about packaging. Debian packages are basically a couple of tarballs archived together. They hold a tarball that maps on to your system directory and will place files where they appear. It has a postinstall script (among others) that can do anything, including loading container images or reloading systemd's daemon. A tool like nfpm makes it easy to define how your repo directories map to the tarball. Having a package makes for an easy "handoff" between an site repo and my infra repo. This artifact can affect more of the system it runs on than a container can.

Containers can't describe how they're deployed, so you always need something like this. Podman and systemd via quadlets is a great method for deployment. I can wrap those unit files up in a deb package and podman will pull them! The postinstall script can reload the systemd daemon to make sure they're picked up. Security is only as good as my unit files I guess, but at least I didn't have to hand write the caddy one.

I now have an infrastruture repo with OpenTofu that sets up the caddy server which will front the rest of my sites and podman because I'm sure I'll use a container runtime. Debian packages make it easy to install my sites and other softwares as I need them. Having a separate repo is important because I will very seldomly need to change much about the server, but I want to deploy my sites very often!

I can put all the deployment scripts in the infra repo. That includes scripts for all my sites. The sites build their artifact, the deb package, then I can deploy from the infra repo using a mise task. I looked into Ansible and others but didn't find anythign I liked enough for my very simple scripts, so these are just bash with a slightly nicer handling. This splut should make it easy for me to turn this into GitOps if I ever wanted to. Build the package on a push, then pull from the remote and install. But I don't have any plans to do that just yet.

Lastly, secrets can go right in deployment artifacts. Using sops and age, I can write unit files that decode them on the server in a very ephermeral way. I'm not sure that it's as good as podman secrets, but I'm sure I'll learn how to make it even better in time.

My old stack: caddy, systemd (unwittingly), bash

My new stack: caddy, systemd (knowledgeably), bash, opentofu, mise, podman, nfpm, sops, age, cloud-init

What I lost: nothing, in the end. This was a big knowledge gain and massive deployment improvement

What I gained: the ability to deploy as many sites as I want easily. Knowledge about the Linux Filesystem Hierarchy (FHS). A container runtime on my server. Better secret management

For the time being, this system is flexible enough that I can continue to use my container setup as I migrate my other repos back and break apart that container.

[^1]: The caddy file is really simple: import /etc/caddy/othercaddyfiles/*.caddyfile I can have cloud-init drop it on the new machine

A Weekend With sops and age

Mon, 11 May 2026 00:00:00 GMT

Ben's Blog - A Weekend With sops and age

A Weekend With sops and age

May 11th, 2026 Ben

They seem almost too easy. It's safe to git commit my secrets now? A keyfile can really be that easy to read? I looked into sops and age this weekend and like what I found. I host a little wedding countdown timer for my family weddings. The data isn't super secret, but I also don't need to make it super public. So I've kept it out of version control. I deploy from my own machine, so it just lived there for a while. Then I wrote a script to load it from my password manager.

But sops takes a different approach. As a CNCF Sandbox project donated by Mozilla, it encrypts values in the same structured format you use it in. It keeps the keys in the file so it's easy to see what has changed in a diff. Then, because the values are all encrypted, you can just commit the file to your git repo!

Editing happens with the sops command, which decrypts and opens the file in your editor, then re-encrypts it after closing, pretty snazzy! sops does the structured part, but what keys do you encrypt with? It seems sops integrates with a lot of cloud options, but age caught my eye. It's a single Go binary with short keys and is capable of using ssh keys as well. Public keys can be put in .sops.yaml for sops to load, specifying age with the age key. Then when decrypting, age private keys live in ~/.config/sops/age/keys.txt. All your keys in a simple text file with comments!

The combo really shines when you realize you can encrypt with multiple public keys. I followed parts of this dchost tutorial and want to continue with the systemd stuff too.

Send your coworkers encrypted messages

Github lets you easily download public ssh keys for anyone using https://github.com/.keys. You can download the keys for all of your coworkers then encrypt a message that any of them can descrypt with the ssh key they already use for github! Not a long term solution, maybe, but pretty cool that it's so simple.

echo "secret message" > msg # put secret message in here
mkdir -p keylists/
# can repeat with multiple coworkers
curl -L https://github.com/.keys > keylists/
cat keylists/* | age --encrypt --armor -R - msg > msg.age

Send it in any text channel (Slack? WhatsApp? IRC?) and let them decrypt!

age --decrypt -i ~/.ssh/gh msg.age # will print to terminal

I would print you an example, but I don't know you yet! It's so much simpler than gpg or any other provider I've used. Maybe I'll use it in more places. sops has some other cool features like exec-env and exec-file, which seems like really cool ways to never need to decrypt the file on your machine at all. One less operational worry!

Enjoy explaining both of these names to your coworkers, hopefully they'll be happy using it no matter how they decide to pronounce them.

Running an App Server

Sun, 03 May 2026 00:00:00 GMT

Ben's Blog - Running an App Server

Running an App Server

May 3rd, 2026 Ben

Running an app server isn't enough. Eventually you'll want to automatically restart your app if it crashes. Eventually you'll want to be notified if it crashes. Eventually you'll want to observe how your app is working. Eventually you'll want to tweak settings without restarting your app. Eventually you'll want to gracefully degrade your app when it's stressed, so it crashes less often. Eventually you'll want to backup data that your app is creating. Eventually you'll want two copies of your app to handle more requests (horizontal scaling). Eventually you'll want to expand/contract the number of running app copies. Eventually you'll want better insight on how people are using your app. Eventually one database won't scale vertically fast enough. Eventually you'll want to authenticate a user to your app. Eventually you'll want to tell another service you've done something. Eventually you'll want to know when an outside service has done something. Eventually you'll want your websockets to stay connected through redeploying your app. Eventually you'll want healthchecks because monitoring the process isn't enough.

None of these things are your app but they all work together to make sure your app works. They're all capabilities around the core business logic of your app. I wasn't an engineer during the microservice craze. I've been learning a lot about the graduated and incubating CNCF projects though. There's a lot of work with initiatives like OpenTelemetry and OpenFeature that I wouldn't want to replicate in my app. Authentication is really tough to set up all the features people may want (password, passwordless, MFA, passkey, etc). What if you had a central server you could trust (a la forward auth or OIDC)? Whole companies are built around adding these capabilities to your app. Clerk and Firbase sell auth, Datadog/Grafana/Betterstack/Sentry all sell telemetry. Vercel/Posthog sell feature flagging. If you use any of these services, are you running microservices now? Or is it still a monolith? If you run all those same things yourself -- Jaeger, Prometheus, Keycloak/Authelia, flagd -- are you still building a monolith or microservices?

We all agree a reverse proxy is a good idea for a web server, so you're always going to have at least two services running. Or do you want to build TLS support directly into your app? Then how would you handle load balancing?

I've read DHH's majestic monolith, but I've also seen them release Upright. I've seen them try different auth methods (all standards, but built into their app) and I've seen people always ask for their preferred, portable auth method. You can't make everyone happy, but maybe you don't need to reinvent the wheel either.

I'm not arguing or advocating for a monolith or microservices. I'm not arguing for hosting it all or paying someone else.

If you do decide to run microservices, don't separate your business logic too much. You'll already run a lot more services than you think.

If you decide on a monolith, don't try to do too much. There are many standards out there and many smart people have thought through these problems. There are many self hosted projects or people to pay to take care of something you don't care to implement. Let your app stay focused on your core business.

Whatever you call it, you'll want many of the same parts other people use. Hopefully you'll share something useful or fix something broken, and we can all continue to learn together. Learn the names, they help communicate the concepts. Learn the concepts and their nuances, names can't capture every detail. If they did, we'd all have names as long as Tolkien's Ents. Eventually someone will pay you for your discernment. You can take great pride in it and they don't have to learn about it.

Systemd Socket Activation Tutorial with Caddy and Quadlets

Wed, 29 Apr 2026 00:00:00 GMT

Ben's Blog - Systemd Socket Activation Tutorial with Caddy and Quadlets

Systemd Socket Activation Tutorial with Caddy and Quadlets

Apr 29th, 2026 Ben

I've spent the past couple of days learning about how systemd.socket files work and how they work with a little caddy server. It feels like a bit of a super power, so I wanted to share. I referenced this blog post a lot while writing my own test sockets, it's another great resource.

I'll be using podman quadlets in this tutorial to run the caddy server, but you could run the caddy.service directly if you'd like. So many of these commands need to run as root, I may assume you're the root user, or prepend sudo. Our service should do something you can see, so it will returns good tidings.

Why Socket Activation

More secure, Can run container as unpriviledged user connected to a priviledged port
Faster boot, only the socket starts
Save resources, the server can be shutdown when it isn't in use (called exit-on-idle)

Get the computer ready

Ubuntu 26.04 came out a few days ago and has podman 5.7 in its package repos, so that's a good place to start. With a new machine, run these commands to get podman.

apt update
apt install podman

Write our files

Socket Unit

I'm going to write my files in the home directory of my user, cadusr. First up is a socket file. Names are important, the socket and container file names must match. I'll call this tidings.socket

[Unit]
Description=socket for good tidings
Before=tidings.service

[Socket]
ListenStream=localhost:80
FileDescriptorName=http

[Install]
WantedBy=sockets.target

This socket file describes to systemd what socket it should listen on. The "Before" key tells systemd that tidings.service relies on tidings.socket. Socket units will actually get this by default, but I've put it here to illustrate. The Socket table has the port to listen on and gives it a name. The name sets LISTEN_FDNAMES in the environment with a colon separated list of names given to the sockets. systemd passes these sockets as file descriptors (think stdin, stdout) starting at 3. LISTEN_FDS gives you the number of sockets passed through. The "ListenStream" keyword specifies the type of socket, in our case this will work for http/s communication. The "WantedBy"

Caddyfile

Before we write our container file, let's write the Caddyfile that we will configure caddy with. It likes to be mounted in a directory, not the file directly, so we'll create a caddy directory for it.

mkdir caddy
touch caddy/Caddyfile

http:// {
  bind fd/3
  respond "Good tidings"
}

That's it for the Caddyfile. This tells caddy to listen on http protocol but doesn't give it a port or hostname. We bind "fd/3", or file descriptor 3, as the interface, which we know systemd will provide for us.

Container file

Last, let's set up our caddy container. In a file named tidings.container, write the following:

[Unit]
Description=send good tidings
Requires=tidings.socket
After=network.target

[Container]
Image=docker.io/library/caddy
Volume=/home/cadusr/caddy:/etc/caddy # replace with your own Caddyfile directory
ReloadCmd=/usr/bin/caddy reload --config /etc/caddy/Caddyfile --force

[Service]
User=1000 # replace with output from `id -u` when you aren't root
Group=1000 # replace with output from `id -g` when you aren't root

A Container Unit can be used by systemd because podman has a generator for it to turn it into a systemd service, this is why we can't use docker or another container runtime. Table by table, the Unit table just sets up a description and some dependencies for us. systemd is great at dependency management. The Container table is where we put all our podman related keys. These correspond very closely with the command line values (or docker compose values). Notice I've put a ReloadCmd so we can call systemctl reload tidings.service to reload our caddy file; systemd knows how to do it! We also don't publish any ports, which is unusual for a web service. The socket unit is what listens on the port in this case, caddy just binds to a file descriptor. So the container doesn't need any ports open, or really any network priviledges! Lastly, the Service table. This is forwarded through the podman generator verbatim. In our case, we're going to run our service as the user id 1000 and group id 1000, so our container doesn't run as root.

Installing our unit files

"Installing" the unit files is as simple as copying to the right place and reloading systemd. podman has a fancy quadlet install command that helps us, but I'm not sure it does anything but copy (and maybe verify?) to the right place. Note, both these commands must be run as root. If you run podman quadlet install as your user, it will become a user unit file instead of a system unit file. Then your socket won't be able to find your service and neither of them will work. Even though our container will run as an unpriviledged user, it's still installed as a system unit.

cp tidings.socket /etc/systemd/system
podman quadlet install tidings.container
systemctl daemon-reload

Once we install the file, you can run systemctl cat tidings.service to see the generated service unit.

If you accidently install a bad container unit, sometimes podman will refuse to install a new one or remove the old one. It doesn't give you great feedback unless you run podman quadlet list. In that case, you can just remove it manually from where it was "installed" (copeid) to. rm /etc/conatiners/systemd/tidings.container

Enable our units

Either quadlets or systemd generators don't really need to be enabled, but we definitely want to enable and start the socket. This next command enables the socket (so it starts on boot) and starts it now for us.

systemctl enable --now tidings.socket

Now systemd is listening to port 80 for us! We can hit port 80 on our machine with curl. The first time it will take a moment as the caddy server starts. Subsequent invocations of curl will work much faster!

curl localhost
# should return "Good tidings"

Now we have a socket activated service that will be supervised by systemd! Good work!

Further Usage

More than one port

Most web servers will listen to at least two ports, 80 and 443, so this socket activation wouldn't be very useful if we couldn't bind to more than one port. Fortunately, you can add ListenStream as many times as you want in the socket file. systemd guarantees file descriptor ordering of sockets listed within the same .socket file (it does not guarantee them across socket files, if you had more than one socket file for the same service). If we wrote this socket file:

[Socket]
ListenStream=80
ListenStream=443

then fd/3 would always be port 80 and fd/4 would always be port 443. This is nice because caddy doesn't yet support the names passed through.

You can also listen on specific interfaces. When we set our ListenStream to localhost:80 before, systemd opened a socket that only listened to the localhost (loopback) interface. With just setting the value to 80 like I did above, systemd will listen on all interfaces and your caddy server will be reachable externally to your computer. This is nothing special for caddy, but just know that you aren't losing that here; it's really only that the port is passed to you instead of your service needing to bind it itself.

Running it yourself

We set up unit files and installed them so systemd would handle the lifecycle of our app and make it easy for us to control with typical systemd commands. But systemd also provides a shell command you can run to set up a socket activation.

systemd-socket-activate -l "localhost:80" podman run --volume /home/cadusr/caddy:/etc/caddy docker.io/library/caddy

That command is the equivalent of our unit files from above. This is just for a one off command and a great way to play with socke activation. While the process is running it behaves the exact same way as our unit files. A few options I find very interesting are "accept" and "inetd" which basically make systemd into a web server for cgi-like scripts. You programming language would still need to set up the environment for you, but it's a very simple stdin to stdout interface to talk with the world.

Writing a web service for socket activation

What if you are writing your web app and have it containerized and want it to support socket activation? I don't think I saved the fabulous tutorial I found online about eating lunch. But the basic premise is to check for the LISTEN_FDS environment variable. If it's set, you know you can connect to fd/3, however your programming language expresses that. For node I think this might be as simple as

net.createServer().listen({fd: 3})

although I haven't made a good test for it.

Ubuntu 26.04

Tue, 28 Apr 2026 00:00:00 GMT

Ben's Blog - Ubuntu 26.04

Ubuntu 26.04

Apr 28th, 2026 Ben

Just wanted to celebrate the release of a Ubuntu version that ships with a new enough version of podman to have the quadlets subcommand and the replace flag! podman version 5.7.0

I'm familiar with different types of Linux in general, but I'm most familiar with Debian and Ubuntu. I didn't have trouble getting Fedora set up with podman once I figured out it had what I needed, but it's nice that there are more options now!

Hopefully this makes it easier in general to use quadlets for more people so they will continue to see more adoption.

Moving To Quadlets

Wed, 22 Apr 2026 00:00:00 GMT

Ben's Blog - Moving To Quadlets

Moving To Quadlets

Apr 22nd, 2026 Ben

I moved my website from running caddy as a systemd service to running a container as a systemd service! Otherwise known as Podman Quadlets, podman has a systemd generator that will let you run containers as a systemd service using Unit files that resemble podman run commands (or docker compose yaml) in systemd's ini file syntax.

The result is a container with systemd running as its supervisor. systemd will start the container when the system starts. It can manage the lifecycle and more. You can interact with your container with typical systemd commands.

Motivation

My deployment method was simple, but very bespoke. I had written my original Caddyfile on the server and that was the only place it lived. My deployment system was a bespoke set of scripts for every site/repo I hosted there (four and counting) and it was all tied together by scp and rsync'ing into the right directories. I would have never been able to recreate it. Maybe, given enough time, but the configurations were so scattered and that Caddyfile still only lived on the single server.

That worked great for me. I was barely comfortable with bash at the time, but caddy made it so simple that I was able to get a website up and keep it running for 3+ years this way. I don't want to understate this, it was my beginning on a journey running my own operations.

But it's been three years and that box is out of date. I've become very comfortable with bash and containers. I think containers are really great; their runtimes, like Docker and Podman, offer a standard interface to start them, stop them, and more. A Containerfile (or Dockerfile) is an easy way to write down the configuration in a way that makes it trivially repeatable to build.

I want to have a repeatable build that coordinates across my repos and gives me a single command (or small set) to deploy my website. I still want to deploy it from my local machine. But I want to limit my bespoke bash when I can.

My Decisions

I decided to go super simple with the image and bake everything, including the Caddyfile, into my image. I'm coordinating all the different repos I deploy from by making them submodules of my single deployment repo, this lets me deploy easily from my local machine still and has git handle the coordination between repos.

I now have a bespoke script for setting up a brand new Fedora machine to put the newest version of podman on it. It's still bespoke, but I didn't have a script at all for that before. My deploy script basically just copies files to the remote machine then runs a couple of systemctl and podman commands. Bespoke, technically, but also basically four lines of bash.

With an image ready to be deployed, how do I deploy it? Docker is fine, but podman seems lighter weight. I've been looking at kubernetes for work, and I hear K3s aren't just for Black Friday but I just don't feel comfortable with that yet. I know I need a supervisor to make sure my container keeps running. I used systemd with my old configuration (basically without knowing it).

Podman has done some really cool stuff to bridge a container runtime with kubernetes. They're where I learned what a Pod was and why use one. They can run kube yaml, although I've never tried. And they have this thing called Quadlets that lets you run a declarative configuration under systemd. Their unit files are declarative configuration, like a docker compose file or kube yaml, but in systemd's ini file syntax. Honestly, ini is so super simple to read and write that wasn't a problem. Podman should give me the easiest way to deploy!

Quadlets

Like most of what I learn from Podman, I really misunderstand the concepts involved at first. When I first learned about Pods, I expected them to behave like a docker compose file. I didn't realize all those containers shared a network namespace (plus more, of course). When I first tried to use Quadlets, I didn't realize how much control podman ceded to systemd. Once I run podman quadlet install, I'm basically done with podman. I think that command might even just copy the files to the right place and run systemd daemon-reload. Now, I think podman is providing the generator to turn those Units into Service Units that systemd understands. But having podman is enough, so the quadlet subcommand feels like icing on the cake.

The Trouble

It's all rosy now that you're reading this from a quadlet I have deployed, but getting a version of podman with the right support is tough. You need 5.6 to get the quadlet subcommand at all. And 5.7 to get the --replace flag on the install command, useful for making my deploy scripts simpler. Plus, I couldn't seem to run a container with 5.6 on CentOS Stream. And my local machine is Ubuntu and only has 4.9.3 which doesn't support quadlets at all! Your options seem to be Arch or Fedora. And Digital Ocean only supports Fedora officially. Then you need to install the specific new version of podman from their updates repo because Fedora only ships with 5.6.2.... Trouble and misunderstandings aside, I learned some stuff and quadlets are a fantastic way to run containers.

Future Plans

Socket Activation for my caddy container. Caddy is already really lightweight, but it's a powerful seeming technique I'd like to try.

Rolling deployments. Technically, I've introduced downtime by restarting a container. With socket activation, systemd can hold the connections for me. And podman auto-update will manage starting the new container with a health check then rolling back to the old one if the health check fails. This means I also need to introduce a health check and maybe better tag versions, but neither will be hard if I find the time.

Some dynamic content. Now I can put anything in a container. I could use multiple containers! The sky feels like the limit and I don't have to write a whole new set of scripts for every one. Just small updates to what I have. If I add a site visitor counter, you'll know I've done just that. This was another motivator for me.

Why Not Kamal

I use Kamal for deplying things internally, I've written a bunch about it here. But it uses docker and it has an extra kamal proxy container for rolling deployments. And it's a big local dependency. And it's defaults are very much geared towards a whole web application. It requires a lot more ssh'ing into specific containers to debug. It doesn't have anything like journald.

My biggest issue: Kamal requires a container registry. I'm just not interested in setting one up or paying for one. With podman, I can podman save | ssh podman load to copy my 80 MB image over. It's not terribly efficient, but it's direct and doesn't require any additional infrastructure. Otherwise, I've taken a lot of inspiration from their interface in writing my little bash scripts. I think they're easy to read.

Declarative Configuration, Imperative Interface

Tue, 21 Apr 2026 00:00:00 GMT

Ben's Blog - Declarative Configuration, Imperative Interface

Declarative Configuration, Imperative Interface

Apr 21st, 2026 Ben

Programs that have a declarative interface for their configuration like Kubernetes, Docker Compose, systemd, and OpenTofu are all easier to read through and reason about than their counterparts. Kamal takes a different approach and says commands should be obvious and imperative. Where is that line?

Kamal still has a config file where you declare how to build your container image, where to send it, where your hosts live, and any additional sidecar containers you want. Then it gives you imperative commands to get them there. Once you have Kamal configured, you just call kamal deploy to get a new version of your app deployed.

I can't claim to be a Kubernetes expert (barely a novice), but once you have the configuration done, it seems to me that you just call kubectl -f config.yaml apply which is not as easy English as Kamal's deploy but doesn't it do the same thing? Both get your production service to a new state don't they? Kamal had to roll their own proxy to get rolling, zero-downtime releases, so now they're doing multi-container management. Kubernetes does that too, but has a lot of options and contributors for your use.

A big difference I see is that Kubernetes seems to guarantee an eventual consistency with the applied state through their operator pattern whereas Kamal has the new state up and running by the time the command finishes (or errors, and it rolls back). And, of course, K8s are a beast to run. But K3s seem easier to run yourself.

Both of these systems are way better than a bunch of shell scripts. Maybe better than Ansible too, I don't have any experience there but that yaml scares me insofar as it reminds me of GitHub Actions. In both, you can declare things about the state of your system in a configuration file then both give you a standard set of commands for interacting with what's been created with that configuration. I'm currently in the process of moving from shell script deployments for this static site to containerizing it and running it with Podman Quadlets.

Systemd gets a special mention here because I've been playing with Podman Quadlets. I've found their unit files and systemctl to work a very similar way. Declarative configuration with imperative commands. There are differences: INI syntax instead of yaml, containers running as processes, and it's much closer to the UNIX system it comes from overall. But you can declare dependencies and start/reload commands that systemd then knows how to run with its standard interface. The same way Kubernetes and Kamal seem to work. It can do rolling releases and health checks. Has a decent structured logging interface out of the gate, and doesn't require the overhead of a Kubernetes cluster.

I'm writing a follow up post about my experience setting up Quadlets. It's been a little bumpy, but I really like the place they fit in. Systemd can be controversial, but I think it's here to stay. It's more standard than Kamal and less heavy than Kubernetes. The declarative nature of those Unit files reminds me so much of Docker Compose (which I have plenty of experience in, especially comapred to kube yaml). And that declarative nature gives me something much easier to read and is more repeatable to deploy than the shell scripts I had been using. I could set up the system from scratch by uploading a Container Unit and image to any server running systemd and podman (5.8+). That setup still has some shell scripts for now, but it's a step in a direction I'm very happy with (and I can still build it on my own computer!).

Migrating from Jekyll to WebOrigami

Thu, 09 Apr 2026 00:00:00 GMT

Ben's Blog - Migrating from Jekyll to WebOrigami

Migrating from Jekyll to WebOrigami

Apr 9th, 2026 Ben

They have slightly different philosophies. WebOrgami is much more direct, while Jekyll has layers of configuration. WebOrigami is very attached to file extensions while Jekyll's are all wrong (markdown and liquid in html or md??)

What I've ended with is spiritually something in between Jekyll and WebOrigami. But because WebOrigami is so flexible, it's all written in it! I wasn't rely much on Jekyll, really, so this process took me a few hours over the course of a week or two. These steps are ordered in the way I wish I would have done it.

First step, change all the filenames. I haven't found a better way than to just rename then on the system. Everything became .liquid so I could use a file loader for it.

Second, adapt Jan's Liquid handler. I've made it load much closer to what Jekyll expects, and return an object with the front matter too. My loader creates all context for the Liquid rendering, renders that, then gives me back the document with its front matter. The document's body might be markdown or html, but the handler doesn't care. For the markdown files, I manually call Origami.mdHtml later on.

Writing the Liquid Handler was probably the most difficult part for me. I think the intention might be that a loader is able to turn an arbitrary file into a function that returns something you can post on the web. I'm not sure, but all the loaders I've seen do that. I think mine still works well within WebOrigami's system because it returns a tree like many of the examples on their site. Jekyll builds a lot of context for you, I had to move that to the handler. I definitely took some shortcuts. My blog was 3 layers deep at its thickest and I think I relied on a small subset of what Jekyll really provides. All the special Jekyll tags I use needed to be added to the Liquid rendering engine, but I only used post_url . Since I've created my own post hierarchy now, I just interpolated it directly there, half a step from hard coded. Returning a tree from the handler instead of text only was my biggest enabler. Once I had the posts' front matter available to me in my site.ori file, I could do many more interesting transformations on the data.

Including, moving metadata into front matter. This was part of making the blogging system my own. I don't like the naming convention required by Jekyll. Instead of recreating it in WebOrigami, I added title and date properties into the front matter. I didn't taken the time to make the URLs match, sorry about that lapse of judgement. Since I made the file handler return the front matter to me, I have all the metadata I want, and WebOrigami makes the transformations easy. I'm not sure if I'll use Obsidian or Sveltia to write these eventually, but the front matter should be easy to add in both.

Lastly, porting all the other Jekyll extensions and add ons. I really only relied on the feed_xml for an RSS feed. WebOrigami uses a JSON Feed to RSS converter and has a very nice tutorial on how to create a JSON Feed. Now I have both!

Future Plans

I can do so much more with this now. I never learned Jekyll's tagging system, I didn't take the time when I had so few blog posts and committed to only blogging on tech subjects. But now I can build that myself, and it can be as lightweight as I want. With WebOrigami easily traversing the file system and yaml and any sort of tree, I don't expect it will be that hard.

I've changed the file names on my posts, which is a decision I made thinking not too many people actually come to my site. Eventually, they will probably change again. I'd like to allow them to be organized by year and maybe month.

This is what it looks like, with a single .ori file. Two if you count the configuration.

Overall, I've had a fun experience with WebOrigami. It's being actively worked on and you can read all the comics to learn more about it. They have a great community to chat with. The Tree mechanism is really an incredible one!

Tailnet Zero-Downtime Deployments

Wed, 04 Mar 2026 00:00:00 GMT

Ben's Blog - Tailnet Zero-Downtime Deployments

Tailnet Zero-Downtime Deployments

Mar 4th, 2026 ben

Tailscale is amazing for enabling private mesh network overlays. For connecting your phone to a server you having running at home, easily and securely. If you're building things you want to deploy on your tailnet, what's the best way to do that?

I want everything to run on my own hardware, minimizing my costs and letting me use what I already have. Tailscale lets me talk with my computers easily. Kamal lets me deploy from my local machine with ease and zero downtime (my wife will never know!). Tailscale's Serve feature work great with Kamal Proxy's accessory setup.

Kamal has one onerous requirement, it requires a container registry. This registry has to be available from your laptop and server. If you use an external service, like GitHub's Artifact Repository or Digital Ocean's container registry, then you should be good to go. If you, like me, want to also run your own container registry on your tailnet, I wrote another article about that.

How it works

Using a ephermeral tailscale auth key, Tailscale will route traffic on our network to the accessory tailscale container that Kamal deploys for us. We use docker's dns routing to point Tailscale's Serve feature to the kamal-proxy container that Kamal deploys. Kamal's proxy will check the hostname for us then route to the application container for our app. Because we're deploying behind kamal-proxy, Kamal will handle zero downtime deploys for us, no configuration needed!

Limitations

Kamal proxy routes via the hostname for you, so you can't access these services via the IP address.

Deploy more services

Kamal Proxy can handle multiple apps deployed to the same server. We register a different tailscale sidecar for each one to make our deployments simpler and each service can have it's own identifier in our Tailscale Admin Dashboard. Requests to both services will run through the same kamal proxy container, who will route it properly via hostname.

Appendix A: Configuration

# excerpts from my deploy.yml for Kamal

# my server is on tailscale as well
servers:
  web:
    -  name>. name>.ts.net

# To connect with Zot on my tailnet
build:
  driver: docker

# tell the proxy my tailscale hostname
proxy:
  # tailscale terminates the ssl connection
  ssl: false
  # same hostname as the tailscale sidecar
  host:  name>. name>.ts.net
  # rails port number
  app_port: 3000
  # rails takes a long time to boot on my little server...
  healthcheck:
    path: /up
    interval: 5
    timeout: 600
  run:
    # don't publish ports to the host machine,
    # all the traffic will come through the docker network
    # via the tailscale accessory
    publish: false

accessories:
  sidecar:
    image: ghcr.io/tailscale/tailscale:stable
    # for kamal, the host to run this sidecar on, same as servers.web configuration
    host:  name>. name>.ts.net
    files:
      # I don't think directories works the way I way, so
      # copy and mount the file directly.
      - config/tailscale/ts.json:/config/ts.json
    env:
      clear:
        TS_USERSPACE: false
        TS_STATE_DIR: /var/lib/tailscale
        TS_SERVE_CONFIG: /config/ts.json
        TS_EXTRA_ARGS: --advertise-tags=tag:container
      secret:
        # loaded with .kamal/secrets
        - TS_AUTHKEY
    options:
      # must be the same as the proxy's service name so tailscale and kamal proxy agree
      hostname:  name>
      cap-add: NET_ADMIN
      device: /dev/net/tun:/dev/net/tun
      # derive the volume from the service name so we can have multiple tailscale sidecars on the same server
      volume:  name>-tailscale-state:/var/lib/tailscale

Container Registry for Kamal, Secured with Tailscale

Mon, 02 Mar 2026 00:00:00 GMT

Ben's Blog - Container Registry for Kamal, Secured with Tailscale

Container Registry for Kamal, Secured with Tailscale

Mar 2nd, 2026 ben

I think this is a niche confluence of technologies. Hopefully my experience can help someone else who's trying to deploy services with Kamal, all while behind a Tailnet. This enables you to use your own hardware, secure in your Tailnet, to deploy easily and zero downtime with Kamal.

Since I'm only deploying personal web apps/containers with this setup, I tend to think of it as pretty ephemeral, but if you take the time with this (and maybe have a mirror), Zot is capable of being a complete container registry for docker images and any OCI Artifacts.

Setting up Zot

Zot has pretty good docs, and it's pretty simple to setup too. We're going to put it behind Tailscale, so if we're a little lenient with some of the security options we should still be safe. Some of this is not best practices. At best, these are okay for a homelab setup when nothing is exposed to the internet.

In Appendix A, I have a bunch of configuration files to help get you started. Run the compose on any docker instance you want to use as your registry server. The server doesn't need to be on your tailnet because we'll put the registry on it directly.

Kamal requires a password be set for a registry it accesses through HTTPS, so you will need to setup a password to use in Zot.

Configure Kamal

You only need to set up Zot once, but Kamal you'll configure for every project you want to deploy. I wrote another article that goes into more detail about the Kamal configuration for deploying on a Tailnet.

In Kamal's deploy.yml file, the builder section must contain "driver: docker". The docker driver has access to your machine's DNS configuration, but Kamal's default "docker-container" does not. I think this might change eventually, but I'm not sure. If you're using a registry that doesn't need Tailscale's DNS to work, don't worry about this setting.

I haven't used a remote builder. I imagine it will need access to your Tailnet as well, to upload the built image. I think the docker driver limits the architectures we can build an image for, so remote might be important if your laptop and server have different architectures.

Appendix A: Zot Configuration Files

# example compose.yml with tailscale
name: registry
volumes:
  registry-tailscale-state:
  zot-data:
services:
  sidecar:
    image: ghcr.io/tailscale/tailscale:stable
    hostname: registry
    cap_add:
      - NET_ADMIN
    volumes:
      - registry-tailscale-state:/var/lib/tailscale
      - /path/to/configuration/directory:/config # holds the ts.json, below
    devices:
      - /dev/net/tun:/dev/net/tun
    env_file: stack.env # put all the tailscale environment variables here
  app:
    image: ghcr.io/project-zot/zot:latest
    depends_on: 
      - sidecar
    volumes:
      # zot configuration
      - /share/Docker/stack-configs/ocireg/config.yaml:/etc/zot/config.yaml
      # users and passwords
      - /share/Docker/stack-configs/ocireg/htpasswd:/etc/zot/htpasswd
      # where our images will be stored
      - zot-data:/data/zot
    command: serve /etc/zot/config.yaml

Example ts.json, Serve Functionality

{
  "TCP": {
    "443": {
      "HTTPS": true
    }
  },
  "Web": {
    "${TS_CERT_DOMAIN}:443": {
      "Handlers": {
        "/": {
          "Proxy": "http://app:8080"
        }
      }
    }
  },
  "AllowFunnel": {
    "${TS_CERT_DOMAIN}:443": false
  }
}

# example Zot configuration, config.yaml
distSpecVersion: 1.0.1
storage:
  rootDirectory: /data/zot
http:
  address: 0.0.0.0
  port: 8080
  auth:
    htpasswd:
      path: "/etc/zot/htpasswd"
  # accessControl:
  #   repositories:
  #     **:
  #       defaultPolicy:
  #         - read
  #         - create
  #         - update
  #         - delete
extensions:
  ui:
    enable: true
  search:
    enable: true

What Bash Does Better

Thu, 19 Feb 2026 00:00:00 GMT

Ben's Blog - What Bash Does Better

What Bash Does Better

Feb 19th, 2026 Ben

Bash is eschewed online for being hard to read and write. Depending on who you listen to, you should reach for something else anytime you need something longer than what fits in your terminal. But I've been having a great time writing bash scripts. They are at least twice concise as my boss's equivalent javascript scripts, measuring objectively on lines of code and subjectively on how many lines I have to read to understand what a piece does.

There are some niceties that I like to set up for myself. For example, the die function gives me an easy way to write checks

die() {
  echo "$@" >&2
  exit 1
}

[[ "$(git rev-parse --is-in-work-tree 2>/dev/null)" == "true" ]] || die "Not in git repo"

I often need to look up the string manipulations, but it's so simple to read them.

VERBOSE="${VERBOSE:-false}" # set VERBOSE to false if it is unset or null.

Bash's real super power over a traditional language is the input and output flexibility. Its control flow is second-to-none. The mechanism is super, super simple, strings all around really. But streams are the default, and they are powerful.

while read -r line; do
 # run a command every time a notification is sent.
done < <(curl -sN https://ntfy.sh/test/json)

The thing on the last line there looks a little weird, doesn't it? < <(command) is another super power of bash. How commands can be called. You can treat a file as a string, a string as a file, open a named pipe on your system for inter process communication, inline a script in another language, and more! Bash takes it all in stride. The only thing I've seen recently that comes close is WebOrigami.

A=3 B=3 node -e "console.log(Number(process.env.A) + Number(process.env.B))" # 6
# heredoc
cat <<EOF
This is a long
 inline string with
 enters, spaces and everything!
EOF

# herestring
json='{"this": "Test", "hello": ["sun", "moon", "world"]}'
hello="$(jq -n '.hello[2]' <<<"$line")"

I can even control the process forking of my command with ease. () for a subshell, $() for a subshell, piping stdout bach to me. <() for a subshell, giving me back a file descriptor for it. Functions run in my process automatically, but I can run them in a subshell if I want. Commands may run in a subshell automatically, but I other scripts I can source and run in my process instead.

Lastly, its simple I/O mechanisms are available in every language and it can call any executable on your system with ease, by name. I consider jq part of my basic toolset nowadays. And gum a close second. They're installed on my system, I don't need to import them every time. I wrote a parseargs package because I didn't like the current options and know Node well, now I can call that easily as well! Eventually I'll rewrite it in Zig to be faster, but my scripts won't need to change at all.

The importing is a double edged sword, I know. It's a reason to limit the amount of dependencies I use, luckily bash has a lot of good already in it! But some dependencies are worth convincing other people to use. I trust my taste here and so do my colleagues, but sometimes I will write helpers that don't require others to have packages installed that I do.

log() {
  if command -v gum &>/dev/null; then
    gum log --structured --level info "$@"
  else
    echo "$@"
  fi
}

There's some syntax to learn with bash. It's probably somewhere between Ruby and Perl in that. There's no one place to go and learn about it. You probably only use it for quick, one off scripts and don't fire your whole engineering brain making it robust. But read enough tips and tricks, try new things each time, and I think you'll find yourself reaching for it more and more often given that you can find it almost everywhere and it is amazingly expressive.

Don't Underestimate a CTE

Thu, 12 Feb 2026 00:00:00 GMT

Ben's Blog - Don't Underestimate a CTE

Don't Underestimate a CTE

Feb 12th, 2026 Ben

CTEs are a powerful tool for making your SQL more legible. They also help me model my data and iterate quickly before materializing the final shape of a table, without mucking about modifying a table shape.

The Problem

My wife wants to know when she'll work a certain number of hours so she can take an exam. There's a projection forward, but I also want to take into account days/hours she's already worked and days that are out of the norm.

The Start

I could make one table with entries for all her hours worked, but then I need to track in that table which are a projection and which are "real". Thinking myself clever, I decided the distinction warranted two tables. One for simple entries of hours worked and one to hold all the projections.

How do I fill in all those projection dates? I came up with a simple algorithm that basically takes all the week days and gives her 8 hours a day. I used a CTE to come up with this, then I was going to insert them into projections and go from there.

The Iteration

I made a table expression to insert data into a real table. But why not just use that expression in my calculation directly? If I have a algorithmic projection, what parameters could I change that would cause the calculation to update? Those parameters are what I want to store in a table!

If she's works part time, I can tune that parameter directly instead of trying to reconcile what's in the table with the new data I want. The SQL CTE will just recalculate it for me.

CTEs are super nice to iterate quickly, since there's nothing stored to clean up. DBeaver has a nice concept of variables I used to help me decide what parameters should be part of my configuration. What I put in the DBeaver variables become columns in the table directly.

The Solution and Next Steps

Now that I have a more stable idea of what I want, the next step is materializing it in the database. A View for my projection and a Table for my configuration. Both make the query a little more complicated, since now I have to get the configuration from a new table. But both will help make my final calculation, when will my wife hit her testing hours, easier. And we can tweak parameters until we've run through all the scenarios we want. Even generating a little rails app where she could tweak the parameters herself without wading through SQL code shouldn't be too hard. If I need to change the projection, I can change the view. If we need more parameters, I can tweak the table.

It wasn't my initial design, but CTEs helped me find my way to a more powerful solution.

A List of DSLs for a Website

Fri, 07 Nov 2025 00:00:00 GMT

Ben's Blog - A List of DSLs for a Website

A List of DSLs for a Website

Nov 7th, 2025 Ben

The most basic form of a website needs ~4 or 5 languages.

written after reading this article

HTML
CSS
Javascript
SQL
backend language

3 are required to use the browser most effectively. 1 is required for solid data management. The last one is the only one we really get to choose. Even if we chose Javascript, I could agree it's 5 languages: Node and other runtimes are very close but ultimately different environments for the same language and they should be treated differently.

In a production Node application, with a React frontend, we could easily double that count.

HTML
JSX
CSS
Panda CSS
React
Javascript/Typescript/Node
SQL
Prisma
Lua

9 languages! 6 or 7 DSLs! Some are over top of others, but you write better JSX if you understand HTML better. Same for Panda and CSS, Prisma and SQL. For every DSL layer on top of a DSL doesn't abstract it away as much as you'd think.

What makes a DSL?

Would any templating language be considered a DSL? Something like Liquid or Nunjucks? They're such simpler abstractions than JSX/React, you really get the semantics of the underlying DSL much, much more clearly. There's hardly even another layer to think about. Ultimately they do require a little more knowledge, but they also don't really know anything about the HTML layer beneath them. They could be used to template Javascript or SQL the exact same way.

More advanced templaters like ERB (with Rails) or Laravel's Blade definitely feel like they spill over into DSL land. They start to feel more aware of the langauge they're abstracting. Since they ultimately render down to HTML though, they're still better at separating what they do vs the templated code than a React/JSX that tries to mix the two and bring a runtime into the mix.

Do we gain enough through the abstraction, the additional DSL, to justify it?

Each person and group can decide for themselves and has a different tolerance for then. 10-15 years ago, React, SASS, etc. smoothed a lot of rough edges on the DSLs that make up web pages. But the platform has come a long way since then. For me, I prefer working with the DSLs directly and dropping into the full Javascript language when needed over just smoothing edges that aren't rough or pointy anymore.

A Weekend With Caddy

Sun, 20 Jul 2025 00:00:00 GMT

Ben's Blog - A Weekend With Caddy

A Weekend With Caddy

Jul 20th, 2025 Ben

I've been dabbling with Caddy web server. It's the easiest reverse proxy I've found for self signed development certs. I set up a Caddy server to run my personal blog, a static website. This weekend, I took it a step further and used some caddy templating to make a mostly static site dynamic. The outcome? Every single one of these projects has felt like a magical experience. In this post, I focus on this past weekend when I used some caddy templating to make a mostly static site dynamic.

I host a countdown timer for various friends and family's weddings. Previously, it was an entirely static site I made for my own wedding, hosted on Github Pages. Then I changed it for the next wedding. But then I couldn't see how long I had been married for!

I needed the barest amount of dynamic content on my page. I didn't want to ship everybody's wedding dates to the client, so it needed to happen server side. I make web apps (React, et al) for a living but that was just way too much (effort, code, time, etc) for what should be a simple problem, one interpolated date!

I had been testing Caddy to host my personal blog, a static website. It's been performing phenomenally, I'm able to deploy faster to it (via rsync) than to SourceHut Pages most of the time. I had recently come across the Caddy templates module. For my blog, I was resistant to becoming too dependent on a feature like that, in case I needed to switch servers or something. But the concept was the exact right amount of complexity for my wedding countdown timer project.

It took me a few hours to adapt my static site: loading a json file server side then interpolating the date into my timer-element web component and deploying the changes on my public facing web server (adapting the Caddyfile I had there to host two sites at the same time!). But the end result? I'm very impressed! I was able to add a bunch more weddings to my site by adding lines to the json file. Everyone I texted about it was happy to see the counters to their weddings! It will last as long as Caddy does, I didn't need to introduce or maintain any other moving parts.

For the future, I'm exploring templating via a CGI script. It's slightly more work, but much more server agnostic. Luckily, caddy has a third party module to support CGI and an amazing build tool, xcaddy, to produce supporting binaries. We'll see where my ideas take me, but I know I'll be using Caddy for a lot in the future! Thank you Matt Holt for the amazing project!

Tailscale Sidecar Run Deep Dive

Thu, 10 Jul 2025 00:00:00 GMT

Ben's Blog - Tailscale Sidecar Run Deep Dive

Tailscale Sidecar Run Deep Dive

Jul 10th, 2025 Ben

From my other post , we have a tailscale container running alongside another container. It's not a long file, but there is a lot of configuration going on. In this post, I'm going to step through the run script line by line.

Full File

First, the full file for reference

#!/usr/bin/env bash

# load our environment variables
source .env

# run our sidecar container
podman run --detach \
  --hostname "$HOSTNAME" \
  --name "$SIDECAR_NAME"\
  --cap-add net_admin \
  --device /dev/net/tun:/dev/net/tun \
  --volume freshrss_tailscale_state:/var/lib/tailscale \
  --env-file .ts.env \
  ghcr.io/tailscale/tailscale:latest

# run our FreshRSS service
podman run --detach \
  --restart unless-stopped \
  --log-opt max-size=10m \
  --network container:"$SIDECAR_NAME" \
  -e TZ=America/New_York \
  -e 'CRON_MIN=1,31' \
  -v freshrss_data:/var/www/FreshRSS/data \
  -v freshrss_extensions:/var/www/FreshRSS/extensions \
  --name "$CONTAINER_NAME" \
  docker.io/freshrss/freshrss

Line by Line

Bash setup

The first few lines are just bash setup.

#!/usr/bin/env bash : run this script through the bash interpreter. After making the script executable[^chmod], this tells our computer how to run it.

source .env : We set up a .env file with bash variables[^variables] inside. The source command loads those variables into our current process. We could put any bash in there, but by convention we're only setting variables.

Tailscale Sidecar Container

podman run --detach \
  --hostname "$HOSTNAME" \
  --name "$SIDECAR_NAME"\
  --cap-add net_admin \
  --device /dev/net/tun:/dev/net/tun \
  --volume freshrss_tailscale_state:/var/lib/tailscale \
  --env-file .ts.env \
  ghcr.io/tailscale/tailscale:latest

podman run --detach : tell our container engine, podman, to run a container detached so we aren't connected to it's stdout

--hostname "$HOSTNAME" : set the hostname for the container. Tailscale uses this as the machine name. We're using the HOSTNAME variable we set in our .env, which makes it easy to share between scripts

--name "$SIDECAR_NAME" : give the container a name. We reference this in our service container, so we've made it a variable to ensure it has the same value both places.

--cap-add net_admin : add the net_admin capability to the linux container. This gives the container some priviledges. Tailscale needs it to do some of its networking.

--device /dev/net/tun:/dev/net/tun : give Tailscale access to the tun device so it can network effectively.

--volume freshrss_tailscale_state:/var/lib/tailscale : save the Tailscale state into a volume named "freshrss_tailscale_state". /var/lib/tailscale is where the information needed for Tailscale to remember this device, so we can teardown and recreate this container at will. This state directory is set with TS_STATE_DIR, which we set in the .ts.env and is loaded by the next line.

--env-file .ts.env : this is the file the holds the environment variables this Tailscale container needs to authenticate and store state in the correct place. env-file is a nice alternative to setting envvars individually, like we do with FreshRSS. It can keep secrets, like our oauth token, out of git (don't commit your .ts.env file!) and collects all the envvars we need into one place. In fact, we could do this same thing with FreshRSS if we wanted or our configuration got more complex!

ghcr.io/tailscale/tailscale:latest : tells podman which container image to run, "ghcr.io/tailscale/tailscale," and which version, the "latest" tag. We rely on the command from the Dockerfile this container image was built with to automatically start Tailscale, so we don't need to specify anything else! ghcr.io is GitHub's container registry, so we know that's where tailscale hosts it!

FreshRSS Container

FreshRSS is our main service in the example, but it could be any container you want to run on your tailnet.

# run our FreshRSS service
podman run --detach \
  --restart unless-stopped \
  --log-opt max-size=10m \
  --network container:"$SIDECAR_NAME" \
  -e TZ=America/New_York \
  -e 'CRON_MIN=1,31' \
  -v freshrss_data:/var/www/FreshRSS/data \
  -v freshrss_extensions:/var/www/FreshRSS/extensions \
  --name "$CONTAINER_NAME" \
  docker.io/freshrss/freshrss

podman run --detach : run this container in detached mode too

--restart unless-stopped : set the restart policy for the container. unless-stopped will always try to restart the container unless we explicitly run stop to stop the container. Not really necessary here, since the tailscale sidecar won't restart this way. But we could have that too if we wanted.

--log-opt max-size=10m : freshrss suggests this setting. It sets the max size of the log file. More info

--network continaer:"SIDECAR_NAME" : this line does the tailscale magic. It makes the tailscale conatiner (with name $SIDECAR_NAME) the networking stack for this container, so our tailscale sidecar can connect to tailscale and talk to the service within this container. We've parameterized the name of the tailscale sidecar container so we know we're using the right one!

-e TZ=America/New_York : sets an environment variable inside the container. In this case, FreshRSS uses the TZ variable to set timezone information, so I've set it to the US East Coast.

-e 'CRON_MIN=1,31 : another environment variable. This one FreshRSS uses to set when to run a cronjob and update feeds. It's wrapped in single quotes so we can be sure our shell sends those exact characters through, instead of expanding it somehow.

-v freshrss_data:/var/www/FreshRSS/data : mount a volume in the container. A volume is a place we can store things to persist even when the container has been destroyed. In this case, we're binding to the directory FreshRSS uses to store its data.

-v freshrss_extensions:/var/www/FreshRSS/extensions : mount another volume into the container. This is the directory FreshRSS uses to save extensions if we load any.

--name "$CONTAINER_NAME" : set the name of the container to the value we stored in $CONTAINER_NAME in our .env file. This makes it much easier to find this container when we run podman ps

docker.io/freshrss/freshrss : the name of the container to run. Note the docker.io on the front here; docker sets this by default if you don't use it. Other container engines require the full uri (but have settings where you can set defaults).

Wrap Up

That's the entire file, line by line! Of course you can read all about all these options and more in the docs but hopefully this was a nice little tutorial of all of them in plain English for you. Container engines have a lot of options and the best way to learn is by practice.

Like a pod of seals, float on!

[^chmod]: chmod +x run [^variables]: key="value" pairs, where the quotes help in case there's space!

Tailscale Sidecar Tutorial

Mon, 07 Jul 2025 00:00:00 GMT

Ben's Blog - Tailscale Sidecar Tutorial

Tailscale Sidecar Tutorial

Jul 7th, 2025 Ben

Adding Tailscale to your self hosted containers lets you easily set up those services with a secure, fully qualified domain name. It is easy to remember and easy to set up. Tailscale has their own Docker docs, but I want to expand on that starting point and use a different container engine.

There's a lot to Tailscale that facilitates this magic. First, the Tailnet name means you can give each container a name. It's easy to identify on the Tailscale Dashboard, it's easy to type into a URL bar, it's as easy to use as any URL! Second, OAuth tokens make it simple to connect containers (not just machines!) into your Tailnet. Third, HTTPS certificates mean web services behave like you would expect. They look secure in the browser and have access to secure context APIs. Lastly, Tailscale Serve proxies you to the correct port in your container.

Those services together make the experience pretty seamless to connect, once you know how all those pieces fit together. This post will walk you through all the steps you need to set this up today. We'll be using FreshRSS as the service we're proxying. I'm not going to use docker compose. Instead, I'll be using podman and a handful of bash scripts to connect our containers together. This way, the tutorial will be a little more generic and should work for any oci compliant engine (docker, podman, nerdctl, etc).

Prerequisites

Have a Tailscale account.
Have a computer on your Tailnet.
Have a container engine installed. Podman, docker, and nerdctl should all work interchangably, but I'll use podman for this tutorial
A project directory on your computer. Something like ~/services/freshrss-sidecar would be great. All files and folders will be created in this directory.
Some kind of text editor.
A Linux/Mac computer -- not a requirement, but all my commands will be for Unix-y operating systems.

Tutorial

Pull the container images

If you skip this step, podman will pull these the first time we run the container. Either way is fine!

# pull tailscale
podman pull ghcr.io/tailscale/tailscale:latest
# pull freshrss
podman pull docker.io/freshrss/freshrss:latest

Set up some environment variables

This .env file will hold a few configuration variables we can share across our bash scripts. You can parameterize more or less, but this is a good start. HOSTNAME is how we'll reference it on our tailnet at the end.

# file: .env
SIDECAR_NAME="freshrss_tailscale"
CONTAINER_NAME="freshrss"
HOSTNAME="rss"

Next, create a .ts.env file. This one will hold all the environment variables our tailscale sidecar container needs to connect to our tailnet. We can fill in everything in this file but our TS_AUTHKEY argument. We'll generate that shortly.

# file: .ts.env
TS_AUTHKEY=tskey-client-notareal-tailscaleoauthtoken
TS_EXTRA_ARGS=--advertise-tags=tag:container
TS_STATE_DIR=/var/lib/tailscale
TS_USERSPACE=false
TS_SERVE_CONFIG=/config/ts.json

Pick a Tailscale Tailnet Name

In your Tailscale dashboard, go to DNS and find your Tailnet name. Tailscale uses yak-bebop as their example. You can't pick the one you want (only generate it), and you also can't change it once you turn on HTTPS. So take some time to generate one that you like. I like a fun name, but you can pick the default too!

We can make most of this tutorial work without HTTPS, so we won't turn it on until the end.

Generate an OAuth client

An [OAuth client] gives you a more secure way to connect to your tailnet versus and Auth Key. Before we can generate the token, we need a tag to give our container. The official docs give a good reference for defining a tag. My short version: go to Tailscale Access Controls tab and add an entry under the tagOwner key named tag:container:

"tagOwners": {
  "tag:container": ["autogroup:admin"],
},

Save that with the button beneath and now we have a group we can assign the OAuth token to. So head over to your Tailscale Settings page, the "OAuth clients" option along the sidebar and click the "Generate OAuth Client" button. Type a description like "FreshRSS Test Token" and make sure you give it the "Devices:Core" and "Keys:Auth Keys" write permissions. Make sure you have the tag:container that we just created chosen under the "Add tag" dropdown. It should automatically assign to the second permission if you've set it for the first one.

Remember, "Devices:Core" and "Keys:Auth Keys" write permissions, assigned to your new tag, tag:container!

Click "Generate Client" and copy the key it gives you into your .ts.env file. You'll never see this key again, but if you lose it just delete this one and regenerate a new one. The TS_AUTHKEY line should now have your auth token in place of our previous placeholder, giving you a file that looks like:

TS_AUTHKEY=tskey-client-yournew-tailscaleoauthtoken
TS_EXTRA_ARGS=--advertise-tags=tag:container
TS_STATE_DIR=/var/lib/tailscale
TS_USERSPACE=false
TS_SERVE_CONFIG=/config/ts.json

Running our Container

Now we have everything we need to run our container and access it over http. We need two containers, so we'll write a short script to help coordinate it. I call it run, to mimic the podman run command. It will create 3 volumes, use the images we pulled in the first step, and our .env and .ts.env files to load everything up.

#!/usr/bin/env bash

# load our environment variables
source .env

# run our sidecar container
podman run --detach \
  --hostname "$HOSTNAME" \
  --name "$SIDECAR_NAME"\
  --cap-add net_admin \
  --device /dev/net/tun:/dev/net/tun \
  --volume freshrss_tailscale_state:/var/lib/tailscale \
  --env-file .ts.env \
  ghcr.io/tailscale/tailscale:latest

# run our FreshRSS service
podman run --detach \
  --restart unless-stopped \
  --log-opt max-size=10m \
  --network container:"$SIDECAR_NAME" \
  -e TZ=America/New_York \
  -e 'CRON_MIN=1,31' \
  -v freshrss_data:/var/www/FreshRSS/data \
  -v freshrss_extensions:/var/www/FreshRSS/extensions \
  --name "$CONTAINER_NAME" \
  docker.io/freshrss/freshrss

Make the file executable by running chmod +x run, the run the script with ./run. Or you can call bash run and not need to run the chmod command.

Shortly, we should see a "machine" with the tag:container under our Tailscale Dashboard's machine tab called "rss".

Navigate a web browser to http://rss.${tailnet-name}.ts.net (eg, http://rss.yak-bebop.ts.net) from your tailnet connected computer and you should see the FreshRSS welcome page! Because we don't have https certificates working anyway, you could use http://rss to go to the same site, but the short names don't work with HTTPS certs so stick with the longer version.

You could be done at this point, but Tailscale Serve ensures you can work with many different container ports and HTTPS Certs will make your experience much better in a modern browser.

Tailscale Serve Config

This is the last configuration we need, Tailscale Serve. Tailscale won't provision a TLS cert for us without this. And the config will tell tailscale what port to proxy to, so we don't need to type that into our browser either. We didn't need a port number with FreshRSS because it exposes itself on the correct port, port 80. But for most services we'll want this set up. And 80 is the wrong port for https (that's port 443). Make a config directory with ts.json in it, to mount to our tailscale sidecar container. Under the Proxy key is where you would set the port for your service; FreshRSS is on port 80.

{
  "TCP": {
    "443": {
      "HTTPS": true
    }
  },
  "Web": {
    "${TS_CERT_DOMAIN}:443": {
      "Handlers": {
        "/": {
          "Proxy": "http://127.0.0.1:80"
        }
      }
    }
  },
  "AllowFunnel": {
    "${TS_CERT_DOMAIN}:443": false
  }
}

Since this serve config tells Tailscale to generate a https certificate for us, let's turn that on in Tailscale before we use it.

Tailscale HTTPS Certificates

In your Tailscale Dashboard, go to the DNS tab and scroll to the bottom. Click Enable HTTPS and go through any of its prompts. Done! Now let's return to the terminal and restart these containers. The official docs are easy to follow for this step.

Restart with https

Our service container, freshrss, depends on the tailscale sidecar to function. That means we can't stop tailscale until our freshrss container has stopped. Let's write a small script to help us always stop the containers in the correct order. Call it stop to again mimic the podman cli.

#!/usr/bin/env bash

# reuse our envvars to get the container names
source .env

podman stop "$CONTAINER_NAME"
podman stop "$SIDECAR_NAME"

Then, we can also make a rm script to fully remove the containers. This could be one script, but I like breaking it into two for a few reasons. One, I might not always want to fully remove the containers. Two, it mimics the podman cli which has pretty good ergonomics for all its power.

#!/usr/bin/env bash

source .env

podman rm "$CONTAINER_NAME"
podman rm "$SIDECAR_NAME"

We need to add a line to our run script to mount the tailscale serve config, making the full file:

#!/usr/bin/env bash

source .env

podman run --detach \
  --hostname "$HOSTNAME" \
  --name "$SIDECAR_NAME"\
  --cap-add net_admin \
  --device /dev/net/tun:/dev/net/tun \
  --volume freshrss_tailscale_state:/var/lib/tailscale \
  --volume "$(pwd)/config":/config \
  --env-file .ts.env \
  ghcr.io/tailscale/tailscale:latest

podman run --detach \
  --restart unless-stopped \
  --log-opt max-size=10m \
  --network container:"$SIDECAR_NAME" \
  -e TZ=America/New_York \
  -e 'CRON_MIN=1,31' \
  -v freshrss_data:/var/www/FreshRSS/data \
  -v freshrss_extensions:/var/www/FreshRSS/extensions \
  --name "$CONTAINER_NAME" \
  docker.io/freshrss/freshrss

After all that, run the stop script, then the rm script, then the run script again. You should see everything come back up and work, with any state/login/rss feeds you already setup in FreshRSS!

Troubleshooting

Deleting the Tailscale state volume

If we delete the "freshrss_tailscale_state" volume, tailscale won't be able to reuse the same hostname. Instead you'll end up seeing "rss-1", "rss-2", etc. in your list of tailscale machines. To rememdy this, just use the tailscale dashboard to remove those machines, delete the "freshrss_tailscale_state" volume again and rerun the run script to reset the tailscale hostname

Tailscale isn't showing my machine or it isn't connected

If you can't see the rss machine, or it isn't connected, run podman ps -a to get a list of all the containers, including stopped ones. If you can see it has exited, you can run podman logs freshrss_tailscale to see what error messages it might have thrown.

Taking it further

Now that we have the container up and running, there's more we can do to automate! Podman has a great Quadlets feature that will run this all via systemd for us, adding a lot of resiliency. We can add more envvars to our .env file to make our scripts more configurable. We could write an up script to mimic a docker compose up style command. We could automate backing up FreshRSS by copying out the volume data somewhere. We could automate upgrades using podman rename before spinning up a new instance and inserting it where the old one was.

We could enjoy our FreshRSS instance and download a reader like Capy Reader to use it on our phone.

There are so many possibilities! I hope you enjoyed this tutorial.

Note Taking: Obsidian and Fastmail

Wed, 28 May 2025 00:00:00 GMT

Ben's Blog - Note Taking: Obsidian and Fastmail

Note Taking: Obsidian and Fastmail

May 28th, 2025 Ben

Everyone has a note taking app they prefer. For almost 5 years now I've paid for Standard Notes to give me plain text notes synced across my devices. Back then, I was much more bullish on encryption and privacy and this worked great cross platform. It gave me basic searching and sorting functions.

Old Editor

I never really liked their editors, even their Markdown or Spreadsheet ones. They didn't feel good, especially on mobile. Like they were making as many as possible, but not refining any of them. So I always used the plaintext editor, even when typing in Markdown.

I didn't want to fall into the hamster wheel trap of the next new note taking app. Standard Notes stored and synced notes like I needed. Migrating notes to a new experience every couple of months would be such a pain, especially into a new format. And just to try some other editor that will probably charge me money to sync.

A lot has changed in the time since I started using Standard Notes. I've gotten less strict about a E2E solution for everything. I favor open standards over the encrypted stuff now, in many cases. I switched email providers from Proton Mail to Fastmail (again, a big UX choice). I've learned much more about self hosting and have gotten more comfortable with how to put things on the web (including this blog). And it has been 4 or 5 years since I've changed notes apps, Standard Notes hadn't changed much in that time.

New Editor

I had heard about Obsidian on a couple podcasts, but mostly ignored it. I was setting up a new laptop at work, where I used the free version of Standard Notes, and decided this would be a good time to give it a try. The promise of all my notes being Markdown files on my computer was super cool. I figured I could script against them myself even! I don't need any syncing at work, it's just the one computer.

And wow, I was blown away! A few weeks in and I'm still amazed at how open Obsidian is, how responsive Obsidian is, and how many great features they've packed in. I've even taken a look at CodeMirror, and might use it in future projects.

I liked it so much at work I decided to download it on my Android phone and see if it could live up to my hype there. And it nailed it! Really just wonderful. The obsidian links make it easy to extends via macros and the markdown looks great.

Syncing Solution

So I also downloaded it on my laptop too. But now I needed a way to sync between my phone and computer. Since I've begun to self host other things, I started to look into that. But they all seemed like they might be a lot of work, I didn't want something that would be more maintenance than useful.

I looked into the official Obsidian Sync, which costs about the same amount as my Standard Notes subscription at $4/mo. But by now my imagination was going wild with embeddable photos and who knows what else! The official plan only gave me 1GB and sharing with my wife would be another $4/mo for her.

As I was looking at the possibilities, I stumbled into WebDAV as an option via the RemotelySave plugin . My experience with the DAV protocols are somewhat mixed. They're powerful but tough to use. Fortunately, my Fastmail email has a full WebDAV server. You can even view the files in their app! And my account comes with 10GB of storage, plus I could have my wife just log in with a different app password.

Migration

Coming back to this complaint from above, I haven't migrated much yet. Standard Notes will give me my notes in a .txt, and Obsidian will automatically recognize those if I change them to a .md extension. Some of the titles might be mangled and I might lose some metadata. But I had very little metadata, and titles can be repaired.

I've realized that maybe most of my notes are fairly transient anyway. The posts on this blog have a little more staying power, I think. So this is a work in progress, who knows how much I'll end up moving over.

Conclusion

Time will tell how long this version of note taking lasts for me. But Obsidian is an amazing product and RemotelySave with Fastmail makes it so easy to sync that for now, this is definitely a winner.

Defining Part Stack Developer

Sat, 10 May 2025 00:00:00 GMT

Ben's Blog - Defining Part Stack Developer

Defining Part Stack Developer

May 10th, 2025 Ben

On my LinkedIn page, my title is "Part Stack Web Dev." It came from an article I read or podcast I listened to that I haven't been able to find again, so I wanted to write a bit about it.

I work at a start up small enough that there are no defined levels or strict job titles, so when I heard about the tongue in cheek "part stack" I decided it would be a fun title to give myself. It's supposed to be a joke on "Full stack Developer" job titles where they mean "front end web pages/SPA and backend application servers," which feels like a majority of job postings.

Part Stack

But there's also a whole stack of computers and services to serve your application, why aren't those considered part of a full stack engineer's job? I think of that as an Operations role, so maybe those pieces fall under a "DevOps Engineer" title, which smashes the "developer" and "operations" roles together. Maybe all together that's a "Full Stack DevOps Engineer"?

Of course, all of these vary by company and HR department. And luckily there's a job description and interview process where companies and prospective employees can get a better understanding of what a role might entail. We know what all of these titles mean, to a certain degree, so what is a Part Stack Engineer?

I work on the part of the stack that drives your business and serves your customers. I can take a website/web application from Hello World to IPO. I can launch a site if you'll give me a bare metal server or VPS to deploy it on. I can build an application server capable of scaling to meet your demand, making it secure and observable. I can write HTML/CSS/JS to make your website look and feel like the brand you want to present.

Web Dev

If you noticed that everything on that list is related to the web, you might also remember my job title includes "Web Dev." I would happily call myself "Web Engineer," I don't mean to debate developer vs engineer here. Web Dev just rolls off the tongue better than Web Eng. The "web" part is important to me. We live in a world where you want your data to be accessible on your laptop, and your phone, and maybe a work computer, tablet, etc. It has to live somewhere, so a server (yours or mine) is a good place to live. HTTP/WWW is definitely the dominant paradigm for accessing those kinds of things, everybody has a web browser.

Having a web server also deliver the markup makes the whole thing so much more straightforward to develop; you'll save 100s of hours a year of developer time. There are similar projects for mobile apps. I can deliver a mobile ready website, but an app is one of my weakest areas. So I stuck the "Web" part in my self-proclaimed title because my works revolves around the web.

Conclusion

The web encompasses a lot of modern consumer computing. Any part of that stack is something I am interested in. At this point, 6 years into my professional programming career, I think I have at least a passing familiarity with most of it. And plenty of experience to plan, build, deploy, and operate a web application. So I call myself a "Part Stack Web Dev," a title I think encompasses a majority of my experience and interests.

PS, if you think you know where "Part Stack" came from, I'd love to know so I can link to it from here.

New Laptop: Framework 13

Sat, 19 Apr 2025 00:00:00 GMT

Ben's Blog - New Laptop: Framework 13

New Laptop: Framework 13

Apr 19th, 2025 Ben

I'm typing this on my new Framework Laptop 13 in the park because it's the first 80 degree day we've had this year. The screen is remarkably bright and it's standing up okay to the wind.

I've had a Lenovo X1 Extreme for ~six years now. It's been a great machine, but I decided to upgrade. In the past 6 years, I was able to plan my wedding with LibreOffice. I've become much, much more comfortable with Linux. A 16 inch laptop was getting wieldy, so I've been looking for something smaller. Microsoft is ending support for Windows 10 in October. All of those things were reasons to look at new laptops. But the only requirement in there is smaller, with a strong preference for Linux support.

I ended with a Framework because of their excellent Linux support, great size screen, and most importantly: their philosophy that you should be able to fix and upgrade your computer without buying an entirely new one. I've read some articles and had heard good things. They announced new main boards recently, selling their old AMD Ryzen chips at a discount. The price was much cheaper for a DIY version than many competitors. And I look forward to changing and upgrading my computer in the future.

I went with a bottom of the line AMD Ryzen chip, but spec'd it out with a 4TB hard drive and 48GB of DDR5 RAM. I opted for the nicer screen in thought of scaling 200% in Ubuntu and got plenty of expansion cards to take full advantage of them. A clear keyboard makes it a bit of a head turner, but otherwise nothing about this computer shouts "I can fix this!", it just blends in with the landscape. I have hopes of upgrading the main board in a year or so, and even then this computer will be cheaper for the specs than most of the competitors I looked at.

Overall, my first impressions have been amazing. It took me ~20 minutes to put the hardware together, even after reading all their docs twice. The installation of Ubuntu was a breeze, and their guide helped me feel even more confident. Everything has just worked and I've gotten all my typical tools installed: LibreOffice, Bitwarden, Brave, mise, git, eza, fzf, neovim... You get the idea. Some from the App Center, some from the terminal and everything has worked flawlessly. I'm getting to try out ULauncher and Sway (not at the same time) and podman. Basically, getting the laptop setup was a nonevent. In less than an hour of time, I was doing everything I wanted on it.

Book Review: The Unicorn Project

Fri, 21 Mar 2025 00:00:00 GMT

Ben's Blog - Book Review: The Unicorn Project

Book Review: The Unicorn Project

Mar 21st, 2025 Ben

Having never read another book by Gene Kim, he has captured everything I fear from the process and roadblocks and "checks" in a large corporation (and even small startups). While I find his choice of technologies a little hype focused (noSQL, functional programming, microservices), I think the business principles may have merit. But where do people randomly find servers from in a company?

Even if the business principles are part of a hype cycle like the technologies, the book was a fun read. It felt like epic fiction meeting corporate America, and the good guys won. The frameworks were well presented within the narrative and the references section has left me with a lot of reading from Erik's "sensei's".

His seamless blending of technology and business, with all the politics and conflicts it can create (and synergies), was well written to be approachable and familiar while providing plenty of context for those outside a corporate behemoth.

The timelines feel too condensed for any corporation I've seen or heard about, but they add to the fun narrative of the story. Most of the individuals details felt exaggerated like that: not too much, but enough to add enjoyment and suspense to the narrative. I hope I never work for or run a company asking their IT staff to work so much without properly recognizing or compensating them.

Some links to the book:

Custom Elements and the Light DOM

Sun, 26 Jan 2025 00:00:00 GMT

Ben's Blog - Custom Elements and the Light DOM

Custom Elements and the Light DOM

Jan 26th, 2025 Ben

Custom Elements have their own lifecycle. This makes it orders of magnitude easier to render partial page updates. No matter how the html is added to the page, adding a custom element will kick in it's own lifecycle. You'll never get these bits of html that should do something, but the JavaScript hasn't run on them because they were added after page load.

The Custom Element lifecycle gives us some of the reactive benefits of something like Alpine or React, but built directly into the browser. You'll probably hit the limit of this reactivity very quickly, but both the lifecycle and reactivity are compelling reasons to use Custom Elements. And they integrate very well with something like React, for more complicated components.

Custom Elements also give you the ability to use the ShadowDOM. A form of encapsulation that ensures you're interior elements are in their own little realm. But if I want a Custom Element to add behavior to the DOM, I still want to style it with CSS. So I rarely use the ShadowDOM. Instead, I use the "normal" DOM, or LightDOM, to make them easily accessible through CSS.

I haven't done much more than think about this next part, but I think the ShadowDOM would be the right decision if I were creating a new input or similar control. Something that is complicated enough where I want to also give some styling control over using parts and slots. Since my day to day work is still mostly in React, I don't do a lot of this. With React 19 and it's full support for Custom Elements, many complex React controls could be rewritten as Custom Elements. They might even still have React in them, but they could be templated and share the web page much more easily.

Note: I prefer the name "Custom Element" because it reminds me more of html elements. Conversely, "Web Components" reminds me more of React components. Whatever you call them, they feel decidedly more like html elements than React components, so I prefer calling them Custom Elements. I know Custom Elements are really just one part of the [Web Component suite of technologies](https://developer.mozilla.org/en-US/docs/Web/API/Web_components), but I often hear them used interchangably.

Custom Element With React

Mon, 20 Jan 2025 00:00:00 GMT

Ben's Blog - Custom Element With React

Custom Element With React

Jan 20th, 2025 Ben

In my previous post, I discussed how we can escape React out the top. The example there is nice, but feels like a lot of free floating code. We can make better islands of interactivity by using Custom Elements! In fact, we can even hide React as an implementation detail entirely this way. By making our entrypoint a Custom Element, we have something that's easy to template/render server-side and still have all of the interactivity client side that we use React for.

Our App component is almost the same as before. Since we know we'll have a Custom Element wrapping it, we don't need the div tag. With that change, our Custom Element, TextSwitcher, looks like this:

const App = React.forwardRef(function (props, ref) {
  const [msg, setMsg] = useState(props.defaultText || "Hi there!");
  useImperativeHandle(ref, () => ({
    update(newMsg) { setMsg(newMsg) }
  }), [setMsg]);
  return msg;
});

class TextSwitcher extends HTMLElement {
  connectedCallback() {
    if(!this.reactRoot) this.reactRoot = ReactDOM.createRoot(this);
    this.render();
  }

  render() {
    this.reactRoot?.render(<App ref={this.copyRef.bind(this)} defaultText={this.getAttribute('text')} />;
  }

  copyRef(refAttr) {
    for(const [key, val] of Object.entries(refAttr)) {
        this[key] = val;
      } // could also do this.ref = refAttr if worried about colliding with another property.
  }
}

customElements.define('text-switcher', TextSwitcher);

Then we can add a element anywhere on our page. We no longer have placed anything on the window object, so we can place many of these on a single page! Notice that a text attribute on our component above provides the default text for our App component, so we can set the default when it first loads! We can update any of them by targeting/finding it, then calling it's update method. You can change the text-switcher above by typing the following into your browser's dev console:

const elem = document.querySelector('#world-switch');
elem.update('Hello World!");

Maybe this example is still a bit contrived. It wouldn't be hard to change the text inside here without React or a Custom Element. Hopefully you can come up with places where you need the interactivity React provides. I think this approach would work there too. On pages where you need interactivity, but a lot of the page is static or basic form submitting, this approach would shine.

It might be overkill for something like a spreadsheet application, where the whole page is so reactive that you don't need to add the Custom Element layer. If you wanted to though, you could serve a page with a single element in the body that handled mounting React and doing all the things you'd normally do before rendering React to the web page. Still, it might be some work to get bundling and tooling working how you want with this approach.

Can you identify the principle I'm hoping to illustrate here? We can build web pages however we want and still take advantage of React. By making React into an implementation detail, instead of what's driving our design decisions, we've opened up a lot more possibility to reuse these components, mix and match how we do reactivity, and generally take more advantage of all the features a browser already gives us. We can integrate with forms directly. We can port complicated controls to simpler websites because we have written them in a way that fits right into the markup.

Breaking the React Wall

Mon, 13 Jan 2025 00:00:00 GMT

Ben's Blog - Breaking the React Wall

Breaking the React Wall

Jan 13th, 2025 Ben

I've written before about using useImperativeHandle to hoist functionality up a layer of React componentry. It helps to better encapsulate any state that component defines, without needing to expose it directly to the consumer.

You can use this same feature to "exit" React! If your top level component exposes a ref, you can access that with a ref callback! The simplest implementation, where our top level component is named App, looks like:

const App = React.forwardRef(function (props, ref) {
  const [msg, setMsg] = useState(props.defaultText || "Hi there!");
    useImperativeHandle(ref, () => ({
      update(newMsg) { setMsg(newMsg) }
    }), [setMsg]);
  return <div>{msg}div>;
});

const renderRoot = ReactDOM.createRoot(document.querySelector('#react-root');
function refFunc(refAttr: RefAttributes | null) {
    // attach it directly to the window for our example
    window.refHandle = refAttr;
}
renderRoot.render(<App ref={refFunc} />);

Then running window.refHandle.update("Hello World"); in the console updates the text within App! If you try it in your console window on this page, the text in the box below will change!

It's a very simple example, but it shows that we can get React to update directly, within it's lifecycle but outside of the React context, while staying within React's guidelines. I've seen it talked about very little! If it seems trivial here, it could turn a lot of React paradigms on their heads. Most React libraries feel like they try to fit the web into React's paradigm, instead of augmenting their webpages with something as powerful as React. Even more powerful than how frameworks like Next.JS do it today, we can allow React to do what it's best at (reacting to changes) and give us an escape hatch to also interact with other elements in the browser. Just like that, React can easily be made to create "islands of interactivity"

In more complicated "App" components, using an imperative handle means we don't need to worry about calling "render" again. The functions we expose act inside the React lifecycle, even though we're calling them from outside. The same thing could be achieved by placing functions on any element with in the ref, but by able to "come out the top" like this, we can place react DOM render roots anywhere we want, or isolate our consumer from React entirely by wrapping our component in a Custom Element.

It's important that we aren't just copying out a reference to a setState function or something like that. While that technically works, it breaks a lot of assumptions React and most developers would make about your code. It's a good way to cause a mess! Comparatively, using an imperative handle is something React gives us, and it exposes functionality in a way that we can easily see what's going on. Data still flows one way, callbacks are the primary method of interacting upstream, and React can dynamically update the handle if we need. The ref gives us a way to encapsulate some imperative logic as well!

Focusing an element is the classic example of when we might need or want to use some imperative logic, referencing the DOM directly in React. Dialogs also use this technique to call show and close. Checkbox even uses imperative logic to set its indeterminate state.

We can create a more seamless experience within React by mimicking these types of interactions, ones already available to us on the DOM. Developers can utilize their knowledge of the platform their on, or learn about it, while also using and learning our enhancements and new components. We aren't limited by what web browsers give us, and we can use React in its full power to write updates to screen, based on one way data bindings.

PS: You can see the script used in your dev tools, or at /scripts/breaking-react-wall.js. It looks a little different than the above script because it's in React 19, strictly javascript, doesn't use JSX, and I'm vendoring react and react-dom.

Stepper: React's useImperativeHandle

Sat, 14 Dec 2024 00:00:00 GMT

Ben's Blog - Stepper: React's useImperativeHandle

Stepper: React's useImperativeHandle

Dec 14th, 2024 Ben

State encapsulation is pretty good in React: one way data binding via props and callbacks for notifying of changing events. But how do I change the state of a component from outside it's declaration?

For example, I have a Stepper component that shows one of its children at a time, where the Stepper component manages the state.

Node, TLS, and DNS

Thu, 12 Dec 2024 00:00:00 GMT

Ben's Blog - Node, TLS, and DNS

Node, TLS, and DNS

Dec 12th, 2024 Ben

Node presents different problems when using local domain names. In my previous post about reverse proxying, I was able to connect to all my local services with verified domain names. But when I went to have my frontend address my backend as "backend.localhost" instead of "localhost:3256", I quickly learned that Node works very differently from the web browser.

SSL Certs

For starters, Node uses it's own hard coded list of root SSL certificates. The only way to add to them is the NODE_EXTRA_CA_CERTS environment variable, which would need to be set with every command! So I'm exporting that from my .zshrc file. It makes it harder to share the configuration, but I can live with it.

DNS resolution

Then I found node won't resolve *.localhost DNS queries to the local loopback the same way my browser will. The quick and easy way is to edit the /etc/hosts file, and feel free to do that if you want.

But I decided to try a second time to run PiHole. Knowing I couldn't publish port 53 from docker on my Mac, I booted up a Debian VM, configured a little bridge network, and I'm now running PiHole off that. I set my DNS resolution to that VM's IP address and I have a slick little solution on my laptop! Debian is running in Low Memory Mode, but PiHole doesn't seem to be skipping a beat. I'd call this a good solution for my local problem, but I plan to share the hosts file solution with my coworkers, or take it all a step further and put it into docker to use that name resolution.

Vercel serverless

Now that Node can find my services, and trusts them, I thought I'd be all set! Then those Vercel serverless functions started complaining to me again. Turns out, I no longer need to rewrite the Host header! Because I made the VERCEL_URL my frontend.localhost, so that's the Host header Vercel expects. That actually makes my reverse proxy setup so much cleaner.

Conclusion

My conclusion is that none of this was difficult to set up once, but it doesn't scale or translate as well to my coworkers' computers. It's a lot more work than just docker compose up, which is what I was hoping to achieve. As it is now, my coworkers' would need to know a little bit more about networking than I wanted them to need to know. A solution to that might be more Docker.

If I containerized all the dev services, I could probably share the Caddy cert via docker volume (No more manual envvar). I could change the reverse proxy to work on container names, instead of localhost:port. Would I still need DNS? It's maybe the largest problem, since I know I can't publish the DNS port to my Mac, full stop. But maybe if I took advantage of docker's networking name resolution, node would get it. Then my inter-container API calls would still be to a different name than accessing from the same host name as my web browser (still going through the reverse proxy), but that might be okay too. Would SSL resolution work between docker containers? That isn't something I've tried.

Reverse Proxy With Caddy

Tue, 10 Dec 2024 00:00:00 GMT

Ben's Blog - Reverse Proxy With Caddy

Reverse Proxy With Caddy

Dec 10th, 2024 Ben

I've never set up a reverse proxy before. The only thing I've done with Nginx is set up a simple file server for local development, based straight on their docker documentation.

But I wanted to give my local development environments names. To make them fel like real websites. My backed could live at "backend" instead of "localhost:3256". My frontend at "frontend" and so on.

There always felt like so many moving pieces. The easiest method, modifying /etc/hosts didn't solve it all. It would be hard to maintain, impossible to share with my coworkers, no SSL certificate, and I still needed port numbers. I needed a process that was easy to stand up, share, and felt magical without being too complicated.

Part of the reason I'm writing this blog is to centralize some of my most interesting or frustrating technical moments. So I'm writing this to help me recall this set up and hopefully for you to learn something from.

My Journey

DNS

I started the day trying to run pihole to resolve my services' names. I got pihole up and running in docker only to learn that port 53 is already used in a Mac. Turns out the Bonjour service uses it, so I can't run my DNS locally! In the end, it didn't matter. Web browsers will resolve anything ending in .localhost to the loopback interface anyway. Great, problem solved! Along the way, I realized all my services run at different ports. But web browsers only ever connect at one port, 80 or 443. And while I could maybe use SRV records that seemed overly complicated, when I couldn't even get pihole running. That's when I knew I needed a reverse proxy.

The Reverse Proxy

A reverse proxy could listen to ports 80 and 443, then send that traffic to the right service running on a different port. Since all the services will have names, the reverse proxy can use those to decide where to route the traffic.

I knew I didn't understand Nginx's configuration very well. Traefik's auto discovery bewilders me. Then I saw a two line Caddyfile for a reverse proxy and thought, "hmm, that's so easy!" It still took me an afternoon of tweaks though. The container networking had to be set to host so Caddy could proxy to ports on my local machine (since those services don't run in docker). Great, everything can talk to each other now! Except now my web browser doesn't understand I'm in a secure context (no longer localhost Host), so I need an SSL certificate...

SSL Certificate

And Caddy created a cert for me! One line in bash and I had it copied out of the docker container. It still took me an hour to figure out to trust the thing in Keychain Access on a Mac, but I didn't have to generate it!

My final hiccup of the day was with Vercel serverless functions. Locally, vercel dev also proxies whatever it's running, and it didn't like the custom name I gave it (frontend.localhost). It thought it was still hosted at localhost. Eventually, I figured out how to rewrite the Host header in the upstream and it was all good. And it was only ~3 lines in a Caddyfile! I feel very accomplished! I was lucky vercel dev worked with the Host rewrite because that's still about all I know about proxying.

The Next Day

I'd learn the next day that Node doesn't read your local SSL certs, or resolve *.localhost names the way the browser does. At least for now I'm able to effectively access all my sites with their names, instead of localhost:. That alone feels like a win, even if the configuration of my services still need to reference the localhost address. The rest of this I'll write about another day.

Caddy example

I've changed the port numbers from my local dev environment, but this is how my Caddyfile is laid out with the lines for Vercel serverless under frontend.localhost.

backend.localhost {
  reverse_proxy localhost:4321
}

frontend.localhost {
  reverse_proxy /api/* localhost:2345 {
    header_up Host {upstream_hostport}
  }
  reverse_proxy localhost:2345
}

admin.localhost {
  reverse_proxy localhost:5738
}

Not Your Parent's Software

Sat, 07 Sep 2024 00:00:00 GMT

Ben's Blog - Not Your Parent's Software

Not Your Parent's Software

Sep 7th, 2024 Ben

ONCE is a great example of software we can own, built for the modern world.

Years ago (when I was a kid), software mostly ran on the computer it was installed on. I just barely remember dial up, before computers had a persistent internet connection. Once they always had internet,the software on them started to shift. Your software could be on someone else's computer and you could still use it. You could access your data on any device. You didn't need to manage updates. {: #software}

At first, this was great. It felt like your computer gained new superpowers, doing more with less. These services were different than the software that used run on our computers. They were typically "multi-tenant" with a very complicated setup, often running over multiple machines. You might not know it, but they took a dedicated system administration/operations team to run. {: #software-tech-details }

Services often represent an ongoing relationship with the expectation is that you continue to pay. This was great for the companies moving to this model, they found a more steady stream of revenue. The revenue was much larger than they could generate selling software only once. {: #what-is-service}

And some of these computer "services" meet the services definition. For example, I get new music on Deezer whenever an artist drops a new album, a ongoing service. Email really does have a lot of complexity, when companies communicate between each other. But a lot of software doesn't meet those requirements, so shouldn't require that sort of ongoing relationship. {: #services}

Defense of the service model includes ongoing maintenance costs, payment for new features, or many other arguments. But these arguments rarely hold water. A lot of the software doesn't need significant ongoing maintenance (this is why software is so valuable). You didn't agree to new features, nor do you have a choice about them. They are typically foisted upon you, sometimes to the point of being barely recognizable. Changes this significant could and should just be sold again. Companies hope that losing all the data you've collected in their software will be enough to keep you until you're used to the new changes. {: #why-services }

That's where software like ONCE comes in. To bridge the gap between our parents' software and our modern expectations. After purchasing, it's your software with all the data freedoms our parents (unknowingly) enjoyed and all the access we expect from the modern day.

If this sounds too good to be true, there's some technology under the hood to make it happen. First, it's "single tenant", running on a single machine just for you. It gets updates like the software on your computer (regularly, when you aren't using, without downtime). It runs on your machine (although probably not your laptop). It's very self-contained. {: #tech-overview}

What all software works like this? ONCE has chat and book writing software. They've alluded to parking/permit managing software as well. I can think of password managers, podcast subscription apps, note taking apps, maybe even joining the Fediverse. {: #possibilities}

There are self hosted versions of all of these ideas already. What ONCE does better is focus on the User Experience of installing and maintaining. The install is one line. Maintenance happens automatically overnight. If a command line is intimidating, DHH demonstrated the whole process in an 8 minute video! {: #how-to }

I hope to build software like this one day. And I hope I won't be the only one!

GraphQL is Not Expressive

Wed, 04 Sep 2024 00:00:00 GMT

Ben's Blog - GraphQL is Not Expressive

GraphQL is Not Expressive

Sep 4th, 2024 Ben

It has only two categories of inquiry: Query and Mutation, with Resolvers knowing how to construct the return value. It's Query field lets you choose what results you want, that's great. But there's no way to relate a Mutation to another Type. For instance, a REST endpoint of conversation/:conversationId/chatEvent/create easily tells the reader that we're creating a chat event in relation to a specific conversation. The body of the requestcan then all be related to the creation, instead of being split between querying and creation.

In GraphQL, a Mutation has no "related" or "subset of" expression. Instead, a similar mutation to our above endpoint would look like:

type Mutation {
  createChatEvent(
    conversationId: ID!
    input: ChatEventBodyInput!
  ): ChatEvent
}

type ChatEventBodyInput {
  body: String
  metadata: [String]
}

A naive mutation might even lump all the args together in a flat list, instead of nesting them like my above example. But in either version, the conversation id is painfully front and center, making the arguments for creating a chat event a little muddier, a little less obvious.

Related mutations could be called anything. Resources have no graph. You can't show relatedness, except through enforced naming conventions. All this feels antithetical to GraphQL's intended purpose.

Another example, the Nested mutation

type Mutation {
  conversation(
    id: ID!
    createChatEvent: ChatEventInput
  ): Conversation
}

This mutation example does nest and relate like our REST example. It adds the possible mutations as arguments under a single Mutation operation. But at least in NestJS, there's no support for the idiom. It'd all filter through a single Mutation handler and we'd have to dispatch it ourselves, very unlike Resolvers. Then we'd need the resolvers to traverse the graph back to the item we just created! I've never seen this version in the wild, but very quickly it has already become too much work. If you want a REST-like system, use RESTful endpoints.

One last example, the Resolver Mutation

type Mutation {
  conversation(id: ID!): ConversationMutations
} 

type ConversationMutations {
  chatEvent(id: ID!): ChatEventMutation
}

type ChatEventMutation {
  create(input: ChatEventInput!): ChatEvent
}

This version is performing operations depending on which fields on our Mutation are resolved. It uses the return value to perform the actual mutation. This is much more expressive, it looks a lot like our REST pattern. It would have great support in NestJS. But it's not a pattern the graphql docs look at, and it would likely defeat some of the ordering guaratees. For those reasons, I conclude that this isn't really a pattern graphql supports.

Conclusion

Graphql favors the return value so much more than the Query/Mutation interface that it creates lopsided APIs. "Thinking in graphs" works for the return value, which is very expressive. But the input and arguments are not even close. Is this a fair trade off for REST endpoints, where the input seems more expressive but the output more rigid? I don't think so, because it's easy to create expressive endpoints. When you develop both sides, you control the output.

Eventing Like React

Tue, 03 Sep 2024 00:00:00 GMT

Ben's Blog - Eventing Like React

Eventing Like React

Sep 3rd, 2024 Ben

I have a previous article about using React to mirror DOM eventing style while still being able to use other React goodies. In that article, I gave an example of Submitting or Skipping a form. You might think that sort of semantic is something only React can do, but that's far from the truth! With Custom Events we can do the exact same thing with a normal form element. The code looks much different, but the end result is the same. Or maybe even more powerful, given it uses the browser to it's full advantage, instead of glossing over it like React does.

The browser has so many rich APIs for interacting, including a strong eventing system! Using it, we get so much for free and can easily listen to the parts of the document we need. That's a blessing and a curse, if we aren't careful we could end up with a convoluted mess. I've managed to make convoluted messes in React too, though. This skip example is a great example of how powerful augmenting it directly can be. Let's dive in:

<body>
  <form>
    <input name="name">
    <button type="submit">Submitbutton>
    
    <button type="button" onclick="skipForm">Skipbutton>
  form>
  <script>
    /**
     * A barebones implementation of our skip event
     * @example
     * elem.dispatchEvent(new SkipEvent());
     * */
    class SkipEvent extends CustomEvent {
        constructor(detail) {
            super('skip', {
              detail,
              bubbles: true,
              cancelable: true
            });
        }
    }

    /**
     * fires a SkipEvent
     * */
    function skipForm(event) {
      event.stopPropagation();
      this.dispatchEvent(new SkipEvent())
    }

    // add listeners on the document so we can see it fire when it bubbles up
    document.addEventListener('skip', (e) => console.log('form skipped', e));
  script>
body>

Which will show up on our document as a skipped event! This is the parallel to how our onSkip handler worked in React, except this version pulls in all of the power of the browser's native event system! We can attach that behavior to any element we want very easily because we've described the behavior and the view separately!

One Step Further

In our above example, we've only fired our skip event on the button. We could easily fire it on the form as well, maybe if we receive a blank submission. Unlike our React example, we can actually get better granularity here! In React, we can't tell what caused onSkip to be called. The skip button might have fired the event, or an empty input may have! Since DOM Events have a target property, it's easy to check. We can model this in React by passing the SynctheticEvent as part of our onSkip callback, but the DOM provides this out of the box.

<body>
  <form>
    
    <input name="name" onsubmit="submitForm">
    <button type="submit">Submitbutton>
    <button type="button" onclick="skipForm">Skipbutton>
  form>
  <script>
    /**
     * A barebones implementation of our skip event
     * @example
     * elem.dispatchEvent(new SkipEvent());
     * */
    class SkipEvent extends CustomEvent {
        constructor(detail) {
            super('skip', {
              detail,
              bubbles: true,
              cancelable: true
            });
        }
    }

    /**
     * fires a SkipEvent
     * */
    function skipForm(event) {
      event.stopPropagation();
      this.dispatchEvent(new SkipEvent())
    }

    /**
     * skips if empty input, submits if not
     */
    function submitForm(event) {
      event.preventDefault(); // so the page doesn't refresh on us
      const formData = new FormData(event.target); // the data the form is submitting
      // get the name out of our form data, if it's blank stop the current event and fire a SkipEvent from here
      const name = formData.get('name');
      if(!name) {
        event.stopPropagation();
        this.dispatchEvent(new SkipEvent());
      }
    }

    // add listeners on the document so we can see it fire when it bubbles up
    document.addEventListener('skip', (e) => console.log('form skipped', e));
    document.addEventListener('submit', (e) => console.log('form submitted', e));
  script>
body>

Which version do you like better? Which is more legible? Which do you think is easier to maintain? Which provides more context? Which one can communicate with the backend more easily?

My last parting thought is that the above is a complete body to a webpage. Give it a head and doctype and you can host it anywhere. Just use it like that and a browser is probably kind enough to show it to you still. In my React example, there's some boilerplate to bootstrap the app client side I didn't include. Why not just use the native client side, instead of requiring a bootstrapped context?

Reach Eventing Like the DOM

Mon, 05 Aug 2024 00:00:00 GMT

Ben's Blog - Reach Eventing Like the DOM

Reach Eventing Like the DOM

Aug 5th, 2024 Ben

React doesn't have a builtin eventing system like the browser does, but you can model your components after it. You can leverage the DOM Events through on* handler props on JSX elements, which produce Synthetic Events and gives access to them, but you can't easily fire your own Custom Events off of the Nodes React creates. This means any event you want an element to listen to needs to get an event handler or signal or callback from somewhere. Often that's the state management library, but it might just be prop drilling.

So sticking with the Synthetic Event model, we can write a familiar interface for our own components. onClick is called everytime the mouse clicks that element, onChange will be called when the input changes (weirdly on an input, that's the browser's oninput event). When we're building our own components, we should strive to do the same thing. Have events as callbacks that start with "on___". Give access to the event that is finally fired from the browser, if you can. The higher level component can tie into state management for us; that's a nice separation of concerns and allows us to reuse our component in more places. This will push us to think like the nodes we're manipulating, the DOM.

Example

Have a form that can be submitted or skipped? Have the components that encapsulates the form include onSubmit and onSkip props. What fires the onSubmit? Form submission should. Then have that callback take two arguments, the processed form data (for ease of use) and the React.FormEvent event that the form element has, to give as much information as we have access to. How do you skip? When a button is pressed? Great, just have that whole callback be a React.MouseHandler. Oh, you want to call onSkip if the form is submitted empty as well? Then change the type to (event: React.MouseEvent | React.FormEvent) => void;. Maybe that isn't quite as pretty, but it's honest and actually gives information about how the event was triggered, unlike a simple () => void; that I see in a lot of code.

Setting up your components like this might be more work initially, but like refs it helps us focus our effort in making components that work with the browser model better. It forces us to think about component boundaries in a way that we can work with and learn about the DOM as we're building. The React goodness on top and not being tied directly to the DOM allows us to contextualize what we're writing to the domain at hand. Put another way, this style helps ground us in the rendered truth of the browsers DOM while letting us express our problem domain.

What does it look like in practice? In the simple example, with no preprocessing:

type NameFormProps = {
  onSubmit: React.FormEventHandler<HTMLFormElement>;
  onSkip: React.MouseEventHandler<HTMLButtonElement>;
}
function NameForm({onSubmit, onSkip}: NameFormProps) {
  return (
    <form onSubmit={onSubmit}>
      <input name="name" />
      <button type="submit">Submitbutton>
      <button type="button" onClick={onSkip}>Skipbutton>
    form>
  )
}

A little more complicated, to tie into React better:

type NameFormProps = {
  onSubmit: (name: string, event: React.FormEvent<HTMLFormElement>) => void;
  onSkip: (event: React.MouseEvent<HTMLButtonElement> | React.FormEvent<HTMLFormElement>) => void;
}
function NameForm({onSubmit, onSkip}: NameFormProps) {
  const submitHandler = useCallback((ev) => {
    ev.preventDefault(); // stop the network request forms make by default
    // collect the name field from the form
    const formData = Object.fromEntries(new FormData(ev.target).entries());
    if(formData.name.trim()) onSubmit(formData.name, ev);
    else onSkip(ev);
  }, [onSubmit, onSkip]);
  return (
    <form onSubmit={submitHandler}>
      <input name="name" />
      <button type="submit">Submitbutton>
      <button type="button" onClick={onSkip}>Skipbutton>
    form>
  )
}

Can the browser do this? What would it look like? I mentioned Custom Events above, here's my article about implementing it that way

JSX: Writing the Language To Meet You

Fri, 26 Jul 2024 00:00:00 GMT

Ben's Blog - JSX: Writing the Language To Meet You

JSX: Writing the Language To Meet You

Jul 26th, 2024 Ben

Like LISP, JSX allows html to be written "up" to easily define new concepts.

Like LISP macros, poorly written components and abstractions make them harder to work with. But well constructed ones make hard things easy to express.

Templating languages seem unable to allow the language to be written up to express harder concepts. But since JSX is an XML that closely mirrors HTML, where "tags" can be created and defined and expand into any amount of other tags, the markup language can be written up to the concepts they need to express. Making hard things easy to express, just like macros. Able to make hard things really hard to reason about, if done poorly, just like macros.

Almost like custom elements, although the compile-time vs run-time behavior still makes them a bit different enough that I don't think custom elements would provide an useful implementation of this pattern. You can argue React/JSX is run time as well, but JSX has started to be found more places.

I got the inspiration from Lisp, but Elixir has good support for macros. I wish JavaScript had any type of macro system, instead of needing to bolt on code generation.

A good abstraction helps you understand the underlying technology, so remember you're ultimately modelling HTML. Being able to use your abstraction layer while in the mindset of writing HTML is a good gauge on a good abstraction. A good example might be a modal or dialog, where the parent and child tags work together (like select/option or ul/li or table...):

<Modal.Root>
  <Modal.Trigger>
    Click Here!
  Modal.Trigger>
  <Modal.Body>
    You are now looking at the content.  Click anywhere to close.
  Modal.Body>
Modal.Root>

Of course having a good mental model of HMTL helps yourself. But if you don't start with one, you'll learn as your write. Having a good goal to strive for is half the battle! Good luck on writing your React components.

Very Semantic HTML

Sat, 20 Jul 2024 00:00:00 GMT

Ben's Blog - Very Semantic HTML

Very Semantic HTML

Jul 20th, 2024 Ben

Semantic HTML can be a very charged topic. A quick search on the internet will yield plenty of results about how you should use each tag. Some of them should be pretty much common sense. nav wraps navigation elements. main is your main content on the page. header, footer are for their respective parts. But div, article, and section have different nuances for different people.

This article is about taking this idea one step further: what if we could make our tags have even more semantic meaning? What if the markup could have semantic meaning for the project we're in? What if we could model the domain as part of our markup? You want to display an Avatar? Use this Avatar component. But a single component isn't always enough. Here are all of the pieces of our Avatar components, use what you need. It has a Root container, a Face, Initials to fallback to, and a Popover that we sometimes include for more information.

Or for form input: this EmailCollection object holds everything we typically use to request an email. The Root, Label, and Inputs hold all the styling an info to make it easy for you to build one. Need to add something extra? Just add it to the label, or after the label, or wherever you need it. We could write

<EmailCollection.Root>
  <EmailCollection.Label>
    Please enter your email:
  EmailCollection.Label>
  <EmailCollection.Input />
EmailCollection.Root>

and have that incorporate any styles and business logic related to collecting emails. In raw html, the best I could think of would be something like a BEM-inspired:

<div class="email-collection">
  <label class="email-collection--label">
    Please enter your email
  label>
  <input class="email-collection--input" type="email" name="email" placeholder="ben@example.com">
div>

which is still pretty good and readable, although it doesn't have any behavior connected to it. But more importantly, where does that live that it can be reused? How do I know to reach for that markup when I want to request an email input? My EmailCollection component above is a React component that I can easily import and reuse wherever need be. It's easy to find in a code base. I know I'm not missing anything about how my company wants email collection to look or behave. The element might literally be the same markup, but semantically I can speed read a page or larger component and easily pick out the email collection components. BEM makes this easier in the html example, but I estimate that it's more likely to be tailwind utility classes in many companies.

Most templating systems can import/include other templates. But file-based components mean utilities, types, children, and general extras need to live in a different place. I can't have one object of related tags to build with. It's tough to build the behavior into these templates. How do I build the same level of flexibility into these templating systems? In Nunjucks, the closest I can get is

{% extends "email-collection.njk" %}
{% block label %}{{super()}}  Please enter your email{% endblock %}
{% block input %}{{super()}}{% endblock %}

or maybe something involving macros. But both are whole different files for every new usage. There's no concept of children or nesting after in includes, very different from html. I'm primarily a JS/TS dev (front- and back-end), are there other templating systems that could allow for something like that?

I've been thinking about using Custom Elements for this concept, but those don't translate down to the raw html that I want. Ultimately I would love to just serve the raw html. Maybe I could use custom elements to define the behavior, but I would want to upgrade some raw markup with the custom element. Otherwise, I'm not sure what I've gained over React (other than being a little counter culture and losing a dependency), but I know I've still lost all the reactivity that makes React so popular and still a lot of the flexibility of their component system.

Reminder, I'm primarily a JS/TS developer, so I got to wondering if there were a html tagged template literal that could be used as a rendering engine in express, maybe that would afford me the flexibility to encapsulate some behavior, define them flexibly, define children, etc. Or maybe I'm over thinking why file-based templating is really such a problem. Template fragments might help me extract parts of a page, but they don't help me make the templates I write more semantic; have semantic meaning in the project I'm writing for.

Maybe there's a JSX-based, backend templating system that doesn't rely on React or try to mimic React that I could use. It'd be a great gateway system to being able to build my markup the way I want but still be able to transmit raw html over the wire. I did find an article or two about it, but nothing with much steam.

Lots of questions and ideas, no good answers from me today! Why do I want this? I want to build server driven systems using the most powerful transfer markup, HTML! Modern browsers give us so much goodness, and backends and client experiences can be shifted so much easier when you're only building one place. There's lots of reasons, basically. But I haven't found a templating system that makes me feel more productive in yet.

In conclusion, I realize I have a lot of requirements for a templating system! I really like how semantic React allows my markup to become. I want to use a server templating system and just deliver html, but I'm not as happy with the templating options I've found. I'll leave a list of requirements I've picked out in a list here at the bottom:

Requirements for building very semantic html

from most to least important:

easily and flexbily create my own naming conventions, that mostly thin-wrap actual html components
output raw html
write in a way that allows for children within the templating spec
be able to pass attributes (and maybe properties) to each child independently
be able to define and export multiple components from a single file

nice to have:

include how a component behaves within the definition (likely include some js, then)
collect related components into single object
stretch: include some css that could get translated directly into the head? Maybe this one is too framework-specific. It might be nice, but definitely not a requirement.

Description of Wonka Operations

Mon, 15 Jul 2024 00:00:00 GMT

Ben's Blog - Description of Wonka Operations

Description of Wonka Operations

Jul 15th, 2024 Ben

Suffice to say, wonka operators are a simple concept that becomes incredibly tricky very quickly! This post is about wonka streams and callbags: a fusion of Observables and Iterators.
I would read up on some of this if anything in this post confuses you; there isn't enough room to go over everything I'd like to. The best metaphor for this methodology is a pipeline or a river system.

Operators let us transform the stream of data that comes through. In the wonka and callbag specs these are very simple looking functions, that receive other functions, and sometimes call other functions. All these functions flying around are confusing! Yes, they are all the same javascript construct, a function, but they have very different roles.

An operator is a function that returns a function

An operator is a function that accepts a source function and returns a sink function

An operator is a function that accepts an upstream function and returns a downstream function

The upstream function should be called with a callback function that will be called with a signal, and doesn't return anything. The upstream function determines when this function will be called, and can call it as many times as it'd like. It can signal to us that data will begin flowing (START), that it has data to give us (PUSH) and also when it has run out of data (END).

source((signal) => {/* could be START, PUSH, or END */})

A downstream function should be called with a signal, whenever you're ready in the operator. You call it with the START, PUSH, and END signals to talk to the function downstream of you in the pipeline.

return (sink) => {
  sink(START, /* talkback */);
  sink(PUSH, /* data */);
  sink(END);
}

When an upstream function calls the downstream function with START, it should provide another function to "talkback" to it, which the downstream function can tell the upstream function it'd like more data (PULL) or it's done receiving data (CLOSE). This is usually called the talkback function.

return (sink) => {
  sink(START, (talkbackSignal) => {/* could be PULL or CLOSE */})
}

There is a lot of flexibility here... Our operator needs to call the source and call the sink; that's basically it for a functioning operator. A well-behaved operator will also END when asked, probably sending that signal downstream, and forward a CLOSE signal upstream. But it might not, depending on how you want to control the flow of data through your operator. That's the beauty: you have the flexibility to manipulate the data any way you see fit. But it also means that it is on you to explain how your operator transforms the flow through it, and what your operator does when it receives each of the different signals.

This was my very high level overview. They can be very confusing to look at, at first, so let me leave you with a few examples:

// no-op operator, pass the sink we were given directly to the source provided, add no behavior
function operator(source) { return (sink) => {source(sink)})}

// no-op operator
function operator(upstream) return { return function downstream(sink) { source(sink); }}

// basic shell, non functional since I'm not handling any of the signals
function operator(upstream) {
  return function downstream(sink) {
    /* call the source */
    upstream(function ourSink(signal, payload) {
      /* do whatever we need with the START, PUSH, END signals */
    })

    sink(START, function talkback(talkbackSignal, payload) {
      /* do whatever we need with the PULL and CLOSE signals */
    }))
  }
}

// no-op operator, but a basic shell of what could be
function operator(upstream) {
  let ended = false;
  let talkback = () => {};

  return function downstream(sink) {
    /* now that we have the sink */

    /* call the source  */
    upstream((signal, payload) => {
      if(ended) {/* this whole call will be a no-op if we've received an END signal already */ }
      else if(signal === END) { 
        ended = true; 
        /* what else might you want to teardown when it ends? */
        }
      else if(signal === START) { 
        talkback = payload; // hold a reference to the talkback function, so we can talk to our source
        /* what else might you want to start to be ready to receive data? */
        }
      else {
        /* do things here with Push signal */

        // would send the push signal we receive from upstream directly to downstream,
        // not typically useful by itself.
        sink(signal, payload); 
        // cachedData = payload; // maybe store the data locally, so we can send it down later?
      }
    });

    // remember to start the sink so we can give it our talkback function!
    sink(START, (signal, payload) => {
      // since this is the talkback, signal will be CLOSE or PULL
      if(signal === CLOSE) {
        talkback(CLOSE);
      } else if {
        // do something with the PULL signal
        talkback(PULL);  // maybe ask the source for more data?
        // sink(PUSH, cachedData); // maybe push some locally cached data down right away, instead?
      }
    }})

  }
}

function map(mapper: (x: X) => Y) {
  return function operator(upstream: Source) {
    return function downstream(sink: Sink) {
      let ended = false;
      let talkback = () => {};
      source((signal, payload) => {
        if(ended) {}
        else if(signal === END) {ended = true}
        else if(signal === STARt) {talkback = payload}
        else {
          sink(PUSH, mapper(payload));
        }
      });
      sink(START, (signal, payload) => {
        if(signal === CLOSE) {
          talkback(CLOSE);
        } else if {
          talkback(PULL);
        }
      })
    }
  }
}

// usage:
pipe(fromArray([1, 2, 3]), map(x => x + 1), subscribe(console.log); // prints 2, 3, 4 each on their own line
// looks weird without the pipe though...
subscribe(console.log)(map(x => x + 1)(fromArray([1, 2, 3])));

Additional reading:

Form Validations

Thu, 13 Jun 2024 00:00:00 GMT

Ben's Blog - Form Validations

Form Validations

Jun 13th, 2024 Ben

When my front end is decoupled from my backend via JSON API, how does my front end know what kind of validation logic my backend does on the data I provide it? Usually, it doesn't! How do I communicate what is a valid input to my user?

I won't lie, typically I just recreate the validation logic in both places. It isn't very DRY, and it's a pain to change. My backend is even in Javascript, so you'd think it'd be easier to share logic! But the server and browser are different places, so how do I communcate that a date picker can only be from yesterday to next month? In current form, the front end would "know" the requirement and the html produced would be:

<input type="date" min="2024-02-14" max="2024-03-15" name="reservation-date">

Then the backend would have some validation logic that checked that requirement again. A naive example would look like:

reservationDate > "2024-02-14" && reservationDate < "2024-03-15"

If the requirement changed to now allow 2 months into the future, which would you change first? I would relax the backend validation to the new requirement, then the front end. 2 changes in 2 codebases with 2 different deployments. This case is simple too, since the change is simple. But I still can't relax the front end requirement first, the backend would complain even though it looks like a date I can choose.

Server Driven Architecture

What if I could encode all the requirements and validations into a response, sent by the server, that my front end could generate the right control, with all the right validations baked in? Relaxing the allowable date from 1 month to 2 months would only requirea change to my backend, no change to my front end. What does that look like in practice? If I'm using a JSON API, I might have this shape:

{
  controls: [{
    type: "date",
    min: "2024-02-14",
    max: "2024-03-15",
    name: "reservation-date"
  }]
}

But notice how similar that is to the input above?

<input type="date" min="2024-02-14" max="2024-03-15" name="reservation-date">

I've basically encoded all the input attributes in json! Why not save myself a step and just send the input element itself? In a web application using React, with a decoupled JSON API, sending HTML is hard and unintuitive. But if you're already serving HTML from your backend, this should be a breeze (and likely what you're already doing). And templating language will suffice, I like Nunjucks with Express

More complicated validations

What about when the allowable date is dynamic, maybe based on the type of reservation?

<input type="radio" name="reservation-type" value="one">
<input type="radio" name="reservation-type" value="two">
<input type="radio" name="reservation-type" value="three"

Now you front end has logic to change the date picker min/max values based on the state of the "reservation-type" checkbox. How do you code that in a Server Driven Architecture? My only answer is I don't know; and it's too complicated for me to think of an answer that will satisfy all permutations of the equation. So in my day job, react app, I encode the difference validations two places: react in the front end and the mutation in the backend. But in a server driven architecture, we could have an endpoint to receive the date picker and call it every time the value of reservation-type changed. If we could send html, we would just have three date pickers on the backend we could send. This is a case for HTMX; I can reuse the validation logic from my backend and any updates can all be performed in once place, the backend. I can send and receive and splice html with ease. Or if there were another serialization format my front end could understand, maybe I could use that.

Tech Itch

Fri, 12 Apr 2024 00:00:00 GMT

Ben's Blog - Tech Itch

Tech Itch

Apr 12th, 2024 Ben

What is the tech itch?

For me, it's the feeling that a new technology would solve the problem I have in a simple manner, but taking my current project into the new tech is too heady a task and too big a risk for it to maybe solve the problem.

I define a new technology as anything me and my co workers are unfamiliar with, not that it's new to people. They are technologies that I'm unsure the best use case for and I don't know somebody who is knowledgable about it. In these cases, I need to find external sources like blogs or videos to get an idea, or use it for myself.

Usually the itch isn't satisfied until I've determined whether a technology will or won't work for my use case, until I no longer have that problem, or until I'm not feeling the pain of the problem anymore and no team weight was behind solving it.

This itch is usually what leads me into hobby projects (including this blog!)

Repo Local Todos

Tue, 09 Apr 2024 00:00:00 GMT

Ben's Blog - Repo Local Todos

Repo Local Todos

Apr 9th, 2024 Ben

Not all software I write is very collaborative. Many hobby projects I start are just me writing a project, or part of one, to learn a new concept or scratch some itch I can't at work. There's not as much structure around these projects, but as they start to grow, I have ideas about things I want to do in them that I don't have time for right now. Every project has a README, so I use some github-flavored markdown to include some checkboxes in a list of things I wanted to get done, eventually. That saves it right in the repo and I have it as a reference for later, without going out to another tool.

I can never remember where I leave those tools, and don't always open them when I'm working on hobby projects anyway.

The Problem

As a professional programmer, I'm competent with git, so I branch my repo to explore and complete my different todos. Then I can merge (or often rebase) back into my stable branch for deployment. Git is a wonderful tool for this, of course, but I start running into issues with my README!

I write down the todos in my README whenever the inspiraiton strikes me. I usually put my new todos in a separate commit, but I check off todos in the same commit I complete the work in; both put me in an awkward situation with git. In two branches I'll have added two todos on the same line and git doesn't know what to do! It gives me a merge conflict and leaves my otherwise painless merge/rebase in a seeming state of disarray. See, my code doesn't conflict, just the README file!

The Solution

While working through some other, code related, merge conflicts at work the other day, I realized that git is much better about these merges at the file level. If I add two files in the same directory, git will just add them both in the final merge too. If I model each todo as a file, then adding todos is as easy and merge free as adding files as long as I plan on storing them in my repo with git anyway.

If I delete and edit todos in different branches then I'll have merge conflicts. But deletion will only happen when I'm done with the task, which will only happen in one branch since my branches focus on my todos. This also means that any deletions can theoretically supersede any changes; maybe those changes became a new todo, but if a todo file is deleted then it's done.

An Extension, collaborating with others

Theoretically, I could collaborate with others using this same system. All the above applies with more than one person; I'm hardly even using a thin layer over git itself. But I think coordinating work would be hard. In my branch I'm "assigned" Todo A, but I made that change after you branched off. If you start doing that work also before merging in our shared branch when I've assigned it to myself, we may end up both doing the same work! With a little bit of git discipline, I still think it's possible; maybe there's a todos branch that you could cheaply merge in any time because the todos are so conflict-free. Maybe you're only really considered assigned that work if the patch is in that branch. It wouldn't necessarily require a central repository (like github or gitlab) to take advantage of either, just sending the todos branch patch to everyone could work as well.

An aside, only a few of my projects actually have deployments, but I like having a place where I know the code is relatively stable and doesn't contain half completed todos.

I like having my todos checked into git so I can see the evolution of work over time, and reveal some of the structure that created the list in the first place.

Turbo, Helmet, and CSP

Sat, 23 Mar 2024 00:00:00 GMT

Ben's Blog - Turbo, Helmet, and CSP

Turbo, Helmet, and CSP

Mar 23rd, 2024 Ben

I had some trouble with Turbo, but I couldn't find anything online about it. It appeared my requests were being upgraded automatically from http to https, and I couldn't figure out why. I'm building a little node web app for easier calendar entry of my fiance's irregular work schedule. It's mostly a learning project, I wanted to learn a little about WebDAV and different ways to deploy to production. I know javascript, node, express pretty well so I started there. Got everything working, rendering Nunjucks templates and absolutely no client side javascript. I learned some stuff about user authentication, and installed Helmet into my application, but didn't change too many of the defaults.

Then I wanted to learn more about Turbo. I knew I wanted some javascript to add a little more feedback here and there, but this site was meant as an experiment in good progressive enhancement techniques, so the site didn't need any javascript running. I toyed with the idea of HTMX, but Turbo did so much right out of the gate that I was hooked. It also seems to have a good story about progressive enhancment as well. Except forms wouldn't reload properly!

Finally I just used data-turbo="false" to disable it for my main form, but that wasn't want I wanted long term. None of my requests were doing this before Turbo, but I couldn't figure out what difference was causing the issue. See, Turbo swaps the browser's builtin request mechanisms for ajax calls. It's nearly transparent and they're both network requests, so what's the big deal? Browsers treat these two things very differently though, because normal navigation can be trusted (the browser must think, "I made it myself") but ajax calls are untrusted and Content Security Policies (CSP) greatly affect how scripts can run.

There's a lot of options for CSP header directives, I don't fully understand them all. But that's what Helment is for! Good defaults and strong security, except even it acknowledges that it's CSP header may need some configuration. After a little trial and error I settled on the "update insecure requests" directive was the one causing the issue. My server was requesting the browser upgrade any requests being made, and the browser was happily complying! It wasn't happening to normal redirects because the server asks the browser to make those, so there's no client side involvement. But with Turbo intercepting those redirect requests, the browser needed to make sure those would be secure, that's what the server asked for!

End of the story is that I disabled that directive of the CSP header in development and now my forms work just as advertised! I don't expect this to be an issue in production, where I want all requests to be made securely. Hopefully this little tidbit is helpful!

Is React a Framework?

Wed, 20 Mar 2024 00:00:00 GMT

Ben's Blog - Is React a Framework?

Is React a Framework?

Mar 20th, 2024 Ben

Or is React still a library? React started as a library to enhance a webpage from server rendered templates, like Rails, Laravel, or Phoenix. Sprinkle a little extra interactivity on and you can enable much more than the browser on its own. Did this ever mean you were mounting React in multiple places on the page? I wasn't there for it, so I don't know. I've never seen a website like that, but it would fit with progressive enhancement and the ethos of React being a library.

Now, React has a framework and a majority of apps send only enough html over the wire to mount their React app (if any, some apps bootstrap through javascript too!). With React Server Components (RSC) and Server Side Rendering (SSR), what's different with React than server rendered templates a couple of decades ago? They've been making improvements too!

React as a templating language can be much more expressive than things like Handlebars. But erb and heex also fully embed the language, so Javascript is then the choice language, not the only language.

Then there's the argument for one language for front and back end, like JAMStack has always evangelized. But most React apps seem to still only be the frontend, communicating wiht a backend that could be in any number of languages. If it's doing this, now you need to have 2 deployments, typically 2 repos, etc.

If your Next.js project is your entire app, you might still argue for the better interactivity it provides; since with RSCs it provides server actions and streaming. But they aren't the only game in town; LiveView takes this up another notch by providing stateful sessions. Hotwire enables full control communicating back and forth in a language agnostic way through a few html-compliant web components, and even dips strongly into native apps.

If React were still a library, it should be competing with the likes of Stimulus not the likes of Rails. If it is a framework, running as much on a server as in a broswer, then it's not as batteries included as Rails, nor does it have as refined an ecosystem as Laravel. It feels like React is straddling two worlds today, but I'm not sure it's doing either well anymore.

Deployments

Mon, 11 Mar 2024 00:00:00 GMT

Ben's Blog - Deployments

Deployments

Mar 11th, 2024 Ben

How do you deploy your projects? At work, we use Vercel, but my dream is to just have a server and be able to take my code anywhere. I have a little computer at my house I use to host some small docker applications, but nothing that I've created. It's tough, connecting it to the outside world. But it's a problem I'm working on. For now, I'm happy to pay Digital Ocean for some small servers, not even $10/month, to run some stuff.

But writing software and deploying it are two orthognal problems. If I went with something like Vercel, I would never be able to run it (easily, at least) on my computer at home whenever I figure out the best way to expose that. Enter Kamal, a tool that claims to let you "deploy web apps anywhere", "from bare metal to cloud vms". Which sounds great, that's the flexibility I want! Made by the people behind Rails and Basecamp at 37 Signals, whom I've been looking up to since starting my web dev career 5 years ago. They have a good track record, I'll take a look.

I made a quick Rails app; I have no experience with Rails in particular but all I really need is one route and a Stimulus controller , it took me a short morning to create. It's not a fancy page, maybe I'll link to it after it's been running for a few days. Two days later, I got it to deploy! Not bad considering I never even needed to ssh into another machine! I found a couple tutorials to help me with my traefik config, fixed some problems with my rails master key, and now it's on the web!

The one external resource Kamal relies on is a container registry. I didn't want to sign up for a whole docker account or whatever just to push some dev images up, so I looked for another solution. I tried Github Container Registry, but I think you need to connect it to a code repo. I've been hosting my code on sourcehut, and trying to minimize my reliance on GitHub as well, so I continued to look. I settled on Digital Ocean's container registry; added that to my config/deploy.yml file and watched kamal deploy push it up! It felt almost magical.

Kamal has a wealth of other commands to look at logs and run commands. It makes me feel like I have my own personal command center, capable of commanding all the servers I want with one command. Able to pull statuses and uptime in the blink of an eye; now I just have to decide if 512 MB is too little memory to run a rails server...

Terminal vs TUI

Sun, 21 Jan 2024 00:00:00 GMT

Ben's Blog - Terminal vs TUI

Terminal vs TUI

Jan 21st, 2024 Ben

For a long time I've loved using the terminal, but couldn't quite figure out what I liked about it. Things I did all the time I could make faster relatively easily, mostly. Not all software was that way though, even on the terminal. What was the difference between the software that I could automate away for my daily tasks and the ones I couldn't? The ones that had Command Line Interfaces (CLIs) vs Text-based User Interfaces (TUIs). I wanted to like Text-based User Interfaces (TUIs) because they were on the terminal, and the terminal made things easier for me, past the initial learning curve. But the two have very different user philosophies, even though they both run in the same place. The largest different, I've decided, is the captive interface.

Command Line Interface

A CLI has no captive interface. It takes your command as input and spits out output. This allows it to be easily used in scripting and extended to a users content. Add goodies like aliases in there, and you can redefine how most of these work for you, simplifying and streamlining common workflows for yourself. The "for yourself" is important. Designers didn't have to create the perfect experience for you. They gave you tools that made it easy to create the perfect experience for yourself.

My favorite types of CLI tools? Non interactive, plain text (easily parsable) output, and the most useful ones conform to the Unix philosophy Point 2:

Expect the output of every program to become the input to another, as yet unknown, program. Don't clutter output with extraneous information. Avoid stringently columnar or binary input formats. Don't insist on interactive input.

A great example of this that I use every day is a git alias: git logo which expands to git log --oneline; it's 8 characters instead of 17 and for the amount I type it every day, probably saves me hundreds of key strokes a month (and many typos, --oneline is tough for me for some reason). Another example is git delete-gone; it strings together a few git commands and grep to delete branches that have been deleted from the origin remote. I don't even know what command it exactly runs without looking at it, but it's a task I know how to do.

Text-based User Interface

On the other hand, TUIs, or CUIs (captive user interfaces), are typically keyboard and menu driven experiences that don't script well. It's meant for user interaction, often offering fewer keystrokes to accomplish a goal (maybe reading email), but makes it less extensible. Keybindings can usually be reconfigured, but you can't connect it with other applications.

The Inbetween

There are a few tools that change how they behave in respoinse to their environment. Don't supply the flag, but the tool needs that information? It will ask for it interactively. An old example is apt install, where you are then prompted if you want to install the found software, but you can pass a -y flag to ignore this prompt and run the whole command noninteractively.

A better example is ripgrep, where it will default to pretty printing in your terminal, but has a plain text mode and other formatting options that make it more suitable for scripting. It does some checks to pick the best method by default and provides flags to override.

Github's cli tool is another good example, supply the -b flag and a body and it won't ask for one. Don't supply one and you get an interactive question in your terminal. I haven't poked around enough to know if you can turn off all the questions, even without supplying the flags, but it's a very lightweight interface I appreciate when opening PRs.

Possibly somewhere inbetween are server-client memory models like tmux or kakoune which are used interactively but have detached modes where commands can be sent via a CLI. I like these best because they offer the interactivity of a CUI with the scriptablitly of a CLI. How are these systems built? I have no idea, but it's something I plan on exploring.

These "inbetween" softwares demonstrate that software transcends a single philosophy and can pragmatically support multiple, which can provide more users a better experience while keeping the familiarity between modalities. Software that works best for all users is the best kind of software.

Software I Use

Wed, 01 Mar 2023 00:00:00 GMT

Ben's Blog - Software I Use

Software I Use

Mar 1st, 2023 Ben

I’ve enjoyed using the terminal ever since I found one on my computer. I’ve seen “scripting” as a way to get a computer to do anything, magical. Even magical compared to computers more generally; everything interoperates in a terminal and feedback is consistent in place, if not always in format.

What makes the terminal magical? The more I learn about the terminal, the more I realize it’s the Unix philosophy and POSIX that has really made the terminal what it is. It isn’t the terminal directly, but the practices around software that runs in the terminal that really makes it great.

“Everything is text” and “Everything is a file” abstractions are a great lowest common denominator, especially when used in conjunction with line processors like sed or awk.

But the beauty of the terminal doesn’t end with POSIX or commands written before I was born; there are new utilities that follow this philosophy and have made my work more productive. They are:

jq
csvq
fzf
kakoune
ripgrep

having an easy way to parse json (a format that gained popularity while I was alive) makes a lot of sense today, and jq does a great job of following the Unix philosophy. It plays well with stdin/stdout, other files, etc.

like jq, csvq makes it easy to work with csv data sets on the command line, using sql syntax. Sometimes the data takes a little cleaning up, but sql is such a powerful tool that my coworkers think I'm some sort of wizard after I have the answer to their question 5 seconds after giving me a csv file.

fzf, or the fuzzy search finder, is a unique one in my mind. It gives me a menu of options but somehow still plays nicely with stdout, using stderr to show the options. I'm not sure if that use would be frowned upon by Unix purists, but it's very practical in my mind. It also plays great with the next item, kakoune.

kakoune (kak in the terminal) is a great editor, inspired by vim but selection oriented, running in a server/client configuration to really be able to configure it as a light ide. It gives enough commands `([a-]!&|)` to interact and transform text with other command line tools that this interactive terminal application still integrates very well with other commands (following Unix philosophy). Getting the lsp integrated was a huge bonus, and their clippy character has been amazingly helpful in finding commands. I could spend more time setting keybindings, but honestly most commands are pretty straightforward and searchable. I’ve been excited to find answers to nearly all my questions online already, even though I haven’t heard much about this editor in my day to day. If I had to gripe, I'd complain that formatting commands have been tough for me to figure out.

finally ripgrep, which is supposed to be just a faster, prettier grep. The default recursive search feature has been very nice, as well as the output controls. The default gives me plenty of information to the find and edit what I’m looking for, but I can also turn it all off easily enough for piping to other commands. It also respects the gitignore of my project unless I tell it not to, which means I'm always searching through files I want.

Bonus: nnn. I’ve never used noice, and I’m still learning nnn. But it’s nice to have such an interactive file manager in the terminal. This should integrate very well with kakoune, although I haven't quite figured out how yet.

The future: I’ve installed sxmo on a pinephone I have lying around. I was able to install all of these (I didn’t try nnn) on it. I basically have access to all of the same tools on Mac and PostMarketOS/SXMO because of Unix and POSIX. And once I get ssh setup, I could conceivably connect to it and type on a full keyboard over the internet.