feat(distribution): Flathub (Flatpak) GUI path

[cevheri]

Final acceptance (local Flatpak E2E)

Done bar for the packaging work here. Store listing can come after.

• build/install locally with org.flatpak.Builder (flathub-build --install or equivalent)
• flatpak run org.libredb.Studio starts the GUI
• walk the main screens (login/workspace, connections, editor, results)
• add a sample PostgreSQL connection over TCP
• run a query (e.g. SELECT 1) and see rows in the results grid
• leave a short note or screenshot on this issue

Context

We already ship Docker, Helm, npx, Homebrew, .deb/.rpm and Snap (server daemon). Flathub is still missing. Snap-style headless wont fly there. Flathub wants sandboxed graphical desktop apps; console software is rejected.

Related: epic #108, desktop spike #115, recommendation in docs/DESKTOP_WRAPPER_SPIKE.md. Flathub is listed there as follow-up after a Tauri GUI + AppImage.

Blocked by: desktop wrapper PoC + AppImage on GitHub Releases. If that follow-up issue isnt open yet, open/link it first. This issue does not implement the wrapper itself.

Approach

Ship a real desktop shell (Tauri v2 sidecar per the spike; Electron only if WebKitGTK/Monaco fails on Linux). Publish AppImage from release CI. Flatpak manifest pulls that AppImage like Beekeeper does (type: file, unpack, install desktop/metainfo/icons), with x-checker-data pointed at GitHub Releases.

Proposed app id: org.libredb.Studio (verify via libredb.org). Fallback only if needed: io.github.libredb.libredb-studio.

Reference packaging: https://github.com/flathub/io.beekeeperstudio.Studio/blob/master/io.beekeeperstudio.Studio.yml

Trying to rebuild the whole Next.js app offline on Flathub is a bad fit. Reusing the release AppImage matches what similar SQL IDEs already do.

Rough finish-args: network, wayland + fallback-x11, dri, ipc. Prefer portals for files; document any host overrides (local sqlite is a known Flatpak pain, same as Beekeeper).

First login on Flatpak uses the desktop wrapper auth handoff (no password-from-logs UX). Bootstrap file/log remains fallback only.

Decided: Flatpak/desktop path uses STORAGE_PROVIDER=sqlite (same idea as the snap), with STORAGE_SQLITE_PATH under the Flatpak data dir so connections survive restarts. Wrapper should set that on sidecar launch. Tabs still live in the webview localStorage profile.

CI / automation (two places)

Upstream (libredb/libredb-studio):

• smoke-build the manifest with flatpak/flatpak-github-actions/flatpak-builder@v6 in a privileged ghcr.io/flathub-infra/flatpak-github-actions container
• native matrix: ubuntu-24.04 (x86_64) + ubuntu-24.04-arm (aarch64)
• uploads a .flatpak artifact for sanity checks
• does not publish to Flathub; do not wire flat-manager at Flathub

Flathub app repo (flathub/org.libredb.Studio after merge):

• only flathub org actions + peter-evans/create-pull-request are allowed there (https://docs.flathub.org/docs/for-app-authors/github-actions)
• version bumps via External Data Checker + x-checker-data (merge manually after a quick test)
• first submission: PR against flathub/flathub base branch new-pr, title like Add org.libredb.Studio (https://docs.flathub.org/docs/for-app-authors/submission)

Docs for the actions themselves: https://github.com/flatpak/flatpak-github-actions

Work bits

• desktop wrapper + AppImage release artifact (blocker)
• flatpak manifest template in-repo (optional, source of truth ends up on Flathub)
• local Builder build + flatpak-builder-lint on manifest/repo
• upstream flatpak-builder@v6 smoke CI (both arches)
• local E2E above
• Flathub submission PR (maintainer opens it by hand per Flathub docs)
• domain verification token at https://libredb.org/.well-known/org.flathub.VerifiedApps.txt
• docs/DISTRIBUTION.md Flathub section + distribution/channels.yaml entry

Out of scope

• packaging the Snap daemon as a Flatpak
• console-application metainfo
• deploying to Flathub via flat-manager from this repo

Refs

• https://docs.flathub.org/docs/for-app-authors/requirements
• https://docs.flathub.org/docs/for-app-authors/submission
• https://docs.flathub.org/docs/for-app-authors/maintenance
• https://docs.flathub.org/docs/for-app-authors/github-actions
• https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines
• https://flathub.org/apps/io.beekeeperstudio.Studio
• docs/DESKTOP_WRAPPER_SPIKE.md

[cevheri]

Local Flatpak E2E - done

The packaging work is in #235: the Tauri v2 desktop shell (desktop/), the AppImage release job,
and the Flathub manifest (packaging/flatpak/). Everything below was run on this machine against
the manifest and the AppImage that PR produces.

Environment: Ubuntu 24.04 x86_64, X11 session; flatpak-builder 1.4.9 and flatpak-builder-lint
3.0.0 from org.flatpak.Builder; org.gnome.Platform//50 + org.gnome.Sdk//50; PostgreSQL 18 on
127.0.0.1:5433.

Done bar

• build/install locally with org.flatpak.Builder - scripts/build-flatpak-local.sh <appimage> --install renders both manifests, validates the metainfo (appstreamcli validate: pass),
  lints the release manifest (pass), builds, installs, and lints the exported repo (pass). The
  AppImage it repacks is 144 MB and its own --smoke boots the bundled server out of the
  extracted AppDir and gets 200 from /api/db/health.
• flatpak run org.libredb.Studio starts the GUI - splash, then the workspace, with no
  login prompt: the shell reads the password the zero-config first run persisted in
  ~/.var/app/org.libredb.Studio/data/org.libredb.Studio/auth-bootstrap.json and hands it to
  /api/auth/login. Zero error lines in the app log.
• walk the main screens - workspace, connections sidebar, schema explorer, Monaco editor,
  results panel, admin dashboard. Screenshots below.
• add a sample PostgreSQL connection over TCP - 127.0.0.1:5433, user postgres, database
  companyos. "Test Connection" answered Connected successfully (55ms) from inside the
  sandbox, and the schema loaded with 58 tables and row counts.
• run a query and see rows in the results grid - SELECT 1 AS ok, current_database() AS db
  returned 1 rows - 1ms, ok = 1, db = companyos.
• note on this issue - this comment.

Note on how the walkthrough was driven: the WebKitGTK window has no scriptable input on this box (no
xdotool/ydotool), so the clicking part of the connection-and-query walkthrough was done against
the same sidecar the Flatpak app was running (http://127.0.0.1:<port>) from a browser, and the
result then verified inside the app's own window after a restart. The screenshot above is the Flatpak
window itself: Local PostgreSQL (TCP) selected, POSTGRES - LOCAL - Online, 58 tables in the
explorer.

What the run turned up (all fixed in #235)

• Tauri's resource copy drops symlinks, and Turbopack resolves the externalized DB drivers through
  hashed symlinks under payload/.next/node_modules - the server logged "Ready" and then failed
  every request with Failed to load external module ssh2-<hash>.
• flatpak-builder strips binaries by default, which turned the bundled better_sqlite3.node into
  "object file has no loadable segments" and took SQLite storage down while the app looked healthy.
  The module now sets strip: false / no-debuginfo: true.
• The session cookie was marked Secure whenever NODE_ENV=production; libsoup (the cookie store
  behind WebKitGTK) discards such a cookie over http instead of ignoring the flag the way Chromium
  does on localhost, so the handoff signed in and then bounced between /login and / forever.
  Secure is now omitted only for loopback-over-http requests.
• linuxdeploy needs APPIMAGE_EXTRACT_AND_RUN=1, patchelf and librsvg2-dev, and hard-fails on
  sharp's Alpine libvips build (libc.musl-x86_64.so.1).
• Two repo-lint checks (appstream-external-screenshot-url, appstream-remote-icon-not-mirrored)
  can only pass inside Flathub's own pipeline, which rewrites media URLs to dl.flathub.org. They
  are listed in packaging/flatpak/lint-exceptions.json with the reason; everything else the linter
  reports stays a hard failure.

Still open on this issue

• The submission PR against flathub/flathub (base branch
  new-pr, title Add org.libredb.Studio) - a maintainer step. Checklist in
  packaging/flatpak/README.md. Worth saying in that PR up front that the manifest repacks the
  released AppImage rather than building from source, and why.
• The domain-verification token at https://libredb.org/.well-known/org.flathub.VerifiedApps.txt -
  Flathub only issues it after the submission exists, so it is a libredb-website follow-up.
• A <release> entry in org.libredb.Studio.metainfo.xml for whichever version first ships to
  Flathub (the External Data Checker maintains the manifest sources, not the release list).

[cevheri]

Flathub submission opened as a draft: flathub/flathub#9538

It stays draft until 0.9.60 ships, because the manifest references that release's AppImage and the two sha256 values are placeholders until then. Before marking it ready:

1. cut 0.9.60 (the desktop-appimage job attaches the two AppImages plus their .sha256 sidecars)
2. put the real checksums into org.libredb.Studio.yml on the submission branch
3. attach a short screencast of the Flatpak running (the template asks for a video)
4. add a entry for 0.9.60 to org.libredb.Studio.metainfo.xml

The domain token for https://libredb.org/.well-known/org.flathub.VerifiedApps.txt is issued from the developer portal after the app repository exists, so that stays a follow-up on libredb-website.