The Blog of Tom Webster - Blog Post

Debian: Waterfox Flatpak and KDE Plasma Browser Integration

2025-12-24T00:00:00Z

If you’re moving to Waterfox because of the Mozilla CEO’s recent threat that “[Firefox] will evolve into a modern AI browser…” and you use KDE Plasma, you may be surprised to see that the native browser integration doesn’t work. Don’t fret though, the problem is actually because Waterfox is looking for files that haven’t been copied to the right place. Let’s fix that.

The Workaround

The most convenient way to install Waterfox and keep it updated automatically is through Flathub. The files we need will be created once the Firefox Flatpak is installed. Go ahead and install the Firefox Flatpak as well. You’ll also need Flatseal to add a permission to Waterfox.

Open your application launcher and search for “Background Services”. In the search bar, type "browser”. You should see two services:

Pause and unpause the Plasma Browser Integration Flatpak Integration service. This step may be unnecessary, but will speed things up if you’re between polling cycles (this is mostly an assumption).

Now, let’s copy some files:

# Copy the integration host to Waterfox's flatpak data directory
cp ~/.var/app/org.mozilla.firefox/plasma-browser-integration-host ~/.var/app/net.waterfox.waterfox/plasma-browser-integration-host
# Make a director for the next file
mkdir ~/.var/app/net.waterfox.waterfox/.waterfox/native-messaging-hosts
# Use sed to replace the Firefox flatpak app id with Waterfox's flatpak app id,
# then output that file to where Waterfox will look for native-messaging-hosts.
# Ref: https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging
sed 's/org\.mozilla\.firefox/net\.waterfox\.waterfox/' ~/.var/app/org.mozilla.firefox/.mozilla/native-messaging-hosts/org.kde.plasma.browser_integration.json > ~/.var/app/net.waterfox.waterfox/.waterfox/native-messaging-hosts/org.kde.plasma.browser_integration.json

Now, open Flatseal and select Waterfox to edit its settings. We need to go to Session Bus → Talks and add a new item: org.kde.plasma.browser.integration .

Now, when you manage the Plasma Integration add-on and go to Preferences, you’ll see options! Furthermore, you can control your browser’s media with your media keys and system tray icons.

The Real Fix

This is a cool workaround, but the real issue lies in https://invent.kde.org/plasma/plasma-browser-integration. The application watches for many different browsers, but not Waterfox… for now… hopefully… I have a merge request out to KDE with the fix for Waterfox, both Flatpak and native versions:

https://invent.kde.org/plasma/plasma-browser-integration/-/merge_requests/180

If this is accepted, THIS WAS MERGED - it will eventually trickle down to various Linux distributions, fixing this problem without needing the tinkering shown here.

Personal Rant

This move by Anthony Enzor-DeMeo is extremely disappointing and disheartening. Honestly, this dank meme is the best way to sum up how I feel about the situation:

In return Alex Kontos of Waterfox replied with this:

https://www.waterfox.com/blog/no-ai-here-response-to-mozilla/

So I installed Waterfox, imported my data, and tried it out. Its just Firefox with all the bullshit removed. Exactly how it was advertised. Exactly what I wanted. No Pocket, no sponsored stories on the new-tab page, no VPN ads in my menus, no telemetry. Sensible defaults that just work. It even has Tree-Style Tabs right out of the box. Its been a few days, but so far, I’m happy with this being my daily driver.

🦋 Interact with this post on Bluesky:

https://bsky.app/profile/samurailink3.com/post/3marpca6yck2v

How to ruin your domain’s email reputation with ONE EASY TRICK!

2025-11-24T00:00:00Z

A shop I regularly go to restructured their loyalty program and made you opt-in to marketing emails. Sure, fine, whatever, juice the numbers. The person at the counter told me I could instantly unsubscribe, so no real harm.

Later, when I tried to unsubscribe, the site gave me this message:

I shop here regularly. I gain and use my points quite often. Its a nice bonus for being a consistent customer. This is extremely fucking scammy. Its also a fucking great way to destroy your domain’s email reputation.

Actually, that’s a great idea. I made an email rule on Fastmail that automatically sends emails from this address directly to spam. I keep my points, I don’t get spammed, and in the process, I hurt their domain’s email reputation.

I also sent off an email to their support channel. I don’t expect it will do anything to change their minds, but it won’t impact me.

A lot of tech gives you control over your experience. Don’t let idiotic product decisions hurt you without a fight. Dig into your options menu. Use email rules. Block viciously.

🦋 Interact with this post on Bluesky:

https://bsky.app/profile/samurailink3.com/post/3m6fuo3vkjc2k

Halloween 2025 Data Analysis

2025-11-01T00:00:00Z

“THEY GOT BIG CANDY!!”

It’s another year and another chance to keep the legend alive! For the fourth year in a row, we’ve been the “Full-Sized Candy Bar House” in our neighborhood. Just like last year, we’re tracking candy selections using a pair of Notion databases. While this has continued to work well, the actual experience of doing the tracking in real-time is a bit too slow when group sizes reach above 3 people. I have some ideas on how to speed this up with buttons and automation in Notion, but that’s a problem for next year.

As always, if you’d like to dig into the data yourself or follow along with this post in a side-browser, have at it:

Untitled

New Experiments

This year, we cut back on the sheer variety we had. Last year we had 40 different items. This year, we cut that down to 25 varieties of candy and one bonus toy. This seems to have cut down on option-paralysis and made our inventory much easier to manage. Keeping the selection curtailed with a few specific experiments seems to be the best way going forward.

Toys

From an unrelated project, I had a lot of 3D printed articulated sheep laying around.

The model is “Articulated Sheep” by Teigan Blackshaw. It’s a wonderful model, easy to print, and super cute.

So I figured I could pawn them off on the neighborhood trick-or-treaters 🙂. Before anyone thinks I cheated someone out of candy - The sheep was a “Bonus Item” you could take if you wanted to. Most trick-or-treaters opted to take both a piece of candy and a sheep. One trick-or-treater opted out of the sheep, taking only candy. No trick-or-treaters took only a sheep.

I started with 15 sheep and the inventory was exhausted in 40 minutes.

3D printing articulated toys and models isn’t really hard, and it isn’t really expensive. I’m still pondering, but I think I may try to put out a few different toy varieties in various colors next year. There are no shortage of great models to choose from.

Lesson Learned: We should have different databases because manually excluding the sheep in calculations annoys me. I should optimize for laziness wherever possible.

Twizzlers

We didn’t think these would be popular, but wanted to confirm our suspicions. You’ll see in the data later, we were sadly correct. Well… maybe not “sadly”, because we get to dispose of them ourselves.

Lesson Learned: We like Twizzlers, nobody else does.

Nerds Rope

I think Nerds Rope and Nerds Gummy Clusters are some of my favorite “newer” candies. While they weren’t “unpopular”, they never hit the highs I was expecting from that candy. That said, we have a theory as to why they didn’t take off at the start of the evening and picked up towards the end:

We staged the Nerds Ropes in the candy bowl in a way that they wouldn’t fall all over the place. Only about half of the candy was visible above the bowl. Compared to the candies around it (and especially compared to the towering Airheads Xtremes in the next bowl over), they just weren’t “big enough”, they didn’t stick out among the crowd. Halfway through the night, we re-arranged the Nerd Ropes and stuck them up a bit higher. At that point, we saw the popularity pick up considerably, elevating Nerd Rope from “an unpopular disaster” to “solid pick”.

Lesson Learned: Staging is likely more important than you think.

Notable Data Points

Here’s the juicy deets you’re here for:

Headline Stats

Total Candy Selections:
138 (which
just
beats last year’s 137)

Trick-or-Treater-ers per Hour:
~42 (a bit slower than last year’s ~46)

Most Popular Candy Type:
Fruit (which almost doubled the amount of chocolate-candy selections)

Most Popular Item:
Airheads Xtremes - Rainbow Berry (for the
second
year in a row)

Popular (and unpopular) Picks

Again, Airheads Xtremes led the pack, with the Airheads brand taking 24.6% of all selections this year. The next most-popular pick was the ever-classic Crunch Bar with 14.4%. Reese’s were slightly more popular this year, with 6 selections over last year’s 4. I was worried the classic peanut butter + chocolate combo was growing tired. This gives me a little hope.

Here’s what we ran out of:

And here is a list of treats that got picked just once. I hope you found your favorite thing:

And just one treat didn’t get picked at all: Classic Lays. Oh well, more for me.

Chips were wildly more popular this year, making up 7.9% (11 total) of all selections. This eclipses the 3 chip selections made last year. People seemed extremely excited by the chip selection if they didn’t go right for the candy. If someone wanted a break from the sweet treats, they appreciated the differing option. Oddly, Sun Chips were quite popular with very vocal fans, tying Doritos - Nacho Cheese for first place in the chip selection category.

We’re absolutely keeping chips for next year.

On brand selections, through the sheer popularity of Airheads Xtremes, the Airheads brand leads with 24.6% of all selections. Even though Skittles doesn’t crack the individual candy selection leaderboard until position 7, the sheer variety of Skittles means the brand overall is quite competitive, claiming the bronze with 13.7% of all selections. M&Ms remain somewhat unpopular, but nearly match last year selections with 6 selections in 2025 and 7 selections in 2024.

Sour Patch Kids experienced a massive drop in popularity. In 2024, the brand claimed silver with 19 total selections. In 2025, this has dropped to just 6 selections. In looking at the data, I can only conclude that the lack of Sour Patch Kids - Watermelon this year has had a truly devastating effect on the numbers.

Lesson Learned: The Sour Patch Kids are nothing without Watermelon.

Fruit candy dominated this year again with trends mostly following 2024 (the exception being the large bump in chip popularity).

What’s Next?

I’d still like to automate this data collection somewhat, but I’ll probably just start with better ergonomics. Buttons, dashboards, those sorts of things. Make it faster to insert data (and correct data when a trick-or-treater changes their mind). 3D printed toys will be interesting to experiment with. I want to see what we can do with this data going forward. Is there a candy company that would love to trial new packaging or flavors on an ultra-small scale? That’d be cool.

Anyway, thanks for getting to the end, and I’ll be here again next year to dive into the super-niche world of Halloween Data Collection!

👋

🦋 Interact with this post on Bluesky:

https://bsky.app/profile/samurailink3.com/post/3m4ltdxpqrc2f

Windows 11 “upgrade” pushed me to reinstall Linux-on-the-Desktop and I’ve never loved my computer more

2025-10-27T00:00:00Z

OMG TLDR:

If you’re interested in escaping Windows 11 purgatory: Try Linux

Your games likely “just work” thanks to Valve’s incredible work:
https://store.steampowered.com/linux

KDE fucking rules

My experience isn’t perfect, particularly with screen-sharing/game-recording. I am still troubleshooting issues there.

The Backstory

Like a lot of people, I stubbornly stayed on Windows 10 until support for it ended on October 14th, 2025. OS upgrades on Windows can be problematic, thus fresh re-installs are recommended. I’ve been using Windows operating systems since 3.1, this is a well-known fact to me. Regardless, I figured I’d try the direct upgrade anyway. Spoiler alert: Major instability issues. BSODs, driver incompatibility, massive performance degradation for GPU-intensive games (~25% FPS drop, eventually leading to full game crashes and system BSODs). Eugh, but fine, a complete reformat and reinstall from scratch was always part of my expectations. So I took a local backup, formatted my boot drive, and installed Windows 11 from a USB stick.

I reinstalled drivers, ran updates, reinstalled a few critical software packages (like Firefox), and thought my troubles were over. The only hurdles I expected were basic annoyances like turning off anti-features like OneDrive and CoPilot, and getting used to needing to hold shift when I right-click in Explorer. The first day went fine enough. Played some games, even recorded some gameplay. Then I rebooted and everything went to hell.

All graphically-intensive games started to run extremely poorly. Gameplay would last for roughly 10 minutes before resulting in a crash-to-desktop. At one point, even Discord restarted itself. Every few minutes, my computer would lock up, then play my actions in fast-forward to catch up. I eventually diagnosed this issue to Windows Update “helpfully” installing a 15-month-old NVIDIA driver. Annoying, but solvable:

I used DDU to completely shred the old driver in safe mode, then rebooted without any network to install the latest driver package available from NVIDIA’s website. This worked… for a day. Then symptoms started to crop up again, not as severe as before, but still plenty impactful.

The main issue was the massive GPU performance dip. I have an RTX 4080, not the newest card, but really nice, plenty of headroom to play most games at their highest graphical fidelity. I play a lot of Hunt: Showdown, and I try to record gameplay so I can make clips for my friends and the internet. The Windows 11 performance hit made recording gameplay impossible. It would freeze OBS, then Hunt, then my computer. Even lowering settings didn’t help.

To troubleshoot, I did everything I could think of, including (but not limited to):

Installing several older NVIDIA drivers (complete with DDU-backed safe-mode removal)

Deleting shader caches for impacted games

Lowering in-game graphics settings

Lowering OBS recording resolution and quality settings

Checking temps with
OpenHardwareMonitor

And so much more

I spent days trying to make Windows 11 as performant as my Windows 10 install, but I just couldn’t make it work. I’m sure there’s some magic incantation somewhere (or something dumb I’ve forgotten to do), but I just couldn’t make it work. My options boiled down to:

Deal with it, this isn’t my computer anymore, its Microsoft’s.

Move back to Windows 10 and pay Microsoft their “protection money” through Windows 10 Extended Security Updates (ESU) program.

Move to a non-Windows platform.

As long as the “supported/recommended” OS for my system was unusable, how bad could Linux-on-the-Desktop be? Its not like I’m any worse off if things don’t work. I dug a spare M.2 drive out of my parts bin, installed it, and downloaded Debian.

My History with Linux-on-the-Desktop

I’ve been an on-again-off-again Linux-on-the-Desktop user since 2006, first experimenting with Knoppix live CDs, then moving onto a dual-boot Ubuntu 6.06 install. During the Windows Vista era, Ubuntu was my daily-driver. During the Windows 8 era, I split my time between Arch Linux and Debian. I don’t want to waste a bunch of time detailing every Linux experience I’ve had, just know that I’ve been here before and I’m not new to the world of Linux.

The last time I left Linux was for two reasons:

Windows 10 was good.

I was tired of streaming my games from a Windows PC in the other room.

The First Hurdle: Bitlocker

My Windows install uses Bitlocker, Microsoft’s drive-encryption technology. This encryption tech is tempermental. If anything changes with the system, it stops booting and requires you to put in a very long drive-recovery-code (essentially a boot password). Apparently this happened because I was chain-loading Grub→Windows and Bitlocker didn’t like that. After suspending and un-suspending bitlocker protection and never chain-loading Grub into the Windows boot loader, this problem went away.

I actually thought this would be a bigger problem, but I’m just not booting into Windows for much of anything anymore.

What Works

The Basics

The days of Linux installs not recognizing hardware seems to be over (at least for me). Everything on my system just worked out of the box. Adding NVIDIA drivers wasn’t as easy as Ubuntu or Linux Mint makes it, but a brief glance at the Debian Wiki let me get some updated knowledge and walked me through the install process.

Keep in mind, this isn’t a complaint, this is praise. I chose Debian because I wanted more control than Ubuntu and less fiddling than Arch. This is the perfect amount of fiddling for me.

Gaming

Thanks to Steam and Proton, most games just work (honesty, every game I’ve tried worked perfectly, I just find it hard to claim all games work). Even non-Steam games can be added to your library and use Proton (I run the GOG version of Cyberpunk 2077 this way). Very little fiddling needed. As a bonus, most games come with a 10-20 FPS increase running under Proton.

Back in the day, if you wanted to see if a game worked under Wine, it was a lot of searching the internet in deep Linux forums, compiling wine hacks yourself, and trying shit to see if it worked. Rinse and repeat. Today, we’re a bit more civilized, we crowdsource that shit with ProtonDB. Wanna know if your game works on Linux? Go there, search, find out. If there are launch flags or other tweaks to make, they’ll be listed.

Getting mods to work with my GOG Cyberpunk install needed one of these launch options. After that, works just as good as Windows (but with a bonus slight FPS increase).

Accessing Bitlocker-encrypted Drives

I was very surprised buy this. Apparently you can just click to mount Bitlocker drives in modern Linux systems. It just works:

Just use your BitLocker Recovery Key as the password (dashes-included) and the drive unlocks.

What Kinda Works

Sunshine Streaming

I remote into my desktop probably 400 times per day (slight exaggeration). I have an iPad that I use as a thin-client to access my desktop. It effectively means I can walk around the house and still use my PC. In the middle of a 6-hour gaming retrospective on YouTube and don’t want to give up the indomitable uBlock Origin? Just remote in and walk away from your desk without missing a beat.

Sunshine makes this super easy. On Windows.

On Linux, there are some troublesome issues:

The default Debian package does not install the systemd-user service file, so auto-starting Sunshine on graphical-session login simply does not work.

If you’ve configured your monitors to sleep after a time, Sunshine does not wake them up (it does on Windows, though). Instead, you get a connection error.

To solve the first issue, I wrote a cheeky bash script:

#!/bin/bash

/usr/bin/sleep 10
/usr/bin/sunshine

This waits until my KDE session is good and ready, then launches Sunshine. The “proper” way to solve this problem is just to make the systemd service file is installed, but this was fast and it worked. I added this to my KDE autostart list and its been working perfectly.

To solve the second problem, I wrote a tiny service called Sunrise that watches for “monitor is missing” errors, then wakes the monitor and restarts Sunshine.

https://github.com/samurailink3/sunrise

After that brief journey into software development, Sunshine is working well enough to function as a daily driver.

What Doesn’t Work

Screen Sharing/Recording

It ain’t all perfect though. Sharing full-screen apps on Discord via Wayland results in the stream becoming frame-limited and low-resolution after a few minutes. Recording full screen apps on OBS results in the game starting to screen-tear and the frame rate getting very choppy. Its pretty disorienting to look at. There are some troubleshooting steps I have yet to try, particularly looking into compiling OBS myself and using obs-vkcapture. Something to dig into for the future.

That said, Windows 11 can’t game+record at the same time, so I’m not any worse off.

Thoughts on KDE Plasma

I was always a Gnome user. I really appreciated the “simple by default, but very customizable” Gnome 2. Gnome 3 was a disappointment, but with enough tweaks, config files, fragile extensions, and tears, I was able to make it work. This time I decided to give KDE Plasma a full try.

I always shied away from KDE because it was “too big”. Too much by default. I wanted to start simple and add complication, not start with complication and pare it down until it got simpler. Turns out, my past fears are just unfounded with modern KDE. KDE is perfectly usable and simple out of the box. The experience feels a lot like Gnome 2. If you just want a default system, KDE works perfectly, if you want to customize the hell out of it: KDE still works perfectly.

If you hate how Windows 11 fucked with your right-click menu, I’ve got great news: KDE lets you customize it, easily. No shell scripts required, just go into the “configure” menu and its there:

Issues Endemic to Linux

I can’t stop tinkering. Its a problem. It takes a concentrated effort for me to not tweak and optimize and customize my setup instead of just using my setup. When I was on Windows, this was easy: The computer wasn’t really mine, it was Microsoft’s.

There are so many “black boxes” on Windows systems. You can search around the internet for solutions, maybe do some debugging, maybe dive into eventvwr, but with some problems, eventually you just hit a wall and hope the problem goes away.

Linux doesn’t have this problem (for the most part, proprietary software still exists over here). Just about any problem has logs, debugging information, and a small army of turbo-nerd-tinkerers who ran into the exact same problem you did. The power and possibilities are intoxicating.

The main reason I left Arch for Debian in the first place was because I was tired of getting sucked into tinkering with my computer when I should have been using my computer. This is still a problem with me and Debian, just a bit less since so much works out of the box.

Just know, if you’re the same kind of tech person I am, you may need to be extra-vigilant about intentional usage.

To Summarize

While my most recent experience hasn’t been perfect (and it never is), what’s here is more than good-enough, and certainly better than my Windows 11 experience. I left Linux for gaming, and now that gaming is on Linux, I don’t see a lot of reasons to go back to Windows.

🦋 Interact with this post on Bluesky:

https://bsky.app/profile/samurailink3.com/post/3m4bxqgqkpc2t

The Best Game Clipping Setup

2025-09-02T00:00:00Z

I’m gonna try some YouTube stuff for a while. A lot of my projects are kinda cool and I want to talk about them and maybe inspire people to build stuff for themselves too.

Download this Video (Right-Click, Save-Link As): https://s3.samurailink3.com/tom-webster-videos/TomWebster-TheBestClippingSetup.mp4

Things that make me uncomfortable: Missionaries vs Mercenaries

2025-03-11T00:00:00Z

I want to talk about something that makes me professionally uncomfortable: Missionaries vs Mercenaries.

I’ve worked for a few larger tech firms over my career and have experienced both sides of this coin rather viscerally. Before I get into how these two concepts play into the larger organization, let’s take a look at what they are:

Missionaries - People who take the job because they enjoy the work. Missionaries aren’t in it for the money or prestige, they’re in it for the work itself, the challenge, because they believe in the vision. Missionaries largely thrive on intrinsic rewards.

Mercenaries - People who take the job
because of
the extrinsic rewards, aka: They’re in it for the money/prestige. The work and mission don’t really matter, they’re gonna do a good job because it pays well and they want to keep that gravy-train rolling.

I’m gonna try to keep this post generic, if you want to compare this article to my Untitled and draw conclusions about which company is which, feel free. Just know that my intent isn’t to disparage or promote one company over another. If given the opportunity, I wouldn’t work for either company today. One other note, this post talks about money, a lot. I want you to know I understand that having this “debate” at all comes from a place of extreme privilege. A lot of people would be lucky to have a “problem” like this.

The missionary company was a weird place. Pretty cult-like, but that mostly resulted in better experiences for the users. The job paid very well compared to all jobs, but was actually pretty poor compared to other tech jobs of the same caliber. People successful at this company are hired as Staff/Principal roles at other firms. Ultimately, the people that were there were underpaid for the job they were doing.

This was by design. According to longtime employees and leadership, the “Missionary vs Mercenary” problem was “solved” by under-paying. It ensured the people at the company weren’t in it for the money. If they wanted money, they could find it easier at other companies. The people here were in it for the mission, for the customers, for the work. They couldn’t be in it for the money, the money wasn’t there.

This was bullshit, I knew it, everyone around me knew it. The whole “Missionaries vs Mercenaries” argument was an excuse to pay people less than they were worth. Here’s the part that makes me uncomfortable though: It worked.

It’s gross to look back and admit this, but, yeah, it worked. The people I worked with at missionary company largely didn’t care about the paycheck. It was hard work full of challenging problems, burnout, sociopathic leadership, and anti-employee rhetoric and systems. But people stayed because the work was so engrossing. Years later, I’m still referencing old projects and lessons learned there. I’m still friends with many people I met, and they’re still among the very best people I’ve ever worked with.

I ended up leaving missionary company to work at mercenary company. Mostly due to burn-out, but it helped that mercenary company offered to double my salary, give me unlimited time off, and allow me to work from wherever I wanted. At this time, I never looked kindly on the “Missionary vs Mercenary” debate. It was a line given by company leadership to justify underpaying their workforce. It was bullshit, right?

Working for mercenary company was extremely enlightening for all the wrong reasons. Within the first month, I understood what happens to companies that fall far into that mercenary spectrum. People were paid extremely well and the benefits were outlandish. It was pretty insane, comparatively. I was working less and getting paid more than I ever had before. I wondered how this could be sustainable. Then the honeymoon period wore off and I realized: It wasn’t.

The company was suffering. Everything around me was lazily constructed. Hardly anyone took pride in their work, many people openly despised what they were building, but the work continued. No one fought for lower tech-debt, no one strove to change the company, leadership was completely absent. The excuse was “Mercenary company is a grass-roots type of place, we rely on teams to set roadmaps and set direction”. This meant that the leaf-node teams ended up running things without any sense of collaboration, wider vision, or cohesive direction. Teams largely built what was easy without any sense of what the company or customers needed. They built purely to justify their own existence and that’s it.

This begs the question: Why have leadership at all if they’re just going to bury their heads in the sand? The company would have been better off without any senior leadership at all. The people running the company were also caught up in the mercenary-centric “rest and vest” cycle.

This type of thinking was a constant problem for me. I was interested in good engineering, building sustainable solutions to real problems. For the most part, the people around me were interested in playing politics to justify their paychecks. No one gave a shit about the customer. No one gave a shit about the product. Everyone gave a shit about the stock price. The mercenaries were running the show and no one in leadership was inconvenienced enough to stop them.

Mercenary company was directionless and failing. Instead of taking a hard look at what their customers wanted or needed, they ended up choosing to build something easier. A shortcut to more money. They chose poorly because they didn’t care about the work and they didn’t care about their customers. They cared about the paycheck. So they built the easiest thing to justify that paycheck.

Here’s the part that makes me uncomfortable: Mercenary company did the “right thing” by paying people well and offering stellar benefits, but it attracted exactly the wrong type of person. It attracted vultures and burn-out refugees (👋). The vultures ended up running the show and destroying the company from the inside-out. Missionary company did the “wrong thing” and made excuses to pay people poorly, but it attracted the right type of person. It attracted people who wanted to build better experiences for customers. Largely, those people are chewed up and spat out after the company gets what they can out of them before significant burnout sets in.

I’ve tried to come to a conclusion here a few times. This draft has been in my folder for months. Ultimately, I’m just frustrated that doing the “right thing” (albeit, poorly) resulted in such dire conclusions. And I’m frustrated that doing the “wrong thing” keeps working.

Personally, I believe you can pay people well and curate a missionary culture without devolving as long as you have good leadership that cares about the customer and the company (in that order).

🦋 Interact with this post on Bluesky:

https://bsky.app/profile/samurailink3.com/post/3lk4eatnfz222

Stupid Slicer Tricks: Model Mashup

2025-02-11T00:00:00Z

Sometimes you don’t need a full CAD workflow to make modifications to a model, your slicer is capable of some truly amazing feats! Here’s a story about a time where I had a model that I loved that didn’t quite meet my requirements and a remix that also didn’t meet my requirements. The “only” solution was to mash up the two models to make something a bit more customized.

I’ve been trying to upgrade my domains of nerddom and one area I’ve always been mostly-blind to is the physical craft of electronics. I know just enough to be dangerous and spot obvious problems (after they’ve combusted), but I’ve never delved into the practice of soldering or building/repairing my own electronics. Luckily, I have friends well-versed in this domain. I bought a PINECIL and had a friend walk me through the very basics of soldering.

He recommended this PINECIL case on Printables, which is an extremely nice model. Functional and beautiful. The only issue with it is: I’m not gonna use those extra iron tips. While I have another tip, I have neither the experience nor knowledge to use them effectively yet. I’m still an absolute beginner at this stage, I just don’t know what I don’t know.

My friend recommended a flux pen for my beginner soldering kit, but the default case didn’t come with a spot for it. Luckily, this remix of the PINECIL case had a socket that fit perfectly, but it was mashed up with the soldering iron tip holder that I didn’t need. I wanted to blend the models together so I could replace the spare-tip holder with the flux pen socket. Normally, I’d just take this out to TinkerCAD, but I wanted to see if I could get away with a more “low-tech” solution.

For better or worse, that low-tech solution was some goblin engineering shit with PrusaSlicer:

What have I done??

Instead of solving this problem “correctly”, I decided to solve it “good enough”. PrusaSlicer has a great feature called “Negative Volume Modifiers”. You can do a lot of different functions with these simple shapes, even adding text to models easily. This particular modifier just removed areas of a model, kinda like a big boxy 3D eraser.

Let’s dive into what this mess actually does:

The first model uses negative volumes to remove the spare tip holders from the model. It isn’t perfect and leaves some gaps in the original filet of the case, but it’s good enough:

This leaves us a space to add the flux pen socket!

The second model just removes the entire case around the flux pen socket, leaving just the socket behind:

Now, we just gotta overlay those models just right and….

Voila! We’ve now mashed up both of these models to come up with a jankier third option. Slicing this model does result in some problematic g-code and PrusaSlicer isn’t too happy about it:

Sadly, this is actually exactly what we want. We have two different models that should be printed on top of each other. The only question was: Would this print correctly? Let’s take a closer look at the g-code preview and try to discern what’s going on.

This is just a guess, but it appears that one layer of the model is printed twice in the same location. Obviously, this isn’t optimal, but as long as it doesn’t fail the print completely, it should be fine. This is actually the first time I’m seeing this type of error in PrusaSlicer. Lucky for me, PrusaSlicer complains, but doesn’t actually stop me from doing some absolutely hacky bullshit.

I absolutely love this. While it may be conventional to just hard-stop the user from doing something dumb, the fact that it complains, then allows the behavior anyway is fucking fantastic. This is how open-source software should work: Tell me what I’m doing is dumb as hell, but then let me do it anyway, consequences be damned.

I sent the job off to the printer and watched as it double-printed the flux pen socket. The nozzle tried to put down molten plastic into already-solidified plastic, and that didn’t work too well. It squiggled out and made a small mess, but didn’t actually fail or nozzle-crash. The next layer went down perfectly well. No complaints, no issues. It just did the job.

Check out the final product to see the results:

Don’t get me wrong, this is absolutely a hack/goblin engineering/mess, but the bottom line is that IT WORKS. Your projects may not need so many messy hacks or slicer trickery, but its always good to have these skills in your back pocket. Even if its not the “right way” to do something, its often the faster way.

For more slicer trickery, check out these great videos from some of my favorite 3D printing YouTubers:

https://www.youtube.com/watch?v=o-NYbUFzxLw

https://www.youtube.com/watch?v=DaU8-2XadIE

https://www.youtube.com/watch?v=iziTcOLKfFc

If you would like to print this model (or the remix), check out the following links:

https://www.printables.com/model/345083-rugged-multipart-pinecilts100ts80-case-v2

https://www.printables.com/model/440145-rugged-multipart-pinecilts100ts80-case-flux-pensol

🦋 Interact with this post on Bluesky:

https://bsky.app/profile/samurailink3.com/post/3lhwqkr43z22f

Why are all the publish dates “wrong”?

2024-11-22T00:00:00Z

If you’ve been following this site and/or my posts on BlueSky, you’ve probably seen projects pop up with weird dates. The best example is my Door Handle Slammer Stopper - My Stupidest Useful 3D Print posted on 2024-11-20, but with a publish date of 2024-03-05, what’s up with that?

I’d like to treat this site as part-blog/part-portfolio. For the Slammer Stopper, I finalized the design in March, but didn’t write or post about it publicly until a couple days ago. Because I view my projects as portfolio artifacts, I’d like to keep the dates accurate to when they were actually completed. It gives me (and readers) a more-accurate timeline of what I’ve worked on and when.

I’ve played around with adding separating “publish date” and “project date”, but this adds a lot of confusion around what means what to readers and around how I should the posts. In the end, I’ve decided that its fine to “lose” the data as to when the article was published, because it has pretty limited value. The real value is the timeline and content itself.

Do Dollars Make Sense for Incident Management?

2024-11-21T00:00:00Z

I did some writing for the blog on https://rootly.com/ and I’m very happy with how it turned out. Go check out the full article here:

https://rootly.com/blog/do-dollars-make-sense-for-incident-management

Software Engineering Essentials: Flags

2024-11-14T00:00:00Z

Software Engineering Essentials is a series of blog posts designed to help you get started with a wide variety of software engineering topics. This post was originally part of my Go-Twitter project, a project-based curriculum designed to take someone from “zero” to “competent” in the world of software engineering.

All writing for this post is licensed under CC-BY-4.0, while all code is licensed under the MIT license.

Flags

Flag Usage

Flags are effectively named arguments, with some extra features. Instead of needing to remember the order of your program's arguments, you can just specify the name of the flag and what that variable should be set to. Let's take a look at a simple example:

01-simple-flags/main.go:

package main

import (
	"flag"
	"fmt"
)

func main() {
	greeting := flag.String("greeting", "", "")
	name := flag.String("name", "", "")
	flag.Parse()
	fmt.Printf("%s, %s!\\n", *greeting, *name)
}

Now, if we run this program:

go run example-code/02-command-line-arguments-and-flags/02-flags/01-simple-flags/main.go
  !

Huh, that looks weird. This is because our greeting and name variables are empty. We never specified the flags. How do we know what the flags are? Flags have built-in help functionality that will display all of the options available. Most programs use -h or --help to display program usage text, including flags and arguments.

go run example-code/02-command-line-arguments-and-flags/02-flags/01-simple-flags/main.go -h
Usage of /tmp/go-build1913891522/b001/exe/main:
  -greeting string

  -name string

So now we can see that this program accepts the -greeting and -name flags. Let's set some values:

go run example-code/02-command-line-arguments-and-flags/02-flags/01-simple-flags/main.go -greeting="Sup" -name Tom
Sup, Tom!

Flag arguments can be set with some optional grammar to help avoid problems with ambiguity or spaces:

flag value
: For one-word values

flag "value with spaces or special characters"
: For multi-word values or values that contain some special characters.

flag="value"
: This is the
belt-and-suspenders
of flag declaration.

We can also specify the flags in any order:

go run example-code/02-command-line-arguments-and-flags/02-flags/01-simple-flags/main.go -name="General" -greeting="Hello There"
Hello There, General!

Or not specify a value for -name at all!

go run example-code/02-command-line-arguments-and-flags/02-flags/01-simple-flags/main.go -greeting="Hello There"
Hello There, !

We can even abuse the flags to make the program finish the meme:

go run example-code/02-command-line-arguments-and-flags/02-flags/01-simple-flags/main.go -greeting="General Kenobi\\!" -name="You are a bold one"
General Kenobi!, You are a bold one!

Defaults

Let's re-create the program that inserted profiles into a database from the end of the Command Line Arguments chapter, but with flags instead:

02-profile-saver/main.go:

package main

import (
	"flag"
	"fmt"
)

func main() {
	firstName := flag.String("first-name", "", "")
	lastName := flag.String("last-name", "", "")
	favFruit := flag.String("fruit", "", "")
	favVeg := flag.String("veg", "", "")
	favPasta := flag.String("pasta", "", "")
	favMeal := flag.String("meal", "", "")
	riceOrBeans := flag.String("rice-or-beans", "", "")
	favDesert := flag.String("desert", "", "")
	favDessert := flag.String("dessert", "", "")
	flag.Parse()

	fmt.Printf(`Profile Name: %s %s
	Rice or Beans: %s
	Favorites:
		Fruit: %s
		Vegetable: %s
		Pasta: %s
		Desert: %s
		Dessert: %s
		Meal: %s
`, *firstName, *lastName, *riceOrBeans, *favFruit, *favVeg, *favPasta, *favDesert, *favDessert, *favMeal)
}

Right now if we run this program with no flags set, we get this results:

go run example-code/02-command-line-arguments-and-flags/02-flags/02-profile-saver/main.go
Profile Name:
        Rice or Beans:
        Favorites:
                Fruit:
                Vegetable:
                Pasta:
                Desert:
                Dessert:
                Meal:

Lots of blank spaces here. We don't want to commit empty values to the database, it can introduce ambiguity. Did this person not have a favorite pasta or did we just forget to add the data? Being explicit in programming has several benefits, including clarity-of-intent, so let's add some defaults.

Default values can provide the usual options or placeholder data. Flags make this easy. For now, let's just use UNKNOWN as the profile placeholder. With the stanadrd flag package, setting defaults is easy. Let's take a look at the GoDocs for flag.String, available here:

So the second function argument allows us to specify a default value for that particular flag. Let's do that now:

02-profile-saver/main.go:

package main

import (
	"flag"
	"fmt"
)

func main() {
	firstName := flag.String("first-name", "UNKNOWN", "")
	lastName := flag.String("last-name", "UNKNOWN", "")
	favFruit := flag.String("fruit", "UNKNOWN", "")
	favVeg := flag.String("veg", "UNKNOWN", "")
	favPasta := flag.String("pasta", "UNKNOWN", "")
	favMeal := flag.String("meal", "UNKNOWN", "")
	riceOrBeans := flag.String("rice-or-beans", "UNKNOWN", "")
	favDesert := flag.String("desert", "UNKNOWN", "")
	favDessert := flag.String("dessert", "UNKNOWN", "")
	flag.Parse()

	fmt.Printf(`Profile Name: %s %s
	Rice or Beans: %s
	Favorites:
		Fruit: %s
		Vegetable: %s
		Pasta: %s
		Desert: %s
		Dessert: %s
		Meal: %s
`, *firstName, *lastName, *riceOrBeans, *favFruit, *favVeg, *favPasta, *favDesert, *favDessert, *favMeal)
}

Now when we run this program without any flags set:

go run example-code/02-command-line-arguments-and-flags/02-flags/02-profile-saver/main.go
Profile Name: UNKNOWN UNKNOWN
        Rice or Beans: UNKNOWN
        Favorites:
                Fruit: UNKNOWN
                Vegetable: UNKNOWN
                Pasta: UNKNOWN
                Desert: UNKNOWN
                Dessert: UNKNOWN
                Meal: UNKNOWN

There we go, that at least looks more complete.

Now let's actually use those flags to set some values... but wait, what were the flags again? Let's use -h to see what options we have:

go run example-code/02-command-line-arguments-and-flags/02-flags/02-profile-saver/main.go -h
Usage of /tmp/go-build261536590/b001/exe/main:
  -desert string
         (default "UNKNOWN")
  -dessert string
         (default "UNKNOWN")
  -first-name string
         (default "UNKNOWN")
  -fruit string
         (default "UNKNOWN")
  -last-name string
         (default "UNKNOWN")
  -meal string
         (default "UNKNOWN")
  -pasta string
         (default "UNKNOWN")
  -rice-or-beans string
         (default "UNKNOWN")
  -veg string
         (default "UNKNOWN")

Ah, got it. Now let's actually use these:

go run example-code/02-command-line-arguments-and-flags/02-flags/02-profile-saver/main.go -first-name Bob -last-name Sacamano -fruit Apple -veg "Green Beans" -pasta Manicotti -meal Steak -desert Sahara -dessert Sundae -ri
ce-or-beans Rice
Profile Name: Bob Sacamano
        Rice or Beans: Rice
        Favorites:
                Fruit: Apple
                Vegetable: Green Beans
                Pasta: Manicotti
                Desert: Sahara
                Dessert: Sundae
                Meal: Steak

So now we're able to print out all of the profile information using flags. Its still a lot of flags to remember, but at least we have the default help text and the order of options doesn't matter.

Help Text

As we saw above, -h is pretty helpful to understand which flags are available, what type is expected, and what the defaults are, but we can add some more context through help text. As always, reading the documentation can help us find the right place to add help text to our flags. For now, let's just add one piece of help text and see how it compares to the rest of the flags:

02-profile-saver/main.go:

package main

import (
	"flag"
	"fmt"
)

func main() {
	firstName := flag.String("first-name", "UNKNOWN", "the first name of the user profile")
	lastName := flag.String("last-name", "UNKNOWN", "")
	favFruit := flag.String("fruit", "UNKNOWN", "")
	favVeg := flag.String("veg", "UNKNOWN", "")
	favPasta := flag.String("pasta", "UNKNOWN", "")
	favMeal := flag.String("meal", "UNKNOWN", "")
	riceOrBeans := flag.String("rice-or-beans", "UNKNOWN", "")
	favDesert := flag.String("desert", "UNKNOWN", "")
	favDessert := flag.String("dessert", "UNKNOWN", "")
	flag.Parse()

	fmt.Printf(`Profile Name: %s %s
	Rice or Beans: %s
	Favorites:
		Fruit: %s
		Vegetable: %s
		Pasta: %s
		Desert: %s
		Dessert: %s
		Meal: %s
`, *firstName, *lastName, *riceOrBeans, *favFruit, *favVeg, *favPasta, *favDesert, *favDessert, *favMeal)
}

Now let's check out the help text:

go run example-code/02-command-line-arguments-and-flags/02-flags/02-profile-saver/main.go -h
Usage of /tmp/go-build1166983742/b001/exe/main:
  -desert string
         (default "UNKNOWN")
  -dessert string
         (default "UNKNOWN")
  -first-name string
        the first name of the user profile (default "UNKNOWN")
  -fruit string
         (default "UNKNOWN")
  -last-name string
         (default "UNKNOWN")
  -meal string
         (default "UNKNOWN")
  -pasta string
         (default "UNKNOWN")
  -rice-or-beans string
         (default "UNKNOWN")
  -veg string
         (default "UNKNOWN")

Neat! Now let's add the rest:

02-profile-saver/main.go:

package main

import (
	"flag"
	"fmt"
)

func main() {
	firstName := flag.String("first-name", "UNKNOWN", "the first name of the user profile")
	lastName := flag.String("last-name", "UNKNOWN", "the last name of the user profile")
	favFruit := flag.String("fruit", "UNKNOWN", "the user's favorite fruit")
	favVeg := flag.String("veg", "UNKNOWN", "the user's favorite vegetable")
	favPasta := flag.String("pasta", "UNKNOWN", "the user's favorite type of pasta")
	favMeal := flag.String("meal", "UNKNOWN", "the user's all-time favorite meal")
	riceOrBeans := flag.String("rice-or-beans", "UNKNOWN", "whether the user prefers a side of rice or beans")
	favDesert := flag.String("desert", "UNKNOWN", "the user's favorite desert (usually hot and sandy)")
	favDessert := flag.String("dessert", "UNKNOWN", "the user's favorite dessert (usually a sweet after-meal treat)")
	flag.Parse()

	fmt.Printf(`Profile Name: %s %s
	Rice or Beans: %s
	Favorites:
		Fruit: %s
		Vegetable: %s
		Pasta: %s
		Desert: %s
		Dessert: %s
		Meal: %s
`, *firstName, *lastName, *riceOrBeans, *favFruit, *favVeg, *favPasta, *favDesert, *favDessert, *favMeal)
}

And if we check out help text:

go run example-code/02-command-line-arguments-and-flags/02-flags/02-profile-saver/main.go -h
Usage of /tmp/go-build2677080627/b001/exe/main:
  -desert string
        the user's favorite desert (usually hot and sandy) (default "UNKNOWN")
  -dessert string
        the user's favorite dessert (usually a sweet after-meal treat) (default "UNKNOWN")
  -first-name string
        the first name of the user profile (default "UNKNOWN")
  -fruit string
        the user's favorite fruit (default "UNKNOWN")
  -last-name string
        the last name of the user profile (default "UNKNOWN")
  -meal string
        the user's all-time favorite meal (default "UNKNOWN")
  -pasta string
        the user's favorite type of pasta (default "UNKNOWN")
  -rice-or-beans string
        whether the user prefers a side of rice or beans (default "UNKNOWN")
  -veg string
        the user's favorite vegetable (default "UNKNOWN")

So much better. Now our program has clear flagged arguments, defaults set, and some help text to explain what each flag is intended for. However, this could be cleaned up a bit more. To clean up the help text, let's dig into constants.

Constants

Constants work very similarly to variables, but with one critical difference: They cannot be changed at runtime. Constants are set in your source code and compiled-in, after that, the value cannot be changed. Constants are helpful to document and organize variables that control large pieces of your application or that are used in a variety of places, but the values won't change.

Let's dig in with an example. Let's say you were making a program that talks to a website to get information. The functions you write to talk to the website are all going to use the same address over and over and over again. Instead of typing https://www.example.com over and over again, you can put this address in a constant declaration near the top of your file, then just reference it using the constant name:

package main

import (
	"fmt"
)

const (
       website = ""
)

func main() {
       fmt.Println(website)
}

So constants work kinda like variables, but let's see what happens when we try to change the value in our main function:

package main

import (
	"fmt"
)

const (
	website = ""
)

func main() {
	fmt.Println(website)
	website = "A new value"
	fmt.Println(website)
}

When we run it, we get this:

main.go:13:2: cannot assign to website (untyped string constant "")

The constants must remain constant. Trying to change them results in the program refusing to build.

So, constants can be useful to help avoid re-typing, but they can also help generally clean up your code. Right now in our profile-saver program, we have a lot of loose help text that we can clean up by moving those help strings from the flag.String functions into a constant declaration. So we can turn this:

func main() {
	firstName := flag.String("first-name", "UNKNOWN", "the first name of the user profile")
	lastName := flag.String("last-name", "UNKNOWN", "the last name of the user profile")
	favFruit := flag.String("fruit", "UNKNOWN", "the user's favorite fruit")
	favVeg := flag.String("veg", "UNKNOWN", "the user's favorite vegetable")
	favPasta := flag.String("pasta", "UNKNOWN", "the user's favorite type of pasta")
	favMeal := flag.String("meal", "UNKNOWN", "the user's all-time favorite meal")
	riceOrBeans := flag.String("rice-or-beans", "UNKNOWN", "whether the user prefers a side of rice or beans")
	favDesert := flag.String("desert", "UNKNOWN", "the user's favorite desert (usually hot and sandy)")
	favDessert := flag.String("dessert", "UNKNOWN", "the user's favorite dessert (usually a sweet after-meal treat)")
...

Into this:

const (
	firstNameHelp   = "the first name of the user profile"
	lastNameHelp    = "the last name of the user profile"
	fruitHelp       = "the user's favorite fruit"
	vegHelp         = "the user's favorite vegetable"
	pastaHelp       = "the user's favorite type of pasta"
	mealHelp        = "the user's all-time favorite meal"
	riceOrBeansHelp = "whether the user prefers a side of rice or beans"
	desertHelp      = "the user's favorite desert (usually hot and sandy)"
	dessertHelp     = "the user's favorite dessert (usually a sweet after-meal treat)"
)

func main() {
	firstName := flag.String("first-name", "UNKNOWN", firstNameHelp)
	lastName := flag.String("last-name", "UNKNOWN", lastNameHelp)
	favFruit := flag.String("fruit", "UNKNOWN", fruitHelp)
	favVeg := flag.String("veg", "UNKNOWN", vegHelp)
	favPasta := flag.String("pasta", "UNKNOWN", pastaHelp)
	favMeal := flag.String("meal", "UNKNOWN", mealHelp)
	riceOrBeans := flag.String("rice-or-beans", "UNKNOWN", riceOrBeansHelp)
	favDesert := flag.String("desert", "UNKNOWN", desertHelp)
	favDessert := flag.String("dessert", "UNKNOWN", dessertHelp)
...

There's still a lot of text, but its a bit more organized and easier to work with. This is one of the nicest bonus features of constants: They make great organizational tools. If you have certain aspects of your program that can be tuned by yourself or another developer, it may be a good idea to put them in a const declaration at the top of the file so they're easy to access and conveniently grouped.

Its worth keeping in mind that not everything can be a constant. Due to the way the Go compiler works, complex expressions cannot be pre-evaluated. Said another way: Constants are baked into your application when you run go build. According to the Go language spec, the only valid constant types are:

Runes (characters)

Strings

Booleans (
true
or
false
)

Numeric types (
int
s,
float
s, etc...)

If you want the same style of organization for types that don't work as constants, you can use a var declaration instead:

var (
	aMap = map[int]string{
		1: "one",
		2: "two",
		3: "three",
	}
)

Appendix and References

References

GoDocs: flag.String

Go Language Reference: Constants

Appendix

How Spaces Can Affect Flags

go run example-code/02-command-line-arguments-and-flags/02-flags/01-simple-flags/main.go -greeting Hello There -name General
Hello, !

go run example-code/02-command-line-arguments-and-flags/02-flags/01-simple-flags/main.go -greeting "Hello There" -name General
Hello There, General!

go run example-code/02-command-line-arguments-and-flags/02-flags/01-simple-flags/main.go -greeting="Hello There" -name General
Hello There, General!

Software Engineering Essentials: Command Line Arguments

2024-11-13T00:00:00Z

All writing for this post is licensed under CC-BY-4.0, while all code is licensed under the MIT license.

Command Line Arguments

What are command line arguments?

Command line arguments are one way to pass user input into your application. Let's take a look at the common Unix utility ls. ls is a small application that lists files and directories, just like double-clicking on a folder in Windows Explorer, ls allows you to peer into directories and get additional information about files, like ownership information, size, last modification timestamps, and more. ls, like many command line applications, can take in arguments:

ls some-directory

In this example ls is the application you are running and some-directory is the argument. What you're asking ls to do is give you a listing of all files and folders inside of some-directory.

How can my program use arguments?

Because programming is generally open-ended, you can utilize command line arguments to control any aspect of your program. You could use an argument to control which IP address and port your application listens for requests on, or what to print, or if an operation should target your test or production environments. Let's take a look at a simple example:

Here's a simple Go program that will print a person's name and age on the command line:

01-simple-arguments/main.go:

package main

import (
    "fmt"
    "os"
)

func main() {
    fmt.Printf("My name is %s and my age is %s.", os.Args[1], os.Args[2])
}

So if we run go run example-code/02-command-line-arguments-and-flags/01-command-line-arguments/01-simple-arguments/main.go Bob 99, we'll see: My name is Bob and my age is 99.

In this example, we use the os package to get an array of arguments provided on the command line. Arrays in Go start at 0, so we're actually printing the second and third argument. The first argument is the location of the program we're running. Since we're using go run, it will be in a temporary, auto-generated location. Let's add this block of code to our program and look at each argument individually:

fmt.Println("Our program's arguments:")
for i, arg := range os.Args {
    fmt.Printf("os.Args[%d]: '%s'\\n", i, arg)
}

This code will print out each argument and its number:

Our program's arguments:
os.Args[0]: '/tmp/go-build201851007/b001/exe/main'
os.Args[1]: 'Bob'
os.Args[2]: '99'

So /tmp/go-build201851007/b001/exe/main is the temporary compiled version of our program, made by the go run command. The other arguments, Bob and 99 are the arguments we provided on the command line.

So, what happens if we provide less than 2 arguments to our program?

go run example-code/02-command-line-arguments-and-flags/01-command-line-arguments/01-simple-arguments/main.go Bob
panic: runtime error: index out of range [2] with length 2

goroutine 1 [running]:
main.main()
        /home/samurailink3/git/go-twitter/example-code/02-command-line-arguments-and-flags/01-command-line-arguments/01-simple-arguments/main.go:9 +0x21c
exit status 2

Uh oh... panic: runtime error: index out of range [2] with length 2... That doesn't look good. What happened is we tried to access a variable that was outside of the array. Here's a simple diagram of the os.Args array and what we're trying to access:

          Arg 0: Our program         Arg 1: Our provided name     Arg 2: What we're trying to access
                 |                           |                                     |
                 v                           v                                     v
[ "/tmp/go-build201851007/b001/exe/main",  "Bob" ]

The os.Args array only contains 2 items (os.Args[0] and os.Args[1]), but we're trying to access something in the third place (os.Args[2]), beyond the end of the array. This is an issue, so the code panics. How can we defend against that? We want to avoid panicing and let the user know they're missing a required field.

The len check:

if len(os.Args) < 3 {
    // Do something here
}

We can get the number of items present in the os.Args array and do something if we don't have enough. First, let's print out a helpful message for the user:

if len(os.Args) < 3 {
    fmt.Println("This program requires two arguments: Name and Age, you have", len(os.Args)-1)
}

When we run this with only the first argument, we get:

go run example-code/02-command-line-arguments-and-flags/01-command-line-arguments/01-simple-arguments/main.go Bob
This program requires two arguments: Name and Age, you have 1
panic: runtime error: index out of range [2] with length 2

goroutine 1 [running]:
main.main()
        /home/samurailink3/git/go-twitter/example-code/02-command-line-arguments-and-flags/01-command-line-arguments/01-simple-arguments/main.go:13 +0x29b
exit status 2

Generally, we don't want to show panics to the user, so let's exit with a non-successful error code (to learn more about error codes, check out the Advanced Bash-Scripting Guide):

	if len(os.Args) < 3 {
		fmt.Println("This program requires two arguments: Name and Age, you have", len(os.Args)-1)
		// See "Advanced Bash-Scripting Guide: Exit Codes With Special Meanings"
		// in the References section for why we use "2" here.
		os.Exit(2)
	}

Now when we run our program with the missing argument, we get:

go run example-code/02-command-line-arguments-and-flags/01-command-line-arguments/01-simple-arguments/main.go Bob
This program requires two arguments: Name and Age, you have 1
exit status 2

That's way cleaner. Now if we run it with the right number of arguments, we see:

go run example-code/02-command-line-arguments-and-flags/01-command-line-arguments/01-simple-arguments/main.go Bob 99
My name is Bob and my age is 99.
Our program's arguments:
os.Args[0]: '/tmp/go-build1771918657/b001/exe/main'
os.Args[1]: 'Bob'
os.Args[2]: '99'

When should I use arguments?

Arguments are best used when an application has a limited number of distinct options or your program operates on an unlimited number of the same argument. Let's expand that previous statement:

So git is a great example of having a limited (and segmented) number of distinct options. It can do a lot, but the options are segmented by sub-command. So, something git branch would have pretty simple arguments, like git branch -D branch-name and git branch --track local-branch remote-branch. There are a couple of arguments to keep in your head, not too bad.

Another program we talked about earlier, ls, is a great example of having an unlimited number of the same argument. So you can run ls with zero arguments, which just shows the files and folders present in your current directory, but we can also run ls some-directory and-another-one but-also-a-third to see what's inside those three distinct directories. ls supports an unlimited number of arguments, but each one does the same thing, so its not hard to remember or think about.

Let's say you had a program to insert profile information into a database. You track the following information about people:

First Name

Last Name

Favorite Fruit

Favorite Vegetable

Favorite Pasta

Favorite Meal

Rice or Beans

Favorite Desert

Favorite Dessert

Your application in use may look like this:

new-profile Bob Sacamano Apple GreenBeans Manicotti Steak Sahara Sundae

Your users will need to keep this whole list in their heads in order. That's a pretty bad user experience and its likely that someone will forget a field or worse, get the order of the arguments wrong. This would add data into the wrong fields in your database. There are too many options to keep track of here, arguments aren't a good choice for this program. Case-in-point: The above example forgets the "Rice or Beans" field. Did you catch it?

This application would be perfect for flags, so we'll cover that in the next section.

Appendix and References

References

Advanced Bash-Scripting Guide: Exit Codes With Special Meanings

Software Engineering Essentials: Working with GitLab (and GitHub)

2024-11-12T00:00:00Z

All writing for this post is licensed under CC-BY-4.0, while all code is licensed under the MIT license.

GitLab

Branch Etiquette

Git makes working in groups much easier than manually copying and pasting code together from multiple sources. A centralized Git hosting service can make it even easier. Most of the time when multiple people work on a project, changes are committed to feature-specific branches. These can be bug-fixes, new features, refactors, or anything else. The important thing to keep in mind is to keep your changes organized in the proper branches.

If you're working on a bug-fix on a branch named front-page-css-bugfix, don't pollute that branch with unnecessary changes like fixing test cases in an unrelated function. The changes in a branch should correspond to that branch. If you really want to do that work and save it somewhere, feel free to create a new branch. Branches are free and easy to use, feel free to make new ones as you need.

Merge Requests

Merge Requests (or Pull Requests in GitHub lingo) are a mechanism in most Git hosting services designed to make it easier to handle merging in new changes. While Git has a lot of tools for managing changes and merges, the web interface is a bit easier to get started with for newcomers.

More important than the change itself is the Code Review process that merge requests assist with. Chances are, your merge request won't be accepted immediately and without question. Most of the time, we have something to fix or something to change. The merge request view allows other team members to comment on your diff and even highlight individual lines or blocks of changes to leave comments. If you've ever used the "Track Changes" feature of Microsoft Office product, you'll be well-acquainted with this interface.

When a merge request is accepted, your commits in the merge request will be applied to the branch your request targets (usually the main development branch). Then, whenever people fetch and pull changes, your commits will be pulled down to their local repositories. This keeps everyone in lock-step with each other while you all work on the same codebase.

Your old branches should be deleted once merged. This isn't a technical requirement, it just keeps things clean.

Protecting Branches

Because the main development branch is used for collaboration and keeping everyone on the project on the same page, you usually don't want to commit changes directly to it. Instead, you commit changes to the main development branch through merge requests. This ensures that the commits people are adding are reviewed and communicated before they are added to the main branch.

Most Git hosting services have a feature that will allow you to protect certain branches. Protecting a branch can prevent things like deletion and/or directly pushing changes onto that branch. Instead changes are added in through merge requests.

Software Engineering Essentials: Version Control with Git

2024-11-11T00:00:00Z

All writing for this post is licensed under CC-BY-4.0, while all code is licensed under the MIT license.

Git

What is Git?

"Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency."

Git is an application designed to manage your source code and make it easy to keep version history, but why would you want this? Programming gets messy, especially in large projects. Let's say you're testing an experimental bugfix, you may be tempted to copy/paste your code into a different folder and name it, my-project_bugfix, but what happens when you have my-project_bugfix2 or my-project_bugfix_real. Copying around folders of source code might work initially, but will quickly get messy, especially if you need to work with other people. Git provides a system to help keep your code organized, easy to work with, and easy to collaborate on.

A Git repository is essentially a place where you can store files to track and share changes to those files. Git repositories (or repos, for short) are usually used to store and track changes to source code files.

Installing Git

Git is available on a wide variety of platforms and you can find an installer here. There are some options to pick during setup:

Select Components:
Default

Choosing the default editor used by Git:
Use Visual Studio Code as Git's default editor

Adjusting the name of the initial branch in new repositories:
Override the default branch name for new repositories:
main

Adjusting your PATH environment:
Git from the command line and also from 3rd-party software

Choosing the SSH executable:
Use external OpenSSH

Choosing HTTPS transport backend:
UUse the OpenSSL library

Configuring the line ending conversions:
Checkout as-is, commit as-is

Configuring the terminal emulator to use with Git Bash:
Use MinTTY (the default terminal of MSYS2)

Choose the default behavior of
git pull
:
Only ever fast-forward

Choose a credential helper:
Git Credential Manager

Configuring extra options:
Check both
Enable file system caching
and
Enable symbolic links

Configuring experimental options:
Leave all options unchecked

Configuring SSH and Setting Up Your GitLab Account

First register for GitLab. Next, we need to create an SSH key so we can authenticate to GitLab.

Press
Windows+R
to bring up the "Run" dialog box.

Type
powershell
and press
Enter
to open up the PowerShell prompt.

Type
ssh-keygen
and press
Enter
to start the key creation process

Click here to go to your GitLab User Settings to manage your SSH keys. In the Add an SSH key section, copy and paste the entire public key file from before into the Key text box, then click Add key.

Now bring up the powershell window you had open before and use the ssh-add command. Type your key passphrase and press Enter. Remember: Your passphrase will not be shown here as you type it.

This command will add your key to an ssh-agent. This program just makes it easier to use your key. Instead of needing to type your passphrase every time you use the key, you just add it to the agent and use the passphrase only once. You'll need to do this each time the computer reboots.

You can see what keys the agent has with the command: ssh-add -l

You can remove keys from the agent, thereby "re-locking" them, with the command: ssh-add -D

How Git views the World

A Brief Introduction to Hashes

Git's view of the world is through hashes. A hash function is a way to "boil down" data to a fixed-length value. This sounds complex, but its simple in practice. Let's look at the current hash of this file I'm writing now:

~ sha1sum Handouts/01-source-code-version-control-and-hosting/01-git.md
0b4597c1d9294a633ea584d715ce6681e57cb82a  Handouts/01-source-code-version-control-and-hosting/01-git.md

But as I write more, change the content, and save, the hash will change:

~ sha1sum Handouts/01-source-code-version-control-and-hosting/01-git.md
8393d5018367212dcfe4fa6e477fdf5deff28576  Handouts/01-source-code-version-control-and-hosting/01-git.md

So hashing is a way to take data of any amount and get a fixed-length value that is unique to that data's content. Some practical uses involve things like error checking, data deduplication, and protection against corruption or tampering. Git uses hashes to identify individual objects like files, directories, references, commits, and more.

Diffs on Diffs on Diffs

Git heavily utilizes the concept of diffs as a way to understand the differences between files (and multiple historical versions of the same file). This makes merges easier to manage and makes for more efficient file storage.

Let's check out diff in action:

I have two files, a.txt and b.txt:

a.txt:

Test
This is file a

b.txt:

Test
This is file b

Here's what I get when I run diff a.txt b.txt:

2c2
< This is file a
---
> This is file b

diff only shows us the differences between the files. Git can use this to figure out what changed between different objects. A commit in Git is like taking a snapshot of the diff of the entire repository. As you make more commits, you are creating historical records of what changed in that repository at that moment in time. By playing the diffs in reverse, you can effectively wind back the clock and travel to past, undoing changes.

So how does git "play back" those diffs? This is an operation called patching. A patch is a series of changes intended to be applied to an existing system.

So if I had a program and someone found a typo: hello.go

package main

import "fmt"

func main() {
	fmt.Println("henlo world")
}

They could send me a small patch to fix it:

typo-fix.patch

--- hello.go	2023-01-01 21:25:05.694853862 +0000
+++ hello.go	2023-01-01 21:26:15.863385402 +0000
@@ -3,5 +3,5 @@
 import "fmt"

 func main() {
-	fmt.Println("henlo world")
+	fmt.Println("hello world")
 }

And I could use patch hello.go typo-fix.patch or git apply typo-fix.patch to apply the diff. Now my application will print hello world!

A Git repository is just hashed objects and diffs stacked on top of diffs.

Extra Reading

If you enjoyed this section, feel free to check out Git Internals chapter in the official book for an ever deeper dive.

Using Git on the Command Line

Git is an open source application and there are a ton of products and graphical interfaces designed to make working with it easier. While these can work well in some straight-forward circumstances, they all tend to fall apart pretty badly when things go off the "happy path", and it can be difficult to get back to a good state. For this reason, we'll focus on using the command-line version of Git. Once you're comfortable with this interface, you can absolutely use any Git-compatible application you want, including VS Code's excellent Git integration, just don't skip learning the CLI basics first.

Project Creation

A Git repository is just a folder with another .git folder inside of it. In the .git folder are a bunch of directories and files that Git uses to make sense of your codebase. These include hashed objects, diffs, and metadata used to keep things organized and human-compatible. You shouldn't need to dive into this directory or change anything.

The command to instantiate a new Git repository on your local system is: git init my-project-name

Once you run this command, you'll need a folder named my-project-name. All of your code, as well as anything you want to keep under version control (like documentation files), should go here.

Cloning an Existing Project

Git is a distributed system, which means projects don't have to live purely on your local system. Many programmers utilize a Git-hosting service to store and share their code with other contributors. These include services like GitHub, GitLab, and Bitbucket. Don't worry about signing up for any of these services just yet, the next section will walk you through the basics of GitLab.

Git hosting services give you an easy way to interact with other contributors, report and accept issues, manage merge requests, and most importantly: Share your code with the world. Its important to understand that Git is a distributed system by default, you don't need these hosting sites to share or collaborate on code, but they do make it easier.

You can think about Git hosting services like YouTube or Vimeo. You can absolutely share video files with people or even make your own video hosting service, but using someone else's service is so much easier. It is important to keep in mind that Git is not GitHub. GitHub can be used to host a Git repository, just like YouTube can be used to host a video. The hosting service and the core technology are two different things.

Most Git hosting sites will give you one or two Clone addresses you can use to copy down the project locally. Most often these addresses are SSH and/or HTTPS links. You can use these addresses in this command:

git clone >


or like this:
git clone git@github.com:torvalds/linux.git
Typically, an https repository link is going to be read-only. You can pull
down changes, but won't be able to push your own changes (unless you set up
HTTPS authentication). An ssh repository link (the one that looks like
git@gitlab) is typically going to be read+write. You will be able to push
your changes to the remote repository.
This will clone the repository hosted on GitHub, by the user torvalds, with
the project name linux, into a directory on your local system called linux.
After you run that command, you can browse the Linux source code on your own
system. Because Git is decentralized, you obtain a full copy of the source
code repository, including history, commits, branches, tags, and other Git
metadata. If you want, you can see what the code looked like last year, or even
before then. You can see when certain features were merged in, or when a certain
version-number was tagged.
One thing to keep in mind is some data found on the Git host site isn't
included with the repository. These would be things like merge request
discussions, issues and bug reports, and project milestones and planning
features. By default, Git does not track these items in the repository, so they
are instead hosted directly by the Git hosting service.
Viewing and Committing Changes
Git's version control isn't automated, users need to manually make "checkpoints"
of their changes to let Git know "these changes are important to track". In Git,
these "checkpoints" are called commits.
A commit is a way to tell Git "here are the changes I want to track". Not
everything in a repository folder is automatically tracked. We need to tell Git
what files we want to track. For now though, let's see how Git see's the world:
In this example, I have a new repository and I've created my first file with
some "Hello, World!" text in it. I can use git status to see what Git thinks
of the files in the repository:
~/git/my-project-name git status
On branch main

No commits yet

Untracked files:
  (use "git add ..." to include in what will be committed)
        my-first-file.txt

nothing added to commit but untracked files present (use "git add" to track)>

Git sees a new file that it has never tracked before: my-first-file.txt
Now, let's follow Git's helpful advice, add the file, and re-run the status
command to see what changes:
~/git/my-project-name git add my-first-file.txt
~/git/my-project-name git status
On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached ..." to unstage)
        new file:   my-first-file.txt


Now it looks like we have added the file to our staging area, but we haven't
committed. We're only preparing the files for commit, we haven't made the
"checkpoint" yet. To do that, let's use git commit. By default, a text editor
will pop up or display in your terminal. This is used for writing a commit
message. A commit message is what will be logged with your code changes into
Git history. So if you're working on a shared project, what you write here will
be viewable by anyone with access to the repository.
Writing good commit messages is an art form and practice makes perfect. Try to
include enough context with your messages, so a "code detective" down the line
can figure out what your change did without needing to read the code itself.
Keep in mind that you will be that "code detective" one day, and the code
you'll be digging into may very well be your own. Trying to track down a bug
and running into a commit that just says "fix" is infuriating. Make it easy on
yourself, write good commit messages.
A good Git commit message explains what changed and why. The first line is
reserved for a title, the second line skipped, and the third line and beyond is
for your longer write-up. This is so git log --oneline and other Git tools can
display text nicely. This isn't a hard rule though, people can (and will)
disregard good commit message etiquette, the software will work with it all the
same. Zach Holman has a great post about commit messages and why they just
don't matter, so there are
multiple schools of thought on the subject.
Back to the example. So I've written this as my commit message:
Added my-first-file.txt to use in a Git example

I've added this file with default text in order to show Git examples
using commit messages.

I saved the file and exited the text editor. Git then uses this to construct a
commit. It returned this text:
[main (root-commit) 3fa8cef] Added my-first-file.txt to use in a Git example
 1 file changed, 1 insertion(+)
 create mode 100644 my-first-file.txt

Now I can use git log to see my history:
commit 3fa8cefb1c854a550158a58d6443ec2b27e957fe (HEAD -> main)
Author: Tom Webster 
Date:   Wed Jan 4 00:17:48 2023 +0000

    Added my-first-file.txt to use in a Git example

    I've added this file with default text in order to show Git examples
    using commit messages.

To get a more compact view, you can use git log --oneline and that will
display your commit titles in a list:
3fa8cef (HEAD -> main) Added my-first-file.txt to use in a Git example

You may have noticed that long string of jumbled text above:
3fa8cefb1c854a550158a58d6443ec2b27e957fe.
This is a commit ID. A commit ID is a hash used to identify the change
you've added to history. Since hashes are designed to be unique, we only need to
display enough characters to identify a single commit, we don't need to display
the full ID from above, we can just display 3fa8cef.
A simple example of this is like an ID system with too many digits. Let's say
you have a list of the best fruits, but each ID has 10 digits, so you end up
with a table like this:
Fruit       - ID Number

Apple       - 0000000001
Orange      - 0000000002
Banana      - 0000000003
Strawberry  - 0000000004

So much wasted space in that ID number. If we think we'll have less than 100
fruits in this list, we can just use 2 digits to display the ID instead of the
full 10:
Fruit       - ID Number

Apple       - 01
Orange      - 02
Banana      - 03
Strawberry  - 04

Hashes in Git operate in mostly the same way: It will give you the shortest
unambiguous hash, but the minimum number of digits is 4.
Git Remotes
Git Remotes are remote repositories. Because Git is a distributed system, you
can have multiple remote repositories you can read from or write to. If you
cloned this course repository from GitLab, you'll probably see this when you run
git remote -v:
origin   (fetch)
origin   (push)

By convention, the first remote added to a Git repository is named origin, but
this is only a general convention, not a hard rule.
You can have multiple remotes and custom rules for pushing and pulling changes
for each of them if you want. Most often you'll just have one remote, hosted by
one of the popular Git hosting services. This setup will allow you to push
changes to an online repository and/or pull changes that have been pushed, but
you haven't pulled to your local repository.
If your repository was created on your local system only, without cloning from a
Git hosting service, you won't have any remotes configured initially. You can
always add a remote with:
git remote add remote-name remote-address
Like this:
git remote add origin git@gitlab.com:samurailink3/go-twitter.git
Pulling Changes
Git has two different methods to pull changes into your local repository:
fetch and pull. Fetching changes pulls down new objects, diffs, and
references from a Git remote down to your local repository. Its important to
keep keep in mind that fetching won't change files in your local workspace. The
changes are instead cached as part of that Git remote.
To fetch changes from the origin remote, you can run:
git fetch origin
If you'd like to fetch changes from all remotes, you can use:
git fetch --all
To actually update files in your local workspace, you would use git pull. This
will import changes from the configured remote branch into your local branch.
This means things like viewing history or checking diffs is near-instantaneous
because all of the changes are cached locally, Git doesn't need to go back to
the internet to get more data. Once you fetch, those changes are stored locally.
Pushing Changes
Once you have commits you would like to push to your configured remote, you can
use:
git push remote-name branch-name
Like this:
git push origin main
This tells Git, "Take my local commits and push them to the origin remote on
the main branch. Git will automatically figure out which commits are missing
on the remote and push only what's needed to make them match.
Branches and Checkouts
Branches in Git are a way to create other "timelines" of history in your
repository. So, if your main development branch is main, but you want to work
on a complex feature without introducing bugs or breakages on the main branch,
you can create a new branch named my-new-feature and start committing changes
to that branch. By default, the first branch of a new Git repository is called
main, or in older versions of Git, master.
To see a list of branches in your local repository, you can use:
git branch
To see all branches, even those present on remotes, you can use:
git branch --all
To create a new branch, you can just use:
git branch my-new-branch
Now, if you look at your list of branches with git branch, you'll see it in
your list of local branches:
* main
  my-new-branch

But if you look, you can see the * next to main, and if you run git status, you'll see that you're still on the main branch:
On branch main

So how do we switch branches?
git checkout my-new-branch
Now when you run git status, you'll see:
On branch my-new-branch
nothing to commit, working tree clean

Now, when you commit changes, you'll be committing to my-new-branch instead of
main. To get back to the main branch, run git checkout main.
To save time, you can create and check out a new branch with one command:
git checkout -b my-new-branch
If you'd like to base your branch on a specific branch, you can use:
git checkout -b my-new-branch main
or
git checkout -b my-new-branch origin/some-other-branch
Additional Reading and Git Workflows
There are many strategies and theories on when you should make new branches and
how you should organize them. When starting out: simpler is better. I'd
recommend reading about GitHub Flow. The quick reference for this
workflow is:
Create a new branch for your specific change
Make your commits
Push your branch to your remote
Create a merge request (called a Pull Request in GitHub's terminology)
If you're working in a group: Get sign off from your team and address any
comments or requests
Merge your changes
Delete your branch
If you are working on software that needs multiple versions and maintenance
releases (like operating systems or desktop software), something a bit more
complex, like git-flow, could help.
Appendix and References
References
The Git Website
Download Git
Git Basics
Codecademy Interactive Git Course
Register for GitLab
GitLab Profile SSH Keys
Git Internals
XKCD: Git
VS Code: Git
GitHub
GitLab
Bitbucket
Zach Holman: Utter Disregard for Git Commit History
GitHub Flow
git-flow



Halloween 2024 Data Analysis
2024-11-04T00:00:00Z
“OH ITS THAT HOUSE!!”
For the third year in a row, we’ve been the “Full-Sized Candy Bar House” in our neighborhood. We have always done rough inventory and after-the-fact tracking on Google Sheets, but that was mostly to guide our spending for next year. This year I wanted to try something a bit over-engineered, thus Untitled.
Using Notion and a pair of linked databases I was able to build a Trick or Treat inventory. I then built a “Selections” database. Each time a kid took a piece of candy, I cut a new DB record with the type. This automatically kicked off inventory deductions on the Inventory database and regenerated the graphs. After adding in some metadata, we are able to slice and dice the data to get some interesting insights into which candy was taken and when (each record has a “created at” timestamp, so we can do temporal analysis as well).
If you’d like to dig into this data yourself, feel free:
Untitled 
Untitled 
Notable Data Points
Let’s dig into some of the more interesting data points.
Headline Stats
Total Selections:
 137 (roughly 46 trick-or-treat-ers per hour)
Most Popular Type:
 Fruit-type Candy
Most Popular Brand:
 Skittles
Most Popular Item (number of selections): 
Airheads Xtremes - Rainbow Berry

Popular (and unpopular) Picks
Sour candy seems to be a big driver (~34% of all picks) with simpler chocolate-types following closely behind:

Its worth noting that both Airheads varieties were the first to be exhausted (aka: “sold out”). A treat containing peanuts or peanut butter seemed to lower its popularity. This follows along with other anecdotal data from previous years.
Simple chocolate-type candy tended to win out over “more complicated” varieties. Things like plain Hershey’s bars and Crunch bars were more popular than Snickers or Twix. This also follows trends from the previous two years.

Speaking of “exhausted”, here’s what we ran out of:

(which kinda bummed me out because I wanted at least one Crunch bar to be left over)

Some treats got picked just once, glad someone found their favorite thing:

Some treats just didn’t get picked at all:

We wanted to trial out cookies and chips to give chaperones a chance to grab something, but in the very rare case an adult did pick something, it was usually a classic candy bar (eg: Snickers). Our Cookie/Chip experiment was a resounding failure:

What’s Next?
This data-collection exercise was extremely entertaining (and will absolutely help inform purchasing decisions for next year), but there were small problems. Manual data collection doesn’t seem that hard, but when you have a group of 10 kids crowd around a small table and grab items simultaneously, it can get hard to track. I’d like to automate this.
I’m not sure if that will involve something like weighed candy bowls or a vending machine or what, but I’m kicking around some ideas with friends. In any case, we’ll likely end up doing similar data collection next year, just to compare.

🦋 Interact with this post on Bluesky:


https://bsky.app/profile/samurailink3.com/post/3lb3vky7op222







Rom Browser
2024-10-24T00:00:00Z
aka: TAHMS RAHMS
I finished a project over the weekend: Rom Browser - A simple web app designed to let my friends easily browse rom collections.



Why? What? Where can I get it?
I fucking love classic games. Whatever “classic gaming” means to you, love it, hell yeah, 10/10, can’t get enough. I love the idea of shared and open culture, freedom of information, and a more limited copyright system. I love roms, emulation, and game preservation. Now that you know where I’m coming from, let’s talk about the why.
A lot of people I know spent a very long time collecting and organizing rom packs for a wide variety of systems. Conveniently, I recently purchased a storage server for my homelab:


So now my friends had a place to back up their collections. But we wanted more than just backups, we wanted an easy way to share these collections. At first, I tried issuing everyone S3 MinIO keys, but, believe it or not, most people don’t use the AWS CLI on a daily basis. They wanted something easier to browse.
Thus, Rom Browser. I’ve needed to get deeper into frontend development for a while, and this project was just complicated enough to get really hands-on with something.
So… where can you get it? You can’t. This project is extremely specific to my particular hosting setup. From networking to the folder structures, its just not generic enough to be easily hosted. There are a few useful things to share that I’ll post below, but right now there isn’t any linked GitLab project. So this isn’t a project announcement, its just a blog post.
The Requirements
Private Access
I’m not trying to get in trouble, and hosting a roms site on the open internet is an easy way to do that. This needs to be Wireguard-only, completely private network.
Simple Backend, Learn Frontend
This project shouldn’t be overly-complex on the backend. I have plenty of experience there, what I need to concentrate on is building the site itself. The backend can be dumb and shortcut-filled in an effort to prioritize frontend-learning.
Provide a Good User Experience
The entire point of this project is to be more usable than the AWS CLI. The site should be intuitive and make users happy. Use domain names, not IPs. Use HTTPS to avoid scary browser warnings.
Make MinIO Transparent
The user should never be aware that they’re interacting with MinIO. I won’t use pre-signed URLs or bucket rules to provide direct access. This will run through a pass-through downloader.
The Tech
Rom Browser is broken up into three components:
Data Exporter - This just lists every object in the bucket, marshals the folder structure into struct variables, then exports this big-ass list of games as a JSON file.
File Server - This handles distributing that JSON cache file and serving rom downloads to users.
Frontend - This takes in that games cache file, then provides several useful views into the games data complete with download links.

Some of the benefits of this design are:
No MinIO keys in the frontend, no chance of leaks.
Users that have MinIO access can independently add new roms to the collection and this will be reflected on the site automatically when Data Exporter runs.
No need for a complicated backend database scheme or anything. Its just a 5MB JSON blob. Not ideal, but good enough for casual use.
Keeps me focused on the frontend and user experience, not on backend optimization.

For the frontend, I decided to try out https://vuejs.org/. I didn’t need the complexity of React, but wanted something a bit opinionated because I just don’t know enough about frontend development to have strong opinions yet.
Networking, Certificates, and Architecture
This site would be hosted on Wireguard at a private 10.x.x.x address. To support my “Good UX” goal, I bound this 10. address to a DNS name. Then, there was a new problem: HTTP-only sites give scary warnings in modern browsers. If I really want to provide the best user experience, I need HTTPS. I love Let’s Encrypt, but had only ever used it for internet-accessible sites. Never for anything internal.
After some poking around, I found LEGO, a Let’s Encrypt client that supports ACME DNS challenges. I plugged in my DNS-provider’s API key and it was able to issue a cert for my internal site without a problem. I then wrote a simple bash script to automate the renewal process and move the certs into the correct location.

The Data Exporter would be cron’d out to run once per hour. Doing the full list command, even on the local network, takes a bit over a minute. That’s far too long to make a user wait. So we need to run this ahead of time and cache the result. To avoid needing to write any sync-scripts to keep the cache file consistent across container volumes, I just hard-linked it.
The File Server is pretty simple. It listens for any requests to /download, then calls the appropriate handler. If the client asks for /download/games.json, the File Server reads the cache file into memory and provides it to the user. For anything else, it checks the path against a filename map to ensure it is in the dataset, downloads the object into memory, then hands it to the user. This helps obfuscate-away MinIO.
The frontend is just a simple https://vuejs.org/ site and uses Foundation for the styling. All of this is served from a single domain and backed by a Let’s Encrypt cert.
Cool Stuff
Use Caddy to bind multiple containers under same domain
I discovered that you can use Caddy to bind multiple servers together under one domain, then just switch who gets the request based on the path. In the example below, I’m serving the site through the frontend container, but any calls to emulation.example.com/download/ is passed through to the File Server container.
https://emulation.example.com {
        tls /etc/caddy/certificates/emulation.example.com.crt /etc/caddy/certificates/emulation.example.com.key
        reverse_proxy 10.1.2.3:3000
        reverse_proxy /download/* 10.1.2.3:8080
}
Use Dockerfile to compile and containerize your software
I wanted to just git push from my local machine and actually build the software on my server, but I didn’t want to clutter it up with a bunch of NodeJS stuff. Luckily, Docker makes this process pretty clean and easy. You can actually use a multi-step Dockerfile to build and then containerize your software. Here’s an example for a simple Go program:
FROM golang:1 AS builder
WORKDIR /opt/builder
COPY . ./
RUN CGO_ENABLED=0 GOOS=linux go build

FROM alpine:latest
EXPOSE 8080
COPY --from=builder /opt/builder/fileserver /bin/fileserver
CMD ["/bin/fileserver", "-config", "/data/config.toml"]
And here’s what I used for the frontend:
FROM node:23 AS builder
WORKDIR /opt/builder
COPY . ./
RUN npm install
RUN npm run build

FROM nginx:latest
EXPOSE 80
COPY --from=builder /opt/builder/dist/ /usr/share/nginx/html/
I then wrote a bash file to build all components in a single command.
So… did it work? Was this better than the AWS CLI?
My friends absolutely loved it. The site is easy to use, fast, and provided me with a perfect opportunity to jump into frontend development. I’m extremely happy with VueJS, Foundation, TrueNAS, MinIO, and the work I put into gluing all these together.

Until next time, thanks for reading!




Notion Calendar Exporter Update: Assignees in Title
2024-10-19T16:08:00-05:00
I’ve made updates to my Notion Calendar Exporter project: You can now elect to show the names of assignees in the event title.
Before, your event would look like this:
Build PC
But now it can be:
[Tom Webster] Build PC or even [Tom] Build PC if you set the option.
Check out the read me on the GitLab page for the details:
https://gitlab.com/samurailink3/notioncalendarexporter



New Site!
2024-10-07T00:00:00Z
I’ve moved my personal website to Notion.
For a while, I’ve been struggling to figure out what to do with my site. I always wanted it to be part blog, part project portfolio, part technical resource, but I kept running into distractions to make any kind of content-flow sustainable. I was always finding something to fix, something to optimize, something to build. For a person like me, this is simply too alluring to ignore:

And it would just go on.. and on… and on!
I never ended up writing much because I was too “busy” fiddling around. While there is benefit in just playing around and exploring various aspects of tech, it wasn’t solving my core need: Be a place where I can write and publish. Working on the writing platform was too tempting, especially compared to the “less fun” aspects, like, you know, actually writing things down.
So, I’m trying out Notion.
At some point I need to write up a more in-depth review of Notion, but for now, here’s the pitch/justification: Hosting my site on Notion removes (most of) the temptations around fiddling with the site-tech itself. Notion should be just-extendable-enough to power my site, get it organized roughly the way I want, and get out of the way. It should allow me to focus more on actually putting stuff out there and less on the systems around that content delivery.
Will it actually work out that way? Who knows?! But its interesting enough to be worth the try. So that’s why the site looks different (although showing anything other than an SSL error from a server that was ignored for far too long is better).