Flatpaking
I only use one snap app on my system and I wanted to see if it could be made available as a flatpak as well. The app in question is the OnlyKey-App (github.com), for use with their excellent USB security key: OnlyKey (onlykey.io). The app is written to run on node/Chromium (NW.js). This was my first time building a flatpak and I thought it might be straightforward. It was not.
The flatpak build process is quite particular - builds are performed in a forced offline environment which means a lot of work must go into obtaining online sources/dependencies before the build starts and language tools such as npm must be able to work offline too. I believe this stems from a desire of the flatpak project to achieve reproducible builds in future, though I could not find any official statement of this goal anywhere (see also: Flatpak builds are not reproducible and why that’s a practical problem (ranfdev.com))
Building a flatpak is mostly about crafting a suitable manifest (flatpak.org) that describes how to build and package your app. You can look at the manifest of existing apps (github.com) to see how it works or the handy quick start examples in flatpak-builder-tools (github.com).
That last repo also contains language-specific tools from the flatpak project
that are essential for creating a working manifest. Luckily there’s a tool just
for node and it’s aware of NW.js too: flatpak-node-generator. Essentially it
examines your package.json/package-lock.json and for each dependency it’ll
replace it with a local file reference and an instruction to flatpak-builder to
download and store the dependency before the offline build step.
Unfortunately I hit two problems with the tool that I had to first overcome:
- Npm provider’s generated-sources.json missing many packages (ENOTCACHED) (github.com). My manifest did not include all the packages needed by the app, so the build failed. The fix involved clearing up the way the tool looked through the package-lock.json. I put a PR together for that.
Once this was solved I hit a separate issue - the installer for NW.js does not work offline and of course that is required for flatpak. There was already a bug filed (#77 (github.com)) and it was fixed recently but not yet released. So I had to fork that and patch our app so it uses the fork.
This caused me to run into the second problem with the flatpak-node-generator tool:
- NotImplementedError: Git sources in lockfile v2 format are not supported yet (github.com). It’s not possible to use a git reference with the tool whilst on the latest version of node (actually the latest lockfile format). This was also solveable but in the process I couldn’t really ignore all the various ways in which npm can add a git reference to a project. So I ended making quite a few tests to try and cover it all and submitted another PR.
Finally after all this I got the flatpak built and running on my own machine 🎉 The final results are here: OnlyKey-App: Unofficial flatpak build of the OnlyKey app
Unfortunately this result is marred somewhat as it’s teetering on a pile of outstanding PRs and patches. I hope the PRs get accepted in some form and also the upstream OnlyKey project decide to take on the maintenance of the flatpak I’ve created so other users can find it easily.
Overall though this was a enjoyable challenge and I learnt much about building flatpaks.
