Flatpak provides several ways to distribute applications. The primary method is to host a repository. This is relatively simple (although there are some important details to be aware of) and allows application updates to be distributed.
It is also possible to distribute Flatpaks as single file bundles, which can be useful in some situations.
Hosting a repository¶
The previous sections of this guide describe how to generate repositories using
flatpak-builder. The resulting OSTree repository can be hosted on a web server for consumption by users.
OSTree repositories use archive-z2, meaning that they contain a single file for each file in the application. This means that pull operations will do a lot of HTTP requests. Since new requests are slow, it is important to enable HTTP keep-alive on the web server.
OSTree supports something called static deltas. These are single files in the repo that contains all the data needed to go between two revisions (or from nothing to a revision). Creating such deltas will take up more space on the server, but will make downloads much faster. This can be done with the
build-update-repo --generate-static-deltas option.
OSTree uses GPG to verify the identity of repositories. This requires that every commit to a repository uses a GPG signature, as well as when repository summary files are modified.
To do this, a GPG key needs to be passed to the
build-export commands, as well as
flatpak-builder if it is being used to modify or create a repository. (If you don’t already have a key, it is easy to generate one.) For example:
$ flatpak build-export --gpg-sign=KEYID --gpg-homedir=PATH REPOSITORY DIRECTORY
--gpg-homedir is optional, and allows specifying the home directory of the key to be used.
Though it generally isn’t recommended, it is possible to disable GPG verification of OSTree repositories. To do this, the
--no-gpg-verify option can be used when a remote is added. GPG verification can also be disabled on an existing remote using
Note that it is necessary to become root in order to update a remote that does not have GPG verification enabled.
Referring to repositories¶
A convenient way to point users to the repository containing your application is to provide a
.flatpakrepo file that they can download and install. To install a
.flatpakrepo file manually, use the command:
$ flatpak remote-add --from foo.flatpakrepo
.flatpakrepo file looks like this:
[Flatpak Repo] Title=GEdit Url=http://sdk.gnome.org/repo-apps/ GPGKey=mQENBFUUCGcBCAC/K9WeV4xCaKr3...
If your repository contains just a single application, it may be more convenient to use a .flatpakref file instead, which contains enough information to add the repository and install the application at the same time. To install a
.flatpakref file manually, use the command:
$ flatpak install --from foo.flatpakref
.flatpakref file looks like this:
[Flatpak Ref] Title=GEdit Name=org.gnome.gedit Branch=stable Url=http://sdk.gnome.org/repo-apps/ IsRuntime=False GPGKey=mQENBFUUCGcBCAC/K9WeV4xCaKr3... RuntimeRepo=https://sdk.gnome.org/gnome.flatpakrepo
Note that the GPGKey key in these files contains the base64-encoded GPG key, which you can get with the following command:
$ base64 --wrap=0 < foo.gpg
Hosting a repository is the preferred way to distribute an application, but sometimes a single-file bundle that you can make available from a website or send as an email attachment is more convenient. Flatpak supports this with the
build-import-bundle commands to convert an application in a repository to a bundle and back:
$ flatpak build-bundle [OPTION...] LOCATION FILENAME NAME [BRANCH] $ flatpak build-import-bundle [OPTION...] LOCATION FILENAME
For example, to create a bundle named dictionary.flatpak containing the GNOME dictionary app from the repository at ~/repositories/apps, run:
$ flatpak build-bundle ~/repositories/apps dictionary.flatpak org.gnome.Dictionary
To import the bundle into a repository on another machine, run:
$ flatpak build-import-bundle ~/my-apps dictionary.flatpak
Note that bundles have some drawbacks, compared to repositories. For example, distributing updates is much more convenient with a hosted repository, since users can just run