Packaging In Depth
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
/usrthat can’t be bundled with the application
Picking an application ID
To select an appropriate an application ID:
If the application already has a desktop file of this form, that is the application ID.
If the application exports any D-Bus services (Look 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 Flathub 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.
com.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.
Flatpaks in Fedora are different from packages in that there isn’t a separate application version for F36, F37, 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:f38 module, for example.
The module and container versions for your stable release should be in the stable branch of your git repository, and the stream of the module will be the stable stream.
Some documentation for the content of
<application>.yaml is available at https://github.com/fedora-modularity/libmodulemd/blob/main/yaml_specs/modulemd_stream_v1.yaml (for files specifying
version: 1) or https://github.com/fedora-modularity/libmodulemd/blob/main/yaml_specs/modulemd_stream_v2.yaml (for files specifying
The flatpak/finish-args: section of your container.yaml determines what permissions the application will have.
flatpak: finish-args: > --share=network --socket=x11 --filesystem=user
flatpak: finish-args: > --socket=wayland --socket=fallback-x11
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
See http://docs.flatpak.org/en/latest/sandbox-permissions-reference.html and the flatpak-build(1) manual page.
Many existing applications in Fedora do not have an application in standard form. You can add keys to your container.yaml to rename exported resources to match the application ID.
flatpak: rename-appdata-file: eog.appdata.xml rename-desktop-file: eog.desktop rename-icon: eog
The preferred way, however, is to fix the application ID in the RPM packaging, or even better, upstream. The reason this is better is that the system can understand the relationship between the two applications, and won’t show duplicate entries in GNOME Software or the installed application list.
The complete list of supported keys from the Flatpak builder manifest file that you can add to the
flatpak: section of
See the flatpak-manifest(5) manual page for documentation.
Want to help? Learn how to contribute to Fedora Docs ›