flatpak

packaging/flatpak/README.md

@@ -0,0 +1,59 @@
+# Combined Linux Flatpak
+
+This packaging builds `server` with `full-embed` and `client-gui2` inside the
+GNOME 50 Flatpak SDK, then exports a single x86_64 Flatpak bundle. It is an
+additive alternative to the AppImage packaging; the existing AppImage build is
+unchanged.
+
+The build uses the official Flatpak Rust and Node SDK extensions. Cargo and
+Yarn resolve the committed lockfiles inside the build sandbox with network
+access. The PostgreSQL 17.10.0 archive, Typst 0.13.1 binary and protoc 21.12
+binary are downloaded by `flatpak-builder` as checksum-pinned sources.
+
+## Build
+
+Install `flatpak` and `flatpak-builder` through the host package manager, then
+run from the repository root:
+
+```sh
+packaging/flatpak/build.sh
+```
+
+The script configures the per-user Flathub remote when necessary, installs the
+GNOME SDK and SDK extensions through `flatpak-builder`, retains its reusable
+cache below `${XDG_CACHE_HOME:-$HOME/.cache}/komp-ac-flatpak-builder`, and
+creates:
+
+```text
+flatpak-dist/KompAC-embedded-x86_64.flatpak
+```
+
+An alternative output directory and filename may be supplied:
+
+```sh
+packaging/flatpak/build.sh /path/to/releases KompAC-0.8.50-x86_64.flatpak
+```
+
+## Install and run
+
+On the destination machine, install Flatpak through the system package manager
+and configure Flathub if it is not already available. Then install and run:
+
+```sh
+flatpak install ./KompAC-embedded-x86_64.flatpak
+flatpak run com.kompac.client
+```
+
+The bundle records Flathub as the source of its GNOME runtime. The first
+installation therefore downloads the runtime when it is not already installed.
+For an offline destination, transfer the runtime through a Flatpak repository
+or offline-update workflow as well as the application bundle.
+
+Application configuration and embedded database state live in Flatpak's
+per-user persistent XDG directories. Typst is included for document rendering;
+no host Typst installation or `.env` file is required.
+
+The manifest deliberately grants build-time network access for the locked
+Cargo and Yarn dependency graphs. This keeps private bundle builds automatic.
+A Flathub submission should replace that build permission with generated Cargo
+and Yarn source manifests from `flatpak-builder-tools`.