Add a flatpak build for linux#70
Conversation
…ata, workflow) Agent-Logs-Url: https://github.com/marthabo/iOpenPod/sessions/355db9ed-7b1c-4fef-a27c-56e599d967c6 Co-authored-by: marthabo <39622526+marthabo@users.noreply.github.com>
…ine installation steps
…nfiguring Flathub remote
…ak manifest and metadata
There was a problem hiding this comment.
Pull request overview
Adds Flatpak packaging support and a CI workflow to build and attach a .flatpak bundle to GitHub Releases for Linux distribution using the reverse-DNS app ID io.github.therealsavi.iOpenPod.
Changes:
- Introduces a Flatpak manifest plus Desktop Entry and AppStream metadata for
io.github.therealsavi.iOpenPod. - Adds a wrapper script to launch the PyInstaller one-folder bundle inside the Flatpak sandbox.
- Adds a GitHub Actions workflow to build the PyInstaller bundle, package it as a Flatpak, checksum it, and upload it to the GitHub Release.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
flatpak/iOpenPod-wrapper.sh |
Wrapper script to set runtime env vars and exec the bundled PyInstaller binary. |
flatpak/io.github.therealsavi.iOpenPod.yml |
Flatpak manifest that installs a pre-built dist/iOpenPod bundle plus icons/desktop/metainfo. |
flatpak/io.github.therealsavi.iOpenPod.metainfo.xml |
AppStream metadata for store/display integration. |
flatpak/io.github.therealsavi.iOpenPod.desktop |
Desktop entry for launching the app in desktop environments. |
.github/workflows/flatpak.yml |
CI workflow to build and upload the Flatpak bundle on tag pushes. |
| BUNDLE=/app/lib/iOpenPod | ||
| export LD_LIBRARY_PATH="$BUNDLE/_internal:$BUNDLE/_internal/Qt/lib:${LD_LIBRARY_PATH:-}" | ||
| export QT_PLUGIN_PATH="$BUNDLE/_internal/plugins:${QT_PLUGIN_PATH:-}" | ||
| exec "$BUNDLE/iOpenPod" "$@" |
There was a problem hiding this comment.
The wrapper sets LD_LIBRARY_PATH and QT_PLUGIN_PATH, but it doesn’t mirror the Linux AppImage launcher used in .github/workflows/release.yml (which also adds _internal/lib and sets QML2_IMPORT_PATH). If any Qt/QML components or bundled shared libs are under those paths, the Flatpak may fail to start or miss plugins. Consider aligning the environment variables with the AppImage AppRun so both packaging formats behave consistently.
| <releases> | ||
| <release version="1.0.41" date="2026-04-10"/> | ||
| </releases> |
There was a problem hiding this comment.
The AppStream release version is hard-coded to 1.0.41, but pyproject.toml currently declares version 1.0.43. This mismatch can confuse users and stores (and may cause validation failures in some tooling). Update the metainfo to match the current release version, or generate/sync this value as part of the release process.
| finish-args: | ||
| # Qt needs shared memory for IPC between processes. | ||
| - --share=ipc | ||
| # Allow the app to open an X11 window. | ||
| - --socket=x11 | ||
| # Allow the app to open a Wayland window. | ||
| - --socket=wayland | ||
| # Give the app access to all host devices, including USB (for iPod). | ||
| - --device=all | ||
| # Allow outbound network access (podcast downloads, artwork, update checks). | ||
| - --share=network | ||
| # Allow read/write access to the user's home directory (music library). | ||
| - --filesystem=home | ||
| # Common iPod mount points on Linux. | ||
| - --filesystem=/media | ||
| - --filesystem=/run/media |
There was a problem hiding this comment.
finish-args currently grants very broad host access (--device=all and --filesystem=home). This increases the sandbox escape surface and will likely block Flathub acceptance. If possible, narrow these to the minimum required (e.g., --filesystem=xdg-music and specific mount points, and only the device access actually needed for iPod sync) and document why any broad permissions are required.
| # This manifest wraps the pre-built PyInstaller bundle produced by the | ||
| # release workflow — it does NOT build iOpenPod from Python source inside | ||
| # the Flatpak SDK. The bundle directory (dist/iOpenPod/) must already | ||
| # exist when flatpak-builder is invoked; the GitHub Actions workflow takes | ||
| # care of building it first. |
There was a problem hiding this comment.
The manifest is designed to wrap a pre-built dist/iOpenPod directory (type: dir source) rather than building from source inside the Flatpak SDK. That approach generally isn’t acceptable for Flathub (which typically requires reproducible source builds and fixed upstream sources). If Flathub publication is a goal (per PR description), consider adding a source-build manifest (or clarify that this manifest is only for GitHub-release .flatpak bundles/custom repos).
| name: Flatpak | ||
|
|
||
| on: | ||
| push: | ||
| tags: | ||
| - "v*" | ||
|
|
||
| permissions: | ||
| contents: write # needed to upload assets to the GitHub Release | ||
|
|
There was a problem hiding this comment.
This workflow triggers on tags (v*) and uploads assets to the GitHub Release, but .github/workflows/release.yml is also triggered on the same tags and creates/uploads the release. Running two independent workflows that both create/update the same release can race and intermittently fail. Consider integrating the Flatpak build into the existing Release workflow (same run), or trigger this workflow via workflow_run after Release completes and only upload once the release exists.
|
are you marta in the discord? also, i have some questions about your experience with the compiled version of the software. i know that users sometimes have to download some odds and ends to get it working, i think to do with pyqt6? i dont have a linux distro installed at the moment and just test on mac and linux and rely on community to let me know if linux is working. Ill get a linux distro going this week so i can be more proactive about it. |
|
i notice it has 1.0.41 hardcoded, is there a way to get that to match the actual version automatically? or will it need changed each version? |
yes
Dependencies on Linux are a mess. For the best compatibility, the binary should be compiled on the same system it will be run on. It's then built against system dependencies and generally should work. AppImages allow you to easily bundle dependencies in the same way Mac programs are packaged in .app files. The best solution for compatibility across distros is Flatpak because it makes the program run in a sandbox built with a common runtime that's required to be installed on the user's computer. Flatpak handles this all automatically, installing the correct runtime with the program. I think it would be best to remove the Linux binary release and keep Flatpak, AppImage, and AUR as the recommended methods. If someone doesn't want to use these, they are usually knowledgeable enough to build it themselves from source.
I made the Flatpak build action get the release tag and update the metadata automatically upon running. It also runs after the release workflow ends because it sometimes doesn't detect the tag correctly. |
|
thanks for the help and info! |
This pull request adds the workflow and infrastructure for automatic flatpak builds. The app's id is
because flatpak requires reverse dns app ids. Currently the way of installing the app is through a .flatpak file, however the app can be published on a centralized repo called FlatHub or distributed through a custom repo made with github pages.