enricobuehler
25b08916b6
The flatpak has not built since 35ba64ca. Every push to main fails at "Build the
flatpak", before a single build command runs:
cp: cannot overwrite non-directory
'.../build/gamescope-wsi-layer-1/subprojects/vkroots/.git'
with directory '.../git/https_github.com_Joshua-Ashton_vkroots.git'
Error: module gamescope-wsi-layer: Child process exited with code 1
vkroots was declared twice. flatpak-builder clones git sources WITH SUBMODULES by
default, and `subprojects/vkroots` is a real gamescope submodule — `git ls-tree
8c676c39 subprojects/` shows it as mode 160000 at 5106d8a0, which is byte-for-byte
the commit the explicit source pinned. So the submodule checkout already produced
the right tree and left `subprojects/vkroots/.git` as a gitlink FILE; the second,
redundant source then tried to copy the bare mirror onto that path as a DIRECTORY,
and cp refused. Source extraction died there — `buildsystem: simple` and the
hand-applied glm/stb patch_directory copies were never reached, so neither is at
fault.
Removing the redundant source is therefore a no-op on the resulting tree: the
submodule supplies that exact rev. glm and stb are NOT submodules — `subprojects/
glm.wrap` and `stb.wrap` are plain blobs at that rev — so nothing else populates
them and their explicit sources have to stay. That asymmetry is the whole trap,
and it is now written down in the manifest next to the sources, along with the
disable-submodules escape hatch for anyone who later needs to pin a subproject
away from the gamescope rev.
Why this reached main: flatpak.yml has no `pull_request:` trigger — only `push` on
main with path filters, `tags: ['v*']`, and workflow_dispatch. PR #64's checks were
green because the flatpak was never built on the PR; run 15775 was the first time
this module had ever been built in CI. Adding a PR trigger (or a manifest lint) is
the durable follow-up, deliberately not bundled here.
This blocks the release, not just main. flatpak.yml runs on `tags: ['v*']`, and the
failing step gates the bundle export, the generic-registry publish, the OSTree push
to flatpak.unom.io and the release-asset attach — all of which stay skipped. A
v0.25.0 tag cut today would ship with NO Linux/Steam Deck flatpak at all, on the
release whose headline Linux change is Deck HDR working out of the box.
NOT VALIDATED LOCALLY: this cannot be built on macOS. The reasoning is confirmed
against the upstream tree (the ls-tree above) but the green run is still owed —
dispatch flatpak.yml on this branch before merging.
punktfunk client — Flatpak (Steam Deck / SteamOS, and any flatpak distro)
The native Linux client — the shell (crate punktfunk-client-linux, binary
punktfunk-client) plus the Vulkan session binary it execs for streaming (crate
punktfunk-client-session, binary punktfunk-session) — is
published two ways by CI (.gitea/workflows/flatpak.yml), on every push to main (a rolling
<next-minor>-ciN.g<sha> build, base derived from the latest stable tag by
scripts/ci/pf-version.sh) and on v* tags (a clean X.Y.Z):
- Hosted OSTree repo at
https://flatpak.unom.io(recommended) — a GPG-signed Flatpak remote served by a static Caddy container on unom-1, so users install once and thenflatpak update. Shared unom-wide repo (remote nameunom), reusable by other unom apps under the same signing key. See "Install (recommended)" below. - Single-file
.flatpakbundle in Gitea's generic package registry (unomorg) — the no-remote fallback the Decky plugin consumes (stablelatest/punktfunk-client.flatpakURL) and the offline/manual path. On tags it's also attached to the Gitea release.
The host is NOT a flatpak (it needs unsandboxed
/dev/uinput+ zero-copy NVENC — see../README.md"Why not Flatpak"). Only the client is sandbox-friendly.
Why flatpak for the Steam Deck
SteamOS /usr is read-only and image-based, and the system is missing libadwaita and
libSDL3 — so a bare punktfunk-client binary dropped into ~/.local/bin won't run. Flatpak
is the Deck's native, update-survivable app path (the user already runs Moonlight and chiaki-ng
as flatpaks), and the bundle carries libadwaita (from org.gnome.Platform//50) + a bundled SDL3,
with HEVC-capable FFmpeg supplied automatically by the runtime's codecs-extra extension.
App id: io.unom.Punktfunk (matches the Apple bundle id family and the Decky plugin's
flatpak fallback).
Install (recommended): the hosted repo
One command adds the signed unom remote and installs the client; it auto-adds Flathub for the
GNOME runtime, and flatpak update tracks new builds from then on:
flatpak install --user https://flatpak.unom.io/io.unom.Punktfunk.flatpakref
flatpak run io.unom.Punktfunk
Equivalent two-step (add the whole remote, then install by app id):
flatpak remote-add --user --if-not-exists unom https://flatpak.unom.io/unom.flatpakrepo
flatpak install --user unom io.unom.Punktfunk
Updates — the whole point of the hosted repo:
flatpak update # or: flatpak update io.unom.Punktfunk
Install on the Deck via the bundle (no-remote fallback)
The generic registry is a plain HTTP file store, so just download the bundle and install it per-user (no root, survives SteamOS updates). This is what the Decky plugin uses; the hosted repo above is the better path for a human on the Deck:
# Pick a version: a tag like 1.2.3, or the newest main build's <next-minor>-ciN.gSHA.
VER=1.2.3
URL="https://git.unom.io/api/packages/unom/generic/punktfunk-client-flatpak/$VER/punktfunk-client-$VER.flatpak"
# Flathub must be enabled (it is on the Deck) so the GNOME runtime + codecs-extra extension pull in:
flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
curl -fL -o /tmp/punktfunk-client.flatpak "$URL"
flatpak install --user --bundle /tmp/punktfunk-client.flatpak
Run it:
flatpak run io.unom.Punktfunk # GUI host list (mDNS)
flatpak run io.unom.Punktfunk --connect HOST:PORT
The Decky plugin launches exactly this (flatpak run io.unom.Punktfunk --connect …) once
installed — see ../../clients/decky/README.md.
Updating the bundle install
If you installed from the bundle (not the hosted repo), it has no remote to track, so updates are "download the newer bundle and reinstall":
flatpak install --user --bundle /tmp/punktfunk-client.flatpak # same command, newer file
Installs from https://flatpak.unom.io instead just take flatpak update (see "Install
(recommended)" above).
Build locally / the CI fallback
CI builds this in a --privileged Fedora container, because flatpak-builder runs
bubblewrap, which needs user namespaces the default Docker executor denies. If the Gitea
runner can't grant --privileged (the job fails at flatpak-builder with
"Creating new namespace failed: Operation not permitted"), build it out-of-band and upload
by hand. The easiest place is on the Deck itself (it can run org.flatpak.Builder
user-scope, no root):
# On the Deck (or any flatpak box), one-time:
flatpak install --user -y flathub org.flatpak.Builder
# build-flatpak.sh auto-detects org.flatpak.Builder, generates cargo-sources.json (or reuses an
# existing one — see below), builds, and exports dist/punktfunk-client-<version>.flatpak:
bash packaging/flatpak/build-flatpak.sh
# Upload to the generic registry (PAT with write:package):
curl -fsS --user "enricobuehler:$REGISTRY_TOKEN" \
--upload-file dist/punktfunk-client-*.flatpak \
"https://git.unom.io/api/packages/unom/generic/punktfunk-client-flatpak/0.0.1-manual/punktfunk-client.flatpak"
cargo-sources.jsongeneration needspython3+aiohttp+tomlkit, which the Deck lacks. Generate it on a dev box (build-flatpak.shdoes it, or run the upstreamflatpak-cargo-generator.py Cargo.lock -o packaging/flatpak/cargo-sources.json), rsync it next to the manifest, andbuild-flatpak.shreuses it (it only regenerates when the file is absent orFORCE_GEN=1).
The Mac build host cannot build a Linux flatpak (no flatpak-builder for macOS), and home-worker-2 has no flatpak and no passwordless sudo to install it — so the Deck or the privileged CI container are the only two viable build sites.
aarch64
The manifest builds for aarch64 as well as x86_64. Two things are architecture-specific, and both are now expressed properly rather than hardcoded:
PKG_CONFIG_PATHcontains the runtime's multiarch directory. flatpak-builder does not shell-expandenvvalues, so${FLATPAK_ARCH}would be taken literally — abuild-options.archoverride supplies the aarch64 string instead, inheriting everything else.- The prebuilt Skia archive is per-target and pinned by sha256. There are now two
type: filesources discriminated byonly-arches, both landing on the samedest-filename, soSKIA_BINARIES_URLstays one literal path. Upstream publishes the aarch64 archive under the same skia commit hash and the same resolved-feature key (pdf-textlayout-vulkan), so on a skia-safe bump update both URLs and both hashes together.
ARCH=aarch64 bash packaging/flatpak/build-flatpak.sh
# -> dist/punktfunk-client-<version>-aarch64.flatpak
ARCH defaults to this machine's, and the bundle name now carries the architecture so an x86_64
and an aarch64 build can coexist in dist/. This is not a cross-compile: flatpak-builder runs
the build in a sandbox for the target arch, so building aarch64 anywhere but an arm64 machine
needs qemu binfmt and is very slow. Not yet verified end to end — the manifest is correct by
construction and the Skia hash was checked against the published archive, but no aarch64 flatpak
has been built.
Manifest
io.unom.Punktfunk.yml. Runtime org.gnome.Platform//50
(GTK 4.20 + libadwaita 1.8 ≥ the crate floors of v4_16 / v1_5), built on freedesktop-sdk 25.08,
with two build-time SDK extensions: org.freedesktop.Sdk.Extension.rust-stable (→ //25.08,
rustc 1.96 — the GTK4 dep chain, e.g. pango-sys 0.22, needs ≥ 1.92, which the EOL GNOME-48 /
24.08 rust-stable at 1.89 could not provide) and org.freedesktop.Sdk.Extension.llvm20 (libclang,
needed by bindgen in ffmpeg-sys-next / sdl3-sys). HEVC-capable libavcodec (soname 61, accepted by
ffmpeg-next 8.x) is supplied automatically at runtime by the freedesktop codecs-extra
extension point (auto-downloaded with the runtime; no app-side codec declaration). A bundled
SDL3 3.4.10 module (pinned to match sdl3-sys 0.6.6+SDL-3.4.10), and finish-args for Wayland +
--device=all (GPU/VAAPI render node + evdev + the hidraw char-devices SDL3 needs for DualSense)
--socket=pulseaudio(PipeWire-pulse: playback + mic) +--share=network. Alongside it:io.unom.Punktfunk.desktop,io.unom.Punktfunk.metainfo.xml,io.unom.Punktfunk.svg(all installed by the manifest). Avulkan-headersmodule supplies what the session binary's ash/Vulkan build needs.cargo-sources.json(the offline crate cache) is a pure function ofCargo.lock; CI regenerates it each build and it is gitignored — generate it on any box with network +python3/aiohttp/tomlkit(build-flatpak.shdoes this automatically) and, for a build host that lacks those (the Deck), rsync the generated file in alongside the manifest.
Offline Skia: the session binary's Skia console UI (pf-console-ui → skia-safe) normally
downloads prebuilt libskia binaries at build time, which is dead in the offline sandbox — so the
manifest pins a skia-binaries-….tar.gz source and points the build at it with
SKIA_BINARIES_URL: file://…. When bumping the skia-safe/skia-bindings crate version, update
that pinned tarball (URL + sha256) to the matching skia-binaries release or the build breaks
offline.
Hosting the repo (unom-1) + one-time setup
The OSTree repo flatpak-builder produces is GPG-signed in CI and rsynced to unom-1, where a tiny
static Caddy container (server/compose.production.yml + server/Caddyfile, port 3230)
serves the ./site tree (repo/ + unom.flatpakrepo + io.unom.Punktfunk.flatpakref +
index.html). The edge Caddy on home-reverse-proxy-1 fronts it at https://flatpak.unom.io.
The CI deploy step no-ops until the secret + infra exist, so it won't redden builds mid-setup.
Signing key: dedicated RSA-4096 key unom Flatpak Repo <flatpak@unom.io>. Public key committed
at unom-flatpak.gpg (its base64 goes into the .flatpakrepo/.flatpakref
GPGKey=); private key (ASCII-armored, then base64) lives only in the CI secret.
One-time setup (mirrors any new unom DMZ service — see the deploy-infra notes):
- Secret
FLATPAK_GPG_PRIVATE_KEYon this repo = base64 of the armored private key (gpg --armor --export-secret-keys <fpr> | base64 -w0).DEPLOY_*+REGISTRY_TOKENalready exist. - Edge Caddy on home-reverse-proxy-1 (
/home/caddy/caddy/Caddyfile, apply by hand +./reload.sh):flatpak.unom.io { reverse_proxy 192.168.50.50:3230 } - Port allowlist: add
3230tocaddy_target_portsinunom/infra(proxmox/unom-1) + terraform apply. - DNS: ensure
flatpak.unom.ioresolves to the edge proxy.
Re-signing/rotation: regenerate the key, replace unom-flatpak.gpg + the secret; every client must
re-add the remote (the GPGKey changed), so rotate rarely.
Alternatives considered
- Hosted OSTree repo (chosen): the only option that gives
flatpak update. We self-host the static tree on unom-1 behind Caddy (Gitea has no flatpak/ostree registry); the build already produces the repo, so the marginal cost is GPG signing + an rsync + a 10-line static container. - Generic registry bundle (kept as fallback): one curl to publish, one
flatpak install --bundleto consume; mirrors the deb/rpm curl-upload pattern. No auto-update — this is what the Decky plugin pulls (stablelatest/punktfunk-client.flatpak), plus the offline/manual path. - Release attachment: also done on tags, good for a human-facing download page.
- Flathub (deferred): best discoverability + zero hosting, but a separate submission/review process and less control; revisit once the client is past scaffold quality.