Packaging Tutorial

Creating a Flatpak of an application that is already packaged in Fedora involves two steps. First you need to rebuild the application RPMs along with any dependencies which are not included in the runtime. Then you need to create a container out of the application. 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 flatpak RPMs and containers are stored in git on https://src.fedoraproject.org and builds are coordinated by https://koji.fedoraproject.org. The flatpak for a an application can be found on https://src.fedoraproject.org in the repository flatpaks/<application>; this git repository contains a container.yaml file, which defines how the package is turned into a Flatpak container.

Setup

Install the necessary tools:

$ sudo dnf install flatpak-module-tools

Make sure that your user is in the mock group (both local RPM builds and local container builds use mock).

$ sudo usermod -a -G mock $USER

(You may need to log out and log back in.)

Add Fedora testing flatpak remote:

$ flatpak remote-add fedora-testing oci+https://registry.fedoraproject.org#testing

On Fedora, the testing remote should be already installed, but in disabled state. To enable it run:

$ flatpak remote-modify --enable fedora-testing

And install the Fedora Flatpak Runtime if you don’t already have it installed:

$ flatpak install fedora-testing org.fedoraproject.Platform/x86_64/f42

Creating `container.yaml`

$ mkdir lagrange && cd lagrange
$ flatpak-module init --flathub=lagrange lagrange

This generates an initial version of container.yaml. The --flathub=lagrange option searches Flathub for an application whose name or application ID matches lagrange, and uses the Flathub manifest to initialize container.yaml. If multiple matches are found, they are displayed, and you’ll need to re-run flatpak-module init with a more specific search string.

Let’s look at the container.yaml file.

container.yaml

flatpak:
    id: fi.skyjake.Lagrange
    branch: stable
    runtime-name: flatpak-runtime
    runtime-version: f42
    packages:
    - lagrange
    command: lagrange
    finish-args: |-
        --socket=wayland
        --socket=fallback-x11
        --socket=pulseaudio
        --share=ipc
        --share=network
        --device=dri
        --filesystem=xdg-download
        --filesystem=home:ro

This container.yaml file can be used as is, but often modifications are necessary.

If there is no existing build of the application on Flathub, you can omit the --flathub option to flatpak-module init. In this case you’ll need to pick an application ID and edit container.yaml.

Doing a local build

$ flatpak-module build-rpms-local --auto
$ flatpak-module build-container-local --install

If building the RPMs succeeds but building the container fails, and you need to change container.yaml and try again, you can repeat just the last step.

Testing

If installation succeeded, you can now do:

$ flatpak run fi.skyjake.Lagrange

To try it out.

src.fedoraproject.org request

Please request a new Git repository as follows:

$ fedpkg request-repo --namespace=flatpaks <application>

Importing your flatpak content

Once the repository has been created:

$ mv <application> <application>.old
$ fedpkg clone flatpaks/<application>
$ cd <application>
$ cp ../application.old/container.yaml .
$ git add container.yaml
$ git commit -m "Initial import"
$ git push origin stable

Building in Koji

First build the packages:

$ flatpak-module build-rpms --auto

If that completes successfully, you can then do:

$ flatpak-module build-container

Testing the build

To install the latest successful build from Koji, run:

$ flatpak-module install --koji <application>-flatpak

Creating an update

Find the NVR of your Flatpak build - if you don’t have it in your terminal scrollback go to https://koji.fedoraproject.org/ and search in "Packages" for the <application>-flatpak name.

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>.

Want to help? Learn how to contribute to Fedora Docs ›