Thinking on Backend Engineering Strategy Tools

Site Navigation — Beyond the Menu

Thu, 04 Jun 2026 00:00:00 +0000

A menu works when the content is shallow and the audience knows what they want. It breaks down when the content grows into something more like a knowledge base — when you have 80 notes across 12 sections and the useful thing is not finding a specific page but discovering that two ideas are connected.

There are a few distinct problems here and they need different tools.

Retrieval vs exploration

Retrieval is when you know what you want: “where did I write about Terragrunt?” A search box solves this. Fuzzy matching, title weighting, done.

Exploration is when you do not know what you want, or want to rediscover something you wrote a while ago. A menu does not help. Search does not help — you cannot search for something you have forgotten exists.

The menu is for retrieval by navigation. Search is for retrieval by keyword. Neither is for exploration.

What does not work

Most recently used / most popular — this feels like someone keeps moving your things. The notes that surface are the ones you or others have looked at lately, not the ones that are useful to you now. Navigation should not have memory that works against you.

Alphabetical listing — fine as a fallback, not useful as a primary navigation mode. Proximity means nothing.

Two experiments

Mindmap

Every note as a node. Edges connect notes that share tags or belong to the same section. Lay it out with a force-directed simulation and you get a visual map of the knowledge base — clusters emerge naturally, isolated notes stand out, and you can trace paths between related ideas.

The interesting property: clicking on one note shows which other notes it is connected to. This is not search — you are not looking for something specific, you are seeing the neighbourhood of an idea.

Try it →

Word cloud

Sections and tags, sized by how many notes carry them. The big words are the areas where there is the most material. Click a word and it feeds directly into the search.

This is an overview of the shape of the knowledge base. Good for answering “what is actually in here?” in a few seconds.

Try it →

The shared data model

Both visualisations run off the same JSON index that powers search — a build-time output from Hugo listing every note with its title, URL, section, tags, and summary. One data source, three interfaces.

The technical implementation is in Notes: Site Navigation.

What is still missing

Tags are sparse — most notes do not have them, so the mindmap edges are mostly section-based rather than cross-section. Adding tags to notes as they are written would make the mindmap significantly more interesting over time.

The word cloud currently surfaces sections more than tags for the same reason. As tags accumulate, it will shift toward showing the actual concepts rather than just the categories.

Both are experiments. The interesting question is whether they change how notes get written — if knowing that a note will appear in a connected graph encourages tagging, or whether tagging feels like overhead.

These Are Not the Pipelines You Are Looking For

Thu, 04 Jun 2026 00:00:00 +0000

There are a lot of CI/CD platforms. GitHub Actions, Tekton, Jenkins, Jenkins X, Harness, Bitbucket Pipelines, GitLab CI, CircleCI, Argo Workflows. The choice between them is a perennial argument — and mostly the wrong one.

The mistake is putting your build logic inside the pipeline. Once you do that, the pipeline owns your build. Reproducing a failure locally means setting up the CI environment. Switching platforms means rewriting all the steps. Testing the pipeline means pushing a commit and waiting. The platform becomes load-bearing.

The fix is straightforward: keep all logic in Make or Dagger. The pipeline calls one command. make build. make test. dagger call publish. That’s it.

The pipeline shrinks to thin orchestration: trigger on a git event, check out the code, call the command, report the result. It does not know what the build does. It does not care. You can swap GitHub Actions for Tekton or Tekton for Argo Workflows and the only thing that changes is the YAML wrapper around the same command.

More importantly: you can run the same command on your laptop. No CI environment to replicate, no “it works locally but fails in CI” gap to debug. The build is the build, wherever it runs.

This matters more the longer a project lives. Build tools consolidate and diverge. Platforms get acquired, deprecated, or repriced. Jenkins pipelines from five years ago are maintained by people who weren’t there when they were written and can’t run them outside of Jenkins. The projects that survive these transitions cleanly are the ones where the build logic was never in the pipeline to begin with — it was in a Makefile or a build tool that could run anywhere.

Gradle, Maven, Make — these predate CI/CD platforms by decades and will outlast the current generation of them. Put your logic there. The pipeline is a trigger and a reporter. Keep it that way.

The pattern in practice:

build:
 docker build -t myimage:$(VERSION) .

test:
 go test ./...

publish:
 docker push myimage:$(VERSION)

# GitHub Actions — the entire pipeline
steps:
 - uses: actions/checkout@v4
 - run: make build
 - run: make test
 - run: make publish

# Tekton — same command, different wrapper
steps:
 - name: build-test-publish
 image: golang:1.22
 script: |
 make build
 make test
 make publish

Same logic. One command. Any pipeline.

Shared Tooling Images — One Image, Three Contexts

Tue, 02 Jun 2026 00:00:00 +0000

The problem with per-context tooling: CI uses one version of a linter, a developer’s machine has another, a colleague has a third. Someone upgrades locally, the pipeline fails. Someone pins the pipeline, local runs drift. The maintenance surface is the number of places you install tools multiplied by the number of people on the team.

The fix is one Docker image that travels across all three contexts:

CI/CD — the pipeline pulls the image, runs the same tools
Local development — developers run the image instead of installing tools natively
Colleagues — same image, same versions, no setup docs to go stale

When you need to upgrade a tool, you change one Dockerfile and cut a new tag. Everyone gets it on next pull. No coordination required.

Why Docker?

There are other ways to solve this — dotfiles, Nix, OS package managers, VMs, cloud-init. All valid in different contexts.

The reason Docker makes sense here is that we are already working in a Kubernetes ecosystem where containers are the starting point. Most CI systems support Docker and OCI-compatible images natively. So the question becomes: is it worth introducing a different tool management approach alongside containers, or is it less costly to stay consistent?

Personally, I lean toward staying consistent. Your mileage may vary depending on your stack.

What Goes in the Image

The principle: include anything that needs to be consistent across contexts. Linters, formatters, build tools, CLI utilities.

Not the runtime — that is the application’s own image.

What specifically goes in depends on the target platform. A Kubernetes-only image looks different from one that also includes a cloud provider CLI. Adding tools increases the maintenance burden, so keep each image focused. That is also why there are multiple images — see The Repos below.

Typical candidates:

kubectl, helm, kustomize
Linters and formatters for the languages in use
jq, yq, curl and similar utilities
Cloud provider CLI where needed (aws, openstack)

Versioning

Follow SemVer — image tag equals version. Merge to main triggers a release. No need to complicate it beyond trunk-based development.

Before merging, build and publish an image from the branch so the change can be tested and verified before it lands on mainline. The branch image is short-lived and not promoted to latest until the merge.

Usage Patterns

A shell alias or Makefile target wraps the docker run so nobody has to remember the full invocation:

alias toolbox="docker run -it --rm -v $(pwd):/work -w /work image:latest"

Then toolbox helm lint . or toolbox kubectl apply -f . works the same locally as it does in CI.

Interactive sessions are where this pattern pays off beyond CI. Drop into a persistent terminal with the right context already loaded — kubeconfig mounted in, cloud credentials available, working directory set:

docker run -it --rm \
 -v $(pwd):/work \
 -v ~/.kube:/root/.kube:ro \
 -w /work \
 image:latest bash

You get a shell that looks the same for everyone on the team, regardless of what is installed on their machine.

For interactive use it is worth including a help script that runs on entry — either via ENTRYPOINT or by sourcing it from .bashrc inside the image. It should print what tools are available, their versions, and any common usage examples. Keeps the image self-documenting: a new colleague drops in and immediately knows what they have to work with without reading a README.

# example /usr/local/bin/toolbox-help
echo "=== Toolbox ==="
echo "kubectl $(kubectl version --client -o json | jq -r '.clientVersion.gitVersion')"
echo "helm $(helm version --short)"
echo "aws $(aws --version 2>&1)"
echo ""
echo "Run 'toolbox-help' at any time to see this again."

In CI the step just references the image directly — no installation step, no version pinning in the pipeline config beyond the image tag.

The Repos

Three tooling images, each a superset of the previous, plus two supporting images:

GitHub repo	Docker Hub	Contents
`image-tooling`	`best-tools/tooling-k8s`	kubectl, helm, kustomize, argocd, k9s, jq, yq
`image-tooling`	`best-tools/tooling-k8s-aws`	`tooling-k8s` + AWS CLI
`image-tooling`	`best-tools/tooling-k8s-openstack`	`tooling-k8s` + OpenStack CLI
`image-buildx`	`best-tools/buildx`	CI builder — Docker buildx, AWS CLI, Dagger CLI
`image-pandoc`	`best-tools/pandoc`	PDF generation — pandoc + TeX Live

Repo names use image-<purpose> in the Backend-Engineering-Strategy-Tools org. Docker Hub names drop the prefix and just describe the tool. The three tooling flavours share one image-tooling monorepo so dependency updates and scanning are configured once.

Pipelines are written in Go using Dagger — the same pipeline runs locally and in CI, publishing multi-arch images (amd64 + arm64) triggered by a version tag.