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.
