enricobuehlerandClaude Opus 5
aff169e131
Two things were x86-specific, both now expressed properly instead of
hardcoded:
* PKG_CONFIG_PATH carries the runtime's multiarch directory.
flatpak-builder does NOT shell-expand `env` values, so ${FLATPAK_ARCH}
would be taken literally — a build-options.arch override supplies the
aarch64 string and inherits the rest.
* The prebuilt Skia archive is per-target and pinned by sha256. Two
`type: file` sources discriminated by only-arches now share one
dest-filename, so SKIA_BINARIES_URL stays a single literal path.
Upstream publishes the aarch64 archive under the same skia commit hash
and the same resolved-feature key, so the two stay in lockstep on a
skia-safe bump.
build-flatpak.sh gains ARCH (default: this machine's), passes --arch to
both flatpak-builder and build-bundle, and arch-suffixes the bundle name so
an x86_64 and an aarch64 build can coexist in dist/ instead of the second
silently overwriting the first. CI composes its own published filename, so
nothing downstream changes.
The aarch64 Skia sha256 was verified by downloading the published archive,
not taken from the API. No aarch64 flatpak has been built — flatpak-builder
builds in a sandbox for the target arch, which needs an arm64 machine.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
216 lines
12 KiB
Markdown
216 lines
12 KiB
Markdown
# 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`):
|
|
|
|
1. **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 then
|
|
`flatpak update`**. Shared unom-wide repo (remote name `unom`), reusable by other unom apps
|
|
under the same signing key. See "Install (recommended)" below.
|
|
2. **Single-file `.flatpak` bundle** in **Gitea's generic package registry** (`unom` org) — the
|
|
no-remote fallback the **Decky plugin** consumes (stable `latest/punktfunk-client.flatpak`
|
|
URL) 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`](../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:
|
|
|
|
```sh
|
|
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):
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
# 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:
|
|
|
|
```sh
|
|
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`](../../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":
|
|
|
|
```sh
|
|
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):
|
|
|
|
```sh
|
|
# 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.json` generation needs `python3` + `aiohttp` + `tomlkit`, which the Deck lacks.
|
|
> Generate it on a dev box (`build-flatpak.sh` does it, or run the upstream
|
|
> `flatpak-cargo-generator.py Cargo.lock -o packaging/flatpak/cargo-sources.json`), rsync it next
|
|
> to the manifest, and `build-flatpak.sh` reuses it (it only regenerates when the file is absent
|
|
> or `FORCE_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_PATH`** contains the runtime's multiarch directory. flatpak-builder does *not*
|
|
shell-expand `env` values, so `${FLATPAK_ARCH}` would be taken literally — a `build-options.arch`
|
|
override supplies the aarch64 string instead, inheriting everything else.
|
|
* **The prebuilt Skia archive** is per-target and pinned by sha256. There are now two `type: file`
|
|
sources discriminated by `only-arches`, both landing on the same `dest-filename`, so
|
|
`SKIA_BINARIES_URL` stays 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.
|
|
|
|
```sh
|
|
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`](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). A `vulkan-headers` module supplies what the session binary's ash/Vulkan
|
|
build needs. `cargo-sources.json` (the offline crate cache) is a pure function of
|
|
`Cargo.lock`; CI regenerates it each build and it is **gitignored** — generate it on any box with
|
|
network + `python3`/`aiohttp`/`tomlkit` (`build-flatpak.sh` does 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`](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):
|
|
|
|
1. **Secret** `FLATPAK_GPG_PRIVATE_KEY` on this repo = base64 of the armored private key
|
|
(`gpg --armor --export-secret-keys <fpr> | base64 -w0`). `DEPLOY_*` + `REGISTRY_TOKEN` already exist.
|
|
2. **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 }`
|
|
3. **Port allowlist:** add `3230` to `caddy_target_ports` in `unom/infra` (proxmox/unom-1) + terraform apply.
|
|
4. **DNS:** ensure `flatpak.unom.io` resolves 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
|
|
--bundle` to consume; mirrors the deb/rpm curl-upload pattern. No auto-update — this is what the
|
|
**Decky plugin** pulls (stable `latest/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.
|