Tux sits smiling inside the flatpak logo, an isometric wooden box. Source image ‘Tux in Flatpak’ (link) by Daniel Aleksandersen (link) is licensed under CC-BY-4.0 (link).

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:

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:

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.