Offline install of a flatpak application

flatpaksoftware installation

I am working in a locked-down corporate environment and I need to install the latest MonoDevelop (http://www.monodevelop.com/download/linux/) in an totally offline environment. I have the ability to access the web to do whatever I need to, but I need to somehow generate a set of files that I can carry over with a flash drive or other media from which I can perform the install on a RHEL 7.2 machine.

The flatpak build-bundle command looks promising, but it doesn't seem to be capable of working from an online repository. Since MonoDevelop installs from a flatpakref I haven't been able to figure out how exactly to do this. Do I need to mirror the entire repo locally? If so, because the flatpakref file also references the runtime Gnome repo, do I need to mirror that as well?

What I would really love is to just install this and then somehow export a bundle. For previous versions of MonoDevelop we were able to use repotrack to find all the relevant RPMs and bring those over manually, but now that they have moved to flatpak it doesn't seem so easy.

Best Answer

Update Nov 2020: In Flatpak 1.7.1+ there is a new cmdline option --sideload-repo and different paths for offline repos. Also re-worded answer to try and bring size down overall.

Update June 2020: I was not specific enough about the location of the offline repo. For avoidance of doubt the full path to the summary file in an offline repo should be: /.ostree/repos.d/myoffline_repo/summary. Clarified instructions below. Also discovered that links for offline repos must be on the same filesystem.

Update May 2020: make note of two issues that make using flatpak offline painful.

Please note two issues that make working with offline flatpak repos difficult:

There is a bug that causes problems when installing flatpaks that use extensions from an offline repo: Flatpak gets confused when the same ref of an extension exists in two repositories When working offline you create a second repo to mirror the online one so this bug cannot be avoided. It means required extensions are not installed on the offline machine. The best way to check if this is the case is to compare what is installed on a healthy online system versus the offline one flatpak list. Significant differences may indicate additional extensions required on the offline system. Flatpak will list what it's about to install when you install something so you can compare this way too. On the offline system it will fail to list the extensions.
Some flatpaks attempt to download files (extra-data) during installation which will fail if the host is always offline: Fails to download libopenh264 when installing offline from flatpak create-usb One example of this is the openh264 extension that during install downloads from cisco.com. You can circumvent this by placing the required downloads in the right place for flatpak to find them without downloading: '~/.local/share/flatpak/extra-data/$SHA256/$FILENAME'. However the exact filename depends on the flatpak's config. One way to find out is to install the problematic flaptak with strace and look for ENOENT against extra-data paths. The shas and filenames will change between releases/updates so you will have to update it on an on-going basis.

Blog post "About Flatpak installations" (blogs.gnome.org) by mclasen on the official GNOME blog says this is exactly what flatpak create-usb is for - it creates a mirror of a remote repo containing the app and will bundle all dependencies too. You can even repeat the create-usb step multiple times to push more apps into the new repo before transferring to offline hosts. You don't have to use a USB stick either, you can transfer the repo however you like to the target machine.

Start on the machine where you'll build your offline repo: the remote you're mirroring will need a collection ID and a subsequent flatpak update. If you're trying to package an app from flathub the author gives an example:

# Configure the remote
flatpak remote-modify --collection-id=org.flathub.Stable flathub
# Force an update
flatpak update
# Package up GIMP (for example)
flatpak create-usb ./ org.gimp.GIMP

The author explains why these steps are needed:

If you don’t add the collection ID to your remote configuration, you will be greeted by an error saying “Remote ‘flathub’ does not have a collection ID set”. If you omit the flatpak update, the error will say “No such branch (org.flathub.Stable, ostree-metadata) in repository”.

Despite the talk of USB sticks this will leave you with a repo under .ostree in the current directory.

Now that you have an offline repo you want to use it when installing flatpaks. Here there are differences depending on your Flatpak version.

Flatpak 1.7.1+

Starting from Flatpak 1.7.1 the latest documentation on USB Drives refers to offline repos as sideload repos. The docs say you can either specify --sideload-repo at the command line, use their new systemd units or

Alternatively, it’s possible to specify sideload sources using symbolic links placed in system-wide or user-specific directories and such sources will then be used for all Flatpak operations without the need for a --sideload-repo option.

This refers to the flatpak command reference which reads:

Such repositories are configured by creating symlinks to the sideload sources in the sideload-repos subdirectory of the installation directory (i.e. typically /var/lib/flatpak/sideload-repos). Additionally symlinks can be created in /run/flatpak/sideload-repos which is a better location for non-persistent sources (as it is cleared on reboot). These symlinks can point to either the directory given to flatpak create-usb which by default writes to the subpath .ostree/repo, or directly to an ostree repo.

The best option for a permanent setup is to make the symbolic links under /var/lib then. As an emample Flatpak should be able to reach the summmary of your offline_flatpak repo here: /var/lib/flatpak/sideload-repos/offline_flatpak/summary

The systemd unit mentioned earlier just seems to scan newly inserted drives and put symlinks under /run/flatpak/... This might be enough if you are genuinely using USB drives.

Flatpak <1.7.1

Flatpak has a repo finder mechanism that will consider not just remotes but certain local paths when looking for repositories or their mirrors. You just need to put the mirror repo in the right place on your target machine for flatpak to use it. Flatpak will search each mount for a repo at the following dirs:

.ostree/repo
ostree/repo
.ostree/repos.d/
ostree/repos.d/

So you can either copy your repo to a USB and stick it in the target machine or copy the files to e.g. /.ostree/repo to use the root filesystem.

To be clear, if you chose to use /.ostree/repos.d then the summary file for your offline repo should be found at /.ostree/repos.d/myoffline_repo/summary.

You can also use a symbolic link in any of these dirs and place the real files elsewhere e.g.

mkdir -p /.ostree/repos.d
ln -s /home/user/Downloads/.ostree/repo /.ostree/repos.d/myoffline_repo

However note the link must to the SAME filesystem or else flatpak will not use it.

Also note flatpak will favour the most up-to-date repo it can find, whichever that is.

Finally

You must still remember to add the original repo to the target machine of course (flathub in this instance) - and set the collection ID. This is because everything in the mirror repo is stored by reference to that original collection ID. On the target machine:

flatpak remote-add flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak remote-modify --collection-id=org.flathub.Stable flathub

If the target is truly offline you can add a remote from a .flatpakrepo file, instead of using a URL:

flatpak remote-add --if-not-exists flathub flathub.flatpakrepo
# Download file from https://flathub.org/repo/flathub.flatpakrepo

Then you can go ahead and install as normal on the target machine:

flatpak install flathub org.gimp.GIMP

If there any problems:

Try sudo in front of cmds in case its permissions stopping flatpak reaching your repo.
You can add the switch --ostree-verbose to flatpak cmds to see debug from ostree on what any problem might be.
You can inspect an ostree repo with ostree summary -v --repo=REPO to see what's actually in it.

Spawn commands outside of flatpak

You may use flatpak-spawn to run commands in a different environment.
However, usually you want to spwan the commands on the host system, thus breaking out of the sandbox. To do so, you obviously need to weaken the sandbox of the flatpak. Just add this permission:

flatpak override com.packagename.App --talk-name=org.freedesktop.Flatpak

Afterwards, you can run flatpak-spawn --host to run commands outside of the flatpak from the host.

Now, to really use this in a GUI, you hopefully have some ways to change the path to the binaries you want to run there. This can get complicated, as you need to pass additional params and in the end you may end up having to write small wrapper scripts.
In my case, I actually did, and you can find them here. They allow (in my case) Atom (but likely possible with any IDE) to run shellcheck or gpg…

How to Always Run a Flatpak Application with Filesystem Permission

TL;DR

If the app is installed "user-wide" add the --user option to the override command:

flatpak override --user --filesystem=/media com.github.alainm23.byte

Detailed

So, after thinking a lot, and reading a github issue about flatpak desktop entries (at this point I was thinking to workaround by manually tweaking it), I understood what was happening.

Basically, flatpak install installs apps "system-wide" by default. However I installed it from the Pop!_Shop (distro store). I realized the app wasn't in the system folder (/var/lib/flatpak/app), but it was in the user folder (~/.local/share/flatpak/app). Because of that I can conclude that Pop!_Shop installed the app "user-wide".

When I ran flatpak override --filesystem=/media com.github.alainm23.byte back then, it would complain and I just prepended sudo to it and it worked. At that time I didn't realize doing that would just set the override to a "system-wide installation" and the app was installed "user-wide".

So, adding the option --user to the override command solves the issue, and it doesn't require sudo.

flatpak override --user --filesystem=/media com.github.alainm23.byte

Now the app has access to the aforementioned file system when launched from the system menu and even from shell without specifying the permission (flatpak run com.github.alainm23.byte).