Flatpak:DeveloperDocs

Introduction

Flatpaks are a new way of deploying applications. If you have an application already packaged as a Fedora package, creating Flatpak offers a number of advantages:

• The application can be safely updated without rebooting the system (you can update a package without rebooting your system using dnf from the command line, of course, but GNOME Software only offers updating applications as part of an offline system update.)
• The application can seamlessly be installed on Fedora Silverblue
• The Flatpak works across all supported Fedora versions - you don’t have to update trailing versions of Fedora for people to use the newest application version.
• The Flatpak can be run by people running on other distributions

Creating a Flatpak of an application that is already packaged in Fedora involves two steps. First you need to create a module for the application. This module will be used to rebuild the application RPM and RPMs. Then you need to create a container out of the module. In the Fedora context, flatpaks are just another form of container, and are handled very similar to the Docker containers used for server applications.

Just as for packages, the instructions for building modules and containers are stored in git on src.fedoraproject.org and builds are coordinated by koji.fedoraproject.org. One difference between server side containers and flatpaks is, however, that for flatpaks the module and the flatpak are so tied together that we don’t have separate git repositories modules/<application> and container/<application>/. Instead the container.yaml that contains the information that is needed to create the Flatpak container is simply stored inside the modules/<application> git repository.=

Is your application suitable?

Most graphical applications can be made into a Flatpak without modification, though creating a sandboxed Flatpak that prevents the application from doing arbitrary things to the user’s account is more likely to require code changes.

Some things that could make an application not work well as a Flatpak:

• If it installs system services or changes system configuration files
• If it needs access to binaries or other files in /usr that can’t be bundled with the application

Picking an application ID

Every application needs a unique application ID, based on a reversed domain name. For example org.gnome.Maps

• If the application already has a desktop file of this form, that is the application ID.
• If the application exports any D-Bus services (Looks for files in /usr/share/dbus-1/services/ - though an application can export D-Bus services without installing a service file) then the prefix of the D-Bus name should match the application ID.
• If the application is already packaged on https://flathub.org please use the same application ID.
• Otherwise, you need to make up an application ID. This should be your best possible guess as to what the upstream would use - if they have their own domain name, that should be the basis, otherwise base it on the hosting - e.g. org.github.<user/organization>.<Application>. Note that the original idea of an application ID is that it is in a reversed name that is under your control, so if possible, please coordinate with the upstream, ask them if your choice is OK, and ask them to rename their desktop file and icon to match that.

Applications can only export resources under their application ID, so the desktop file and icon for the application need the appropriate name. The best place to implement this is upstream. The second best place is in the Fedora application package. But if this isn’t possible, you can do this in your container.yaml. See the Renames section below.

Versioning

Flatpaks in Fedora are different from packages in that there isn’t a separate application version for F28, F29, rawhide, etc. Instead there is a single version that is the latest stable version for all versions of Fedora.

A flatpak targets a particular runtime. Your stable version should ideally target the runtime corresponding to the latest released version of Fedora. If the released upstream stable version of the application has dependencies that are not available in a released version of Fedora and that can’t be bundled in your application module (e.g. it requires a newer version of the C compiler) then it’s acceptable to use the next version of the Fedora runtime, but this should be an unusual case. Your application might be based on the flatpak-runtime:f28 module, for example.

The module and container versions for your stable release should be in the master branch of your git repository, and the stream of the module will be the master stream.

If you want to package unstable upstream releases, see the “Development Versions” section below.

Installing the necessary tools

$ dnf install flatpak-module-tools fedmod koji-containerbuild

Creating <application>.yaml and container.yaml

$ mkdir <application> && cd <application>
$ fedmod fetch-metadata
$ fedmod rpm2flatpak <application> 

Picking the right finish-args

The flatpak/finish-args: section of your container.yaml determines what permissions the application will have.

Non-sandboxed example, application requires X, and accesses the network

flatpak:
    finish-args: >
        --share=network 
        --socket=x11
        --filesystem=user

Sandboxed example:

flatpak:
    finish-args: >
        --socket=wayland
        --socket=fallback-x11

Non-sandboxed application, application has wayland support, and uses DConf:

flatpak:
    finish-args: >
         --filesystem=host
         --share=ipc
          --socket=fallback-x11
          --socket=wayland
          --socket=session-bus
          --filesystem=~/.config/dconf:ro
          --filesystem=xdg-run/dconf
          --talk-name=ca.desrt.dconf
          --env=DCONF_USER_CONFIG_DIR=.config/dconf

Need DCONF_USER_CONFIG_DIR patch added to Fedora

See http://docs.flatpak.org/en/latest/sandbox-permissions-reference.html and the flatpak-build(1) manual page.

Renames

Basic renaming of an application to use an application ID in your container.yaml.

flatpak:
    rename-desktop-file: eog.appdata.xml
    rename-appdata-file: eog.desktop
    rename-icon: eog

Other keys

The complete list of supported keys from the Flatpak builder manifest file that you can add to the flatpak: section of container.yaml is:

• appstream-license
• appstream-compose
• copy-icon
• desktop-file-name-prefix
• desktop-file-name-suffix
• rename-appdata-file
• rename-desktop-file
• rename-icon

See the flatpak-manifest(1) manual page for documentation.

Doing a local build

$ flatpak-module local-build --install

This is a shortcut for three steps:

$ flatpak-module build-module
$ flatpak-module build-container --from-local 
$ flatpak-module install <application>-master-<version>.oci.tar.gz

If building the module succeeds but building the container fails, and you need to change container.yaml and try again, you can do:

$ flatpak-module build-container --from-local --install

Testing

If installation succeeded, you can now do:

$ flatpak run <application-id>

To try it out.

Requesting module and containers in Fedora

File an issue in https://pagure.io/releng as follows: Would be nice to have a template, or flatpak-module subcommand

Please set up a Flatpak for <application> 
   Owner: <fas login>
   Application: <application>
This requires the following steps:
Create modules/$application in src.fedoraproject.org
Add the module and the flatpak to the appropriate tags:
$ koji add-pkg --owner=$owner f29-modular $application
$ koji add-pkg --owner=$owner f29-flatpak $application

Importing your module content

Once your releng issue has been resolved

$ mv application application.old
$ fedpkg clone modules/<application>
$ cd <application>
$ cp ../application.old/{<application>.yaml, container.yaml} .
$ git add <application>.yaml container.yaml
$ git commit -m “Initial import”
$ git push origin master

Building in Koji

First build the module

$ fedpkg module-build

If that completes successfully, you can then do:

$ fedpkg flatpak-build

https://pagure.io/rpkg/pull-request/361 - for now you can do:

$ koji flatpak-build f28-flatpak-candidate git://pkgs.fedoraproject.org/modules/<application>#origin/master --git-branch=master

Testing the build

Go to the Koji page of the successful Flatpak build, find the download link for the Image Archive and paste that into the command line:

$ flatpak-module install https://kojipkgs.fedoraproject.org/packages/<app>/master/…

Would be nice to have flatpak-module support to do this by NVR or just package name. ‘install --koji <app>’

Creating an update

Not yet working https://github.com/fedora-infra/bodhi/pull/2526 https://github.com/fedora-infra/bodhi/pull/2430

Find the NVR of your flatpak build - if you don’t have it in your terminal scrollback go to https://koji.fedoraproject.org/koji/build and search for builds by your username. It will be something like: myapplication-20180601144429.2

Go to https://bodhi.fedoraproject.org/updates/new and enter the flatpak NVR under Candidate Builds (ignore “Packages”). Enter text under “Update notes” like “Initial Flatpak of <application>”, and hit <Submit>.

Development versions

Ignore for now

If you wish to package a development version of your application, then it needs a separate branch, called ‘devel’, and a separate application ID, for example com.example.MyApplication.Devel. In the simple case, the rename be accomplished in your container.yaml using rename-desktop-file, rename-icon, rename-appdata-file, desktop-file-name-suffix . However, if the application exports D-Bus services, then it will need code changes, which you need to implement within the RPM package. (Create a private-devel branch of the application package, and reference this within <application>.yaml>.