Packaging Linux Applications: A Complete Guide to flatpak-builder on Fedora – ITFROMZERO

Table of Contents

Why Linux Developers Can’t Ignore flatpak-builder?

The scenario where an app runs perfectly on your machine but “dies” on a user’s system due to missing libraries is all too familiar for Linux developers. After two years of using Fedora as my primary OS, I’ve realized Flatpak is the most effective lifesaver. Instead of wasting time building separate packages for Ubuntu (.deb), Arch (.pkg.tar.zst), or Fedora (.rpm), you only need to package it once.

Think of flatpak-builder as an automated chef. You give it a “recipe” (a manifest file), and it gathers the ingredients, cooks them in an isolated kitchen (sandbox), and serves the finished dish. The result is a package that runs on almost any modern Linux distribution, including SteamOS on the Steam Deck.

Currently, Flathub serves millions of downloads every month. Getting your app on Flathub not only helps you reach users faster but also completely eliminates worries about system library version conflicts.

Setting Up the Build Environment on Fedora

Fedora is “home turf” for Flatpak, so the installation is extremely quick. However, be prepared with about 2-3GB of disk space as SDKs tend to be quite large.

1. Install Core Tools

Open the terminal and install the builder using the following command:

sudo dnf install flatpak-builder

2. Download the SDK and Runtime

You need a base environment for your app to run. Here, I’m choosing Freedesktop SDK 23.08 – a common standard for apps that don’t rely heavily on GNOME or KDE:

flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install flathub org.freedesktop.Sdk//23.08 org.freedesktop.Platform//23.08

Writing the Manifest: The Soul of a Flatpak Package

The Manifest file (in .yml or .json format) is where you give commands to the system. Don’t let the lines of code confuse you; focus on three main parts: identification, permissions, and source code.

Below is an example for a Python application named itfromzero-app. I’ll save it as org.itfromzero.App.yml.

app-id: org.itfromzero.App
runtime: org.freedesktop.Platform
runtime-version: '23.08'
sdk: org.freedesktop.Sdk
command: itfromzero-app
finish-args:
  - --socket=x11 # Display the interface on the screen
  - --share=network # Allow internet access
  - --filesystem=home:ro # Read-only access to the home directory

modules:
  - name: itfromzero-app
    buildsystem: simple
    build-commands:
      - install -D app.py /app/bin/itfromzero-app
    sources:
      - type: file
        path: app.py

Key Points to Note:

app-id: Must be unique. If you own the domain myapp.com, set it as com.myapp.App.
finish-args: This is the security “fence.” Don’t over-grant permissions. For example, if the app doesn’t need printing, don’t add --socket=cups.
modules: If the app uses third-party libraries (like NumPy or Requests), you must declare them here so the builder can download them automatically.

Build Process and Quick Testing

Once the manifest and app.py file are ready, start the packaging process. I usually use the --force-clean parameter to ensure every build is clean and not affected by leftovers from previous runs.

flatpak-builder --force-clean build-dir org.itfromzero.App.yml

After the command finishes, don’t publish it immediately. Use the command below to run the app directly from the build folder. This is the time to check if buttons work or if the app crashes due to missing file access permissions:

flatpak-builder --run build-dir org.itfromzero.App.yml itfromzero-app

Quick tip: If the app reports a “Permission denied” error, go back and check the finish-args section in the manifest. 90% of beginner errors are found there.

Submitting Your Application to Flathub

Flathub doesn’t host your code; they only host the manifest. This process is like submitting an article for an editor to review:

Fork & Branch: Fork the flathub/flathub repo and create a new branch named after your app-id.
Submit PR: Submit a Pull Request containing your manifest file. The Flathub team will check if your app is safe and complies with community standards.
Bot Verification: A bot system will automatically try to build your app on x86_64 and ARM architectures (like Raspberry Pi).

Specifically, you need to prepare an AppData (XML) file. Without this file, your app will look very “bare” on the app store because it lacks screenshots and a description.

Debugging Techniques for Build Errors

Building a Flatpak rarely succeeds on the first try. Here are three tricks I often use to troubleshoot:

1. Finding Missing Libraries

If you encounter a No such file or directory error during compilation, check if that library has been added to the modules section. Sometimes you need to build 3-4 dependencies before you can build the main app.

2. Inspecting System Logs

Use the flatpak run -vv command to enable verbose mode. Every activity of the app inside the sandbox will be clearly displayed, helping you pinpoint exactly why the app can’t connect to a database or recognize a webcam.

3. Resetting the Environment

If things get too chaotic, clear the build cache using the command:

rm -rf .flatpak-builder build-dir

Mastering flatpak-builder is not just about learning a tool; it’s about professionalizing your software distribution on Linux. Good luck, and may your first app appear on the Flathub homepage soon!