Brimdock is a dock for the servers in my homelab. A handle sits against the edge of the screen. Hover it and the servers slide out, click one and an SSH session opens in your terminal. Servers that don’t answer are dimmed and won’t launch, so you never open a terminal onto a box that’s down. This note is how it was built and what was harder than it looked.
It started as a picture
Brimdock was a web demo before it was an app. The interactive version on this site’s homepage came first, and the design document for the real app sets one goal above the others: the desktop version should be a pixel-perfect match of that demo.
It also didn’t start from nothing. Brimdock is the second app of its kind. Argus, a status rail for my services, already lived at the screen edge, so Brimdock copies its stack, its packaging and its release pipeline. They share patterns, not code: Brimdock’s reachability checker says in a comment that it mirrors Argus’s.
The stack is Python 3.14 with Qt 6 through PySide6, the interface in QML, and KDE’s layer-shell module to place it on the screen edge. One detail in the requirements file decided a lot: PySide6 has to come from the Linux distribution, not from pip. The pip build carries its own copy of Qt, and that copy can’t load the layer-shell module the whole app depends on.
Living on the edge of a Wayland screen
On Wayland, an app can’t just put a window wherever it likes. A dock that lives on the screen edge is a layer-shell surface, a special kind of window that the compositor anchors for you. Most of the interesting bugs came from that.
A surface clips at its own edges. Brimdock has two layouts. In the satellite layout the server cards fan out around the handle, reaching about 265 pixels each way. The surface was 400 pixels tall, so the fan was cut off. It’s 480 by 460 now, and the reason is written next to the number in the code, so nobody shrinks it again.
Don’t make the surface bigger than it needs to be. A full-height transparent surface would have been simpler, but it would also eat the clicks meant for whatever is behind it. So the surface only grows when the dock opens.
Dragging is harder than it looks. You can drag the dock to either edge of the screen. The first version made it jump and jitter, because it read the pointer’s position inside the 64-pixel surface, and moving the surface changed that position in a loop. The fix: while you drag, the surface briefly covers the whole screen, the handle follows the pointer inside it, and when you let go it glides to the nearest edge in about 200 milliseconds.
Some things simply can’t be done. Background blur behind a layer-shell surface isn’t possible from QML, because that’s up to the compositor, so the frosted look from the web demo couldn’t be copied exactly.
The small bugs that config files teach you
Brimdock reads a TOML config file and can also import every host from ~/.ssh/config. The Settings page writes the
file back, keeping your comments. Several bugs lived there:
- Booleans were written as Python’s
Trueinstead of TOML’strue, which made a file the app then refused to read. - The example config put top-level settings after the server list, so TOML quietly read them as part of the last server.
- An audit found that Settings could save stale values from a drag over the real ones.
- A server listed both in the config and in
~/.ssh/configshowed up twice. Duplicates are now removed by name.
None of these were dramatic, but each one would have been a confusing first five minutes for someone trying the app.
Three distributions, one pipeline
Every change goes through the same pipeline: run the tests, build packages for Arch, Debian and Fedora, test-install
the Debian and Fedora packages to check they actually work, then publish. Releases are signed with GPG,
and each comes with a signed SHA256SUMS, so you can check both the signature and the files before installing.
There’s also an AUR package, generated from each release.
The pipeline found its own share of bugs:
- A version number came out empty, because git refused to read a repository it didn’t own.
- The package database was missing its links, so
pacmangot a 404. - 13 stray Python cache files doubled the size of a package.
- One script had a colon in it, and YAML read the line as a key and value instead of a command.
The update check changed too. It first asked the package registry for new versions, but the registry needs a login, so
it now uses checkupdates, which Arch already provides. A later fix made it notice minor versions as well: it had only
compared the major number, so 0.1 to 0.2 never triggered a notification.
Testing something that only lives on a desktop
The logic is covered by 66 tests, which run without a screen through Qt’s offscreen platform. The test job runs on Arch with the distribution’s own Qt, so the layer-shell module really loads, and there are smoke tests that the app starts and that its Settings windows compile.
What tests can’t check is whether it looks right. For that the method was simpler: screenshots of the app next to the web demo, compared by eye. When the design values moved into one shared theme file, the screenshots before and after showed zero changed pixels.
Where it is now
Brimdock is at version 0.1.3, with packages for Arch, Debian and Fedora on its GitHub releases. It does one job: get from the desktop to a server in one click.
The code is closed for now, until I’ve finished working on it; the GitHub repository has the documentation and the signed releases.