Skip to content

feat(linux): tarball release, GUI launch opens the surface, glibc 2.28 floor (#168) - #185

Merged
jonocodes merged 4 commits into
mainfrom
feat/linux-tarball-168
Nov 14, 2026
Merged

jonocodes merged 4 commits into
mainfrom
feat/linux-tarball-168

Conversation

@jonocodes

@jonocodes jonocodes commented Nov 13, 2026 •

Copy link
Copy Markdown
Owner

Part of #168. Three changes to the Linux channel found while preparing the first release.

Summary

1. A GUI launch opens the surface. deckd has no window, so opening the AppImage from the app menu or a file manager looked like nothing happened.

launcher (packaging/linux/launcher.py)
  resolve_open(args)            --open / --no-open, else: no tty + WAYLAND_DISPLAY|DISPLAY
  if open:
    if deckd already answers /health → xdg-open URL, exit 0   (autostart / second click)
    else → start daemon; background thread opens URL once /health answers

xdg-open gets the caller's LD_LIBRARY_PATH back, not the frozen bundle's. Every autostart path passes --no-open.

2. A tarball beside the AppImage. Same frozen payload, no FUSE, stable path, systemd user service.

deckd-<version>-<arch>.tar.gz
└── deckd-<version>-<arch>/
    ├── bin/deckd                       # same PyInstaller onedir as the AppImage
    ├── share/deckd/integration/        # udev rule, focus watchers, icon, helper
    ├── install-system-integration.sh   # run elevated, no args: installs this tree
    └── README.txt
 install-system-integration.sh
+  tarball: copy tree → ~/.local/opt/deckd (re-run = upgrade)
   focus watcher, icon
   udev rule
+  app-menu entry (Exec … --open)          # both channels
   autostart
-    XDG entry
+    AppImage: XDG entry (… --no-open)
+    tarball:  systemd user service (… --no-open), started now if the session is reachable
+    switching channels removes the other one's autostart
+  DECKD_HELPER_TEST_ROOT sandbox (tests only; sudo/pkexec scrub it)

3. Release builds run on older distros. A PyInstaller bundle needs a glibc at least as new as its build host, and we were freezing on the runner's Ubuntu 24.04 (glibc 2.39).

 release-linux.yml
   build (x86_64, aarch64)
-    setup-python + pip on the runner → just build-linux          # glibc 2.39 floor
+    just build-linux-portable   → manylinux_2_28 container      # glibc 2.28 floor
+                                  (python-build-standalone via uv; shared libpython)
+    just test-linux-floor       → boot tarball on debian:10, ubuntu:22.04, debian:12, fedora
     smoke tests, upload-artifact
-    gh release upload (per arch)
+  publish (needs: build)        → gh release upload, only when both arches pass

Supported: glibc ≥ 2.28, so Debian 10+, Ubuntu 20.04+, RHEL 8+, current Fedora and Arch. Not Alpine or other musl distros.

just build-linux builds both from one freeze (_linux-payload + _stage-linux-integration are shared). ADR-0012 amended; GUIDE has a new "Linux tarball" section.

Evidence

  • Before: the helper had no automated tests, and a GUI launch showed nothing.
    After: pytest reports 833 passed, 1 skipped (+26 test_open_surface.py, +12 test_install_helper.py); pyright is clean. Two deliberate mutations of the helper (dropping --no-open from the unit, skipping the XDG-autostart removal) each failed a test.
  • I ran a real just build-linux locally on NixOS through steam-run:
    pyinstaller runs: 1
    Built dist/deckd-0.0.1-x86_64.AppImage
    Built dist/deckd-0.0.1-x86_64.tar.gz
    # frozen AppImage and tarball, stub xdg-open on PATH:
    attach:      "deckd is already running at http://127.0.0.1:8768/; opening it"  exit=0
    stub saw:    http://127.0.0.1:8768/ unset          # URL right, LD_LIBRARY_PATH clean
    fresh GUI:   http://127.0.0.1:8768/ unset          # daemon started, then opened
    tarball:     boots, serves <title>deckd</title>, --extract-integration finds its assets
    helper (sandbox, real tarball): ExecStart="…/.local/opt/deckd/bin/deckd" --no-open
    CI "Smoke-test the tarball" step, run verbatim: PASS
    
  • glibc floor, scripts/test_linux_floor.sh run locally against both builds (podman):
    BEFORE (frozen on ubuntu:24.04)          AFTER (just build-linux-portable)
    FAIL  debian:10     (glibc 2.28)         PASS  debian:10     (glibc 2.28)
    FAIL  ubuntu:22.04  (glibc 2.35)         PASS  ubuntu:22.04  (glibc 2.35)
    FAIL  debian:12     (glibc 2.36)         PASS  debian:12     (glibc 2.36)
    PASS  fedora:latest (glibc 2.44)         PASS  fedora:latest (glibc 2.44)
    
    before, on ubuntu:22.04:
    [PYI-1:ERROR] Failed to load Python shared library '.../libpython3.12.so.1.0':
    /lib/x86_64-linux-gnu/libm.so.6: version `GLIBC_2.38' not found
    
    Highest glibc symbol in the manylinux bundle: GLIBC_2.18. The manylinux AppImage also boots on ubuntu:22.04.
  • Not verified: a real root install of the tarball (service start, uninstall), which goes with the Linux AppImage helper: pkexec front-end + uaccess-first (drop mandatory input group) #173 hands-on check. Also the aarch64 manylinux build: it was only built locally on x86_64, so the first CI run is its test.

Merge Danger

Door: two-way

Nothing has been released yet (no v* tag has ever run release-linux.yml), so there are no installs to migrate.

Blast Radius: packaging

  • Already-installed AppImage autostart entries lack --no-open, so they would open a browser at login until the helper is re-run. Only dev machines are affected.
  • Changed artifact name. The workflow's upload-artifact name changed from deckd-linux-appimage-<arch> to deckd-linux-<arch>.
  • The release build now depends on quay.io/pypa/manylinux_2_28_*, uv's python-build-standalone download, and Docker Hub images for the floor test. If any of them is unavailable, the release fails before publishing anything.
  • Local just build-linux still freezes against the host's glibc. Use just build-linux-portable for anything you hand to someone else.

deckd has no window, so a GUI launch of the AppImage (app menu, file-manager
double-click) looked like nothing happened. The launcher now opens the
surface in the default browser once /health answers, and when a daemon is
already running it just opens the browser and exits instead of failing on
the busy port. GUI launch is inferred (no tty + a graphical session);
--open / --no-open override it and every autostart path passes --no-open.
xdg-open gets the caller's LD_LIBRARY_PATH back, not the frozen bundle's.

The relocatable tree now also ships as deckd-<version>-<arch>.tar.gz: no
FUSE, a stable install path, and a systemd user service. Its top-level
install helper copies the tree to ~/.local/opt/deckd (re-run = upgrade),
installs the service, and removes the other channel's autostart on switch.
Both install paths add an app-menu entry.

The helper gains a DECKD_HELPER_TEST_ROOT sandbox so it is unit-tested
without root (sudo/pkexec scrub it). `just build-linux` builds both
artifacts from one freeze; the release workflow smoke-tests and uploads both.
ADR-0012 amended.
…floor)

A PyInstaller bundle needs a glibc at least as new as its build host. The
release was frozen on the ubuntu-24.04 runner (glibc 2.39), so both Linux
artifacts failed on Ubuntu 22.04 and Debian 12:

  GLIBC_2.38 not found (required by libpython3.12.so.1.0)

`just build-linux-portable` now freezes inside quay.io/pypa/manylinux_2_28
(AlmaLinux 8, glibc 2.28) with Python from python-build-standalone via uv —
manylinux's /opt/python builds are static and PyInstaller needs a shared
libpython. CI runs the same recipe; the runner only needs Docker.

`just test-linux-floor` boots the tarball on debian:10, ubuntu:22.04,
debian:12 and fedora:latest. Release CI runs it per arch, and publishing is
now a separate job that waits for both arches.

The container script zeroes appimagetool's AppImage magic so a host AppImage
binfmt handler (NixOS programs.appimage) can't hijack the exec inside the
container.
@jonocodes jonocodes changed the title feat(linux): tarball release + open the surface on a GUI launch (#168) feat(linux): tarball release, GUI launch opens the surface, glibc 2.28 floor (#168) Nov 13, 2026
…e race

An rc tag (v0.0.0-rc1) must not become the repo's "latest" release. The
Linux and macOS workflows both create the release for a tag, so the loser
of that race now confirms the release exists instead of failing.
@jonocodes

Copy link
Copy Markdown
Owner Author

Release rehearsal: v0.0.0-rc1 tagged at this PR's head. The Linux release run passed: run 43628446987.

x86_64 (ubuntu-24.04) aarch64 (ubuntu-24.04-arm)
manylinux_2_28 build ✅ AppImage + tarball ✅ AppImage + tarball (evdev built from source)
floor: debian:10 (glibc 2.28) ✅ ✅
floor: ubuntu:22.04 / debian:12 / fedora ✅ ✅
GUI attach (stub xdg-open, clean LD_LIBRARY_PATH) ✅ ✅
tarball + helper sandbox ✅ ✅

publish ran after both arches passed and created a prerelease (not "latest") with 2 AppImages, 2 tarballs, and the helper.

The macOS run for the same tag never started (macos-14 runner image retired). #186 fixes that.

The only warning: actions/checkout@v4, setup-node@v4 and upload-artifact@v4 target Node 20, which is deprecated. They still run, but bumping them is a follow-up.

GitHub runners force Node 20 actions onto Node 24 with a deprecation
warning. Bump each action to its current Node 24 major:

  checkout v4→v7, setup-node v4→v7, setup-python v5→v7,
  upload-artifact v4→v7, download-artifact v4→v8,
  deploy-pages v4→v5, upload-pages-artifact v3→v5

None of the breaking changes apply here: npm caching is already explicit,
client/dist has no dotfiles, and no workflow uses setup-python's removed
pip-install input.

The client now builds on Node 24 LTS everywhere (was 20, EOL April 2026,
and 22 for Pages), matching the flox environment. Docs move the stated
floor from Node 18+ (EOL) to 22+.
@jonocodes

Copy link
Copy Markdown
Owner Author

Rehearsal 2: v0.0.0-rc2 (Node 24 actions). The Linux release run passed: run 43634732384. Both arches built, all 8 floor checks passed, and publish created a prerelease. There were no annotations, so the Node 20 deprecation warning is gone. I downloaded the published assets as a user would: the tarballs are valid gzip, the AppImage is an intact ELF, the helper is byte-identical to the source, and the downloaded x86_64 tarball boots on debian:10 and ubuntu:22.04. So the upload-artifact v7 / download-artifact v8 hand-off doesn't mangle anything. macOS still needs #186.

@jonocodes
jonocodes merged commit 373f59d into main Nov 14, 2026
7 of 8 checks passed
@jonocodes
jonocodes deleted the feat/linux-tarball-168 branch November 14, 2026 23:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant