poncho-wonky-flatpak/README.md

Patchwork Flatpak

Flatpak packaging for Poncho Wonky, the Secure Scuttlebutt (SSB) desktop client. This is a release-wrapper Flatpak: it repackages the official upstream tar.gz build from the GitHub releases page instead of building from source, so no native modules are recompiled inside the sandbox.

The packaging files in this repository (manifest, launcher, build scripts) are licensed under CC0-1.0 (see LICENSE). The packaged application itself remains AGPL-3.0, as declared in nz.scuttlebutt.Patchwork.metainfo.xml.

Layout

File	Purpose
nz.scuttlebutt.Patchwork.yaml	flatpak-builder manifest
patchwork.sh	Launcher that runs the app through zypak-wrapper (Electron sandbox)
nz.scuttlebutt.Patchwork.metainfo.xml	AppStream metadata for software centers
build.sh	One-shot build + install helper
flathub.json	Flathub build config

Prerequisites

On Debian/Ubuntu:

sudo apt install flatpak flatpak-builder
flatpak remote-add --if-not-exists --user flathub https://flathub.org/repo/flathub.flatpakrepo

Alternatively, flatpak-builder can be installed as a Flatpak:

flatpak install flathub org.flatpak.Builder

If you use org.flatpak.Builder, you'll need to run builds with:

flatpak run --command=flatpak-builder org.flatpak.Builder \
  --repo=repo --force-clean build-dir nz.scuttlebutt.Patchwork.yaml

Build and install

./build.sh

or manually:

flatpak install -y flathub \
  org.freedesktop.Platform//24.08 \
  org.freedesktop.Sdk//24.08 \
  org.electronjs.Electron2.BaseApp//24.08

flatpak-builder --repo=repo --force-clean build-dir nz.scuttlebutt.Patchwork.yaml

flatpak --user remote-add --if-not-exists --no-gpg-verify patchwork-repo repo
flatpak --user install -y patchwork-repo nz.scuttlebutt.Patchwork

Run it:

flatpak run nz.scuttlebutt.Patchwork

The launcher (patchwork.sh) forces Electron onto Wayland whenever a Wayland socket is available, so it also works from terminals that are not part of the desktop session (local TTY, SSH) where DISPLAY/WAYLAND_DISPLAY would otherwise be unset and Electron would fail with Missing X server or $DISPLAY. On X11-only systems it falls back to Electron's default X11 platform.

Updating to a new release

All pinned versions live in versions.sh. Bump the app version first:

1. Note the new version tag (e.g. v5.5.0) and download the new assets:

   wget https://github.com/soapdog/patchwork/releases/download/v5.5.0/ponchowonky-5.5.0.tar.gz
   wget https://github.com/soapdog/patchwork/releases/download/v5.5.0/ponchowonky-5.5.0-arm64.tar.gz
   sha256sum ponchowonky-5.5.0.tar.gz ponchowonky-5.5.0-arm64.tar.gz
   

2. Update APP_VERSION, APP_SHA256_X86_64 and APP_SHA256_AARCH64 in versions.sh, then run ./check-versions.sh — it verifies the manifest URLs/checksums and the metainfo release entry still match.

3. Update url/sha256 in nz.scuttlebutt.Patchwork.yaml. No build-commands change is needed: flatpak-builder strips the archive's top-level directory (default strip-components: 1) into the app/ source directory.

4. Add a new <release> entry in nz.scuttlebutt.Patchwork.metainfo.xml.

To bump the Flatpak environment, update RUNTIME_VERSION in versions.sh (used for the freedesktop runtime, SDK and Electron BaseApp — they always move together).

Automated updates

update-version.sh performs the app-version bump above automatically: it fetches the latest upstream release, downloads both tar.gz assets to compute their sha256, and updates versions.sh, the manifest and the metainfo (including the release date). Run it locally with --dry-run to preview, or plain to apply (requires curl and jq).

Two GitHub Actions drive the workflow:

• .github/workflows/update.yml — on a daily schedule (or workflow_dispatch) runs update-version.sh, commits the bump as github-actions[bot], pushes a branch and opens a PR labeled automerge.
• .github/workflows/build.yml — on every PR and push to main validates the shell scripts and pinned versions, then builds the Flatpak in the freedesktop-24.08 Flathub CI container (installing the Electron BaseApp first). A merge job auto-merges the bump PR with --squash once both jobs pass; if the build fails the PR stays open for manual review.

Runtime bumps are never automated — only the app version is.

Notes

• Why tar.gz and not the AppImage? The upstream tar.gz assets are the unpacked electron-builder build. Using them avoids the --appimage-extract step and keeps the manifest architecture-agnostic.
• Runtime vs. Electron version. The app ships its own Electron binary inside the tar.gz, so the runtime is not tied to Electron's version — it only needs to satisfy the host glibc/GTK stack that Electron requires. RUNTIME_VERSION should be bumped to the next freedesktop branch only when a newer Electron stops working on the current one (the manifest change is one line plus a rebuild).
• SSB data. Patchwork resolves its data directory from the real user home (getpwuid), not $HOME, so it writes to ~/.ssb on the host even from inside the sandbox. A non-Flatpak install shares the same data — no migration needed. (Flatpak still redirects ~/.cache, ~/.config and ~/.local for this app to ~/.var/app/nz.scuttlebutt.Patchwork/.)
• Network. SSB uses LAN multicast discovery, DHT and direct TCP/UDP; --share=network covers this. --device=all is granted for webcam support and can be removed from finish-args if you do not want it.
• Flathub. The metainfo <screenshots> section is omitted because the upstream screenshot URL currently returns 404. Add screenshots hosted on a stable CDN before submitting to Flathub.