The System Wayfinder
》What Is Wayfinding?
Subways, airports, grocery stores - even cities and the sea. Wayfinding is about reading the environment to get where you are going. In the past this would involve knowing the stars, following migrations, using a map and compass. Now wayfinding is GPS and a multitude of signs. More than that, it’s a sort of language to help guide people. Think about color coded parking garage levels or neighborhoods with matching street signs throughout.
In some ways, this exists in cyberspace with iconography, typography, and color on the web. But often those elements are in the service of branding more than wayfinding. That said, most sites have their own wayfinding elements such as site maps, searches, breadcrumbs, and other navigation aids.
》Brining Wayfinding To The Command Line
What I’ve found from many years of managing systems is that the environment is largely lacking helpful markers that enable wayfinding. Occasionally a clever admin has set desktop background with color-coding and useful host into, or perhaps put something useful in /etc/motd.
The need for this really showed itself to me from my experience with self-hosting a bundle of services. Over time they have moved between hosts, survived restoration after disk failures, and needed oh so much maintenance. And certificates and firewall rules and DNS entries. Keeping notes is helpful, but the distributed nature of all those services makes maintenance hard.
Having more in situ notes sure would be nice. So I set out to make a tool to help with that. The goals I had in mind at the start were:
Reminders that show when `cd`ing into a directory
Notes about what is available on a system to show at login time
Easy editing of notes
Very early in the prototyping stage these were added:
Ability to run commands
Shell integration
Situational storage of command history
》How It Looks Today
Visually, I chose a combination of the Reference Mark and a triangle to represent the project:
Since this is all cli-driven, I had to settle for using them separately. The
goal is to make output from way very distinct so it doesn’t get confused
for other programs.
Here are examples of how the tool looks today. The main program is named way
and works with subcommands like way show or way edit.
》At Login Time
Right now this is barely fancier than motd, but in future versions I plan
to make this smarter and able to fetch into over the network. This requires
adding way login to the shell’s init scripts.
※┃System Wayfinder Login Notes
▶┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━
┃ this is a test
┃ this system is used for foo, bar, and baz》Upon Entering A Directory
I maintain a couple of Nextcloud instances which are mostly pretty trouble
free. Logging in to deal with problems is infrequent enough that the details
of the occ tool and such are always forgotten.
Now when I cd into the directory containing Nextcloud I’m greeted by
helpful reminders:
nundrum@webhost:~# cd /var/www/nextcloud
※┃Wayfinder help available here
┃ Usage reminders: occ upgrade tail
┃ Commands: tail upgrade occ
nundrum@webhost:/var/www/nextcloud#》Viewing Notes And Invoking Commands
One of my instances tends to time out using the web-based update tool. It’s
an easy fix. Since the shell integration notified me that reminders and
commands are available, I just run way show all to see them. Running
way show upgrade would have sufficed as well.
nundrum@webhost:/var/www/nextcloud# way show all
※┃occ
▶┣━━━
┃ Running OCC
┃ The OCC tool has to be run as www-data
┃
※┃associated command:
▶┠───────────────────
┃ sudo -u www-data php ./occ
※┃upgrade
▶┣━━━━━━━
┃ Upgrading Nextcloud
┃ use 'occ upgrade'
┃
※┃associated command:
▶┠───────────────────
┃ sudo -u www-data php ./occ upgrade
※┃tail
▶┣━━━━
┃ Nextcloud log
┃ Follow data/nextcloud log with JSON parsing
┃ and filtering on stack traces
┃
※┃associated command:
▶┠───────────────────
┃ tail -f data/nextcloud.log | jq 'del ( .. | .Trace?)'
nundrum@webhost:/var/www/nextcloud#Satisfied that the upgrade command is what I want, all it takes is way run upgrade to launch it!
nundrum@webhost:/var/www/nextcloud# way run upgrade
[an hour of logs was elided]》Go Get It!
I’m looking for feedback, ideas, use cases, code submissions, and who knows what else. Contact into is in the sidebar, or use GitHub. Thanks!