Package Applications as Flatpaks

tags: `flatpak`, `GTK`, `pywebview`, `HTTP server`, `python`, `bottle`

This includes examples to package applications as flatpak apps.

Documents from Flatpak

Previous lightning talk: Package a PyApp as a Flatpak Package: An HTTP Server for Example

The Comparison Between Container and Flatpak

Image Not Showing Possible Reasons

The image was uploaded to a note which you don't have access to
The note which the image was originally uploaded to has been deleted

Learn More →

Container's key tech: chroot, control groups (cgroups), Union Filesytem, and namespaces …
Flatpak uses:
- Sandbox idea implemented by bubblewrap, which is like a super-powered version of chroot.
  - Each file, including binary and library in the container cannot be shared with other containers. Unless the files come from the based on container image.
- OSTree uses FUSE (Filesystem in Userspace) for mounting filesystem now.
  https://github.com/ostreedev/ostree/blob/v2023.7/configure.ac#L336-L338
  - A flatpak application is based on a runtime, then adds some more files. The runtime is share with other flatpak applications. And, the runtime provides basic binaries and libraries.

Some flatpak's security discussion:

Install Flatpak Tools

Some major Linux distributions, like Fodora, openSUSU and Endless OS have already pre-installed flatpak. Please follow Flathub's setup for your OS distribution. If it is not installed, basically install it like:

apt install flatpak flatpak-builder
yum install flatpak flatpak-builder
dnf install flatpak flatpak-builder
pacman -S flatpak flatpak-builder
apk add flatpak flatpak-builder
…

Then, add the Flathub repository

flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

The flatpak is for common usage, and flatpak-builder is for packaging as a flatpak package. Not only x86(_64) platforms, but also arm64 and so on …

Manual

Flatpak Runtime

The org.freedesktop.Sdk runtime commands for developing, like sh & echo, compiler gcc, and python & pip.

$ flatpak run --command=sh org.freedesktop.Sdk//23.08
[📦 org.freedesktop.Sdk ~]$ ls -l /bin/{sh,echo,gcc,python,pip}
-rwxr-xr-x 5 nfsnobody nfsnobody 45736 Jan  1  1970 /bin/echo
lrwxrwxrwx 1 nfsnobody nfsnobody    28 Nov  5 18:44 /bin/gcc -> x86_64-unknown-linux-gnu-gcc
-rwxr-xr-x 7 nfsnobody nfsnobody   220 Jan  1  1970 /bin/pip
lrwxrwxrwx 1 nfsnobody nfsnobody    16 Nov  5 18:44 /bin/python -> /usr/bin/python3
lrwxrwxrwx 1 nfsnobody nfsnobody     4 Nov  5 18:44 /bin/sh -> bash

The org.freedesktop.Platform runtime has commands for common usage, like sh & echo and python. But, no development tools.

$ flatpak run --command=sh org.freedesktop.Platform//23.08
[📦 org.freedesktop.Platform ~]$ ls -l /bin/{sh,echo,gcc,python,pip}
ls: cannot access '/bin/gcc': No such file or directory
ls: cannot access '/bin/pip': No such file or directory
-rwxr-xr-x 5 nfsnobody nfsnobody 45736 Jan  1  1970 /bin/echo
lrwxrwxrwx 1 nfsnobody nfsnobody    16 Oct 31 20:34 /bin/python -> /usr/bin/python3
lrwxrwxrwx 1 nfsnobody nfsnobody     4 Oct 31 20:34 /bin/sh -> bash

PS. More well-known runtimes in Available Runtimes.

Common Usage

Installation

If it is GNOME desktop, you can install flatpak applications from the Software/App Center directly:
Image Not Showing Possible Reasons
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Learn More →
Or, download the .flatpakref from Flathub website:
Image Not Showing Possible Reasons
- The image was uploaded to a note which you don't have access to
- The note which the image was originally uploaded to has been deleted
Learn More →
Then, install application with the downloaded .flatpakref:
```
flatpak install <Application ID>.flatpakref
```
Or, install the application with flatpak command directly:
```
flatpak install [flathub] <Application ID>
```
The "flathub" is the Flathub "REMOTE".

Execute the Application

Click the desktop launcher with the icon.
Or, run with flatpak command:
```
flatpak run <Application ID>
```

Uninstallation

If it is GNOME desktop, you can uninstall the application from Software/App Center.
Or, uninstall the application with flatpak command:
```
flatpak uninstall [--delete-data] <Application ID>
```
"–delete-data": Delete app data

Build A Simple Flatpak App

Go into work directory

Have a source file run.sh:

$ cat run.sh 
#!/bin/sh

echo "Hello world!"

Have the manifest io.github.starnight.simpledemo.yml for build:

$ cat io.github.starnight.simpledemo.yml 
app-id: io.github.starnight.simpledemo
runtime: org.freedesktop.Platform
runtime-version: '23.08'
sdk: org.freedesktop.Sdk
command: run.sh

modules:
  - name: simpledemo
    buildsystem: simple
    build-commands:
      - install -D run.sh /app/bin/run.sh
    sources:
      - type: file
        path: run.sh

Note: More sources types can be found in Manifests' Modules.
PS. You may need the SDK. It can be installed from Flathub:

flatpak install flathub org.freedesktop.Sdk//23.08

Build the io.github.starnight.simpledemo as a flatpak app, and install it:

flatpak-builder build-dir io.github.starnight.simpledemo.yml --force-clean --install --user

Check io.github.starnight.simpledemo is installed:

$ flatpak list 
Name                  Application ID                  Version  Branch  Origin            Installation
simpledemo            io.github.starnight.simpledemo           master  simpledemo-origin user
...
Freedesktop Platform  org.freedesktop.Platform        23.08.6  23.08   flathub           system
...
Freedesktop SDK       org.freedesktop.Sdk             23.08.6  23.08   flathub           system
...

Run the io.github.starnight.simpledemo flatpak app

$ flatpak info io.github.starnight.simpledemo
          ID: io.github.starnight.simpledemo
         Ref: app/io.github.starnight.simpledemo/x86_64/master
        Arch: x86_64
      Branch: master
      Origin: simpledemo-origin
  Collection: 
Installation: user
   Installed: 2.0 kB
     Runtime: org.freedesktop.Platform/x86_64/23.08
         Sdk: org.freedesktop.Sdk/x86_64/23.08

      Commit: badf1daffd1f6ec3b4d3ca35bab60b4beecb15b22e7b3dc8fa041609d8913040
     Subject: Export io.github.starnight.simpledemo
        Date: 2023-11-05 14:37:17 +0000

$ flatpak run --command=ls io.github.starnight.simpledemo /app/bin
run.sh

$ flatpak run io.github.starnight.simpledemo
Hello world!

A GTK Demo Flatpak App

Get the GTK app in flatpak demo:

git clone https://github.com/starnight/flatpak-example-gtkdemo

GNOME 45 runtime has GTK 4 library:

$ flatpak run --command=sh org.gnome.Sdk//45
[📦 org.gnome.Sdk ~]$ ls -l /lib/x86_64-linux-gnu/libgtk-4*
lrwxrwxrwx 1 nfsnobody nfsnobody      13 Oct 31 20:34 /lib/x86_64-linux-gnu/libgtk-4.so -> libgtk-4.so.1
lrwxrwxrwx 1 nfsnobody nfsnobody      20 Oct 31 20:34 /lib/x86_64-linux-gnu/libgtk-4.so.1 -> libgtk-4.so.1.1200.3
-rwxr-xr-x 3 nfsnobody nfsnobody 8999080 Jan  1  1970 /lib/x86_64-linux-gnu/libgtk-4.so.1.1200.3

Follow README's Build, and then Execute.

A WebView Demo Flatpak Using pywebview

Get the WebView app in flatpak demo:

git clone https://github.com/starnight/flatpak-example-pywebview

Follow README's Build, and then Execute.
- Click the desktop launcher with the icon
- It launches the WebView app

Dependent Modules

Because this example is written in Python and uses pywebview, which depends on bottle …, and more. The dependecies heads are listed in requirements.txt. The dependencies, like pywebview and bottle … must be installed as part of the flatpak app as well. So, we need flatpak-builder-tools's flatpak-pip-generator to generate the required modules’ meta information for the manifest from requirements.txt.

$ git clone https://github.com/flatpak/flatpak-builder-tools
$ python3 ~/flatpak-builder-tools/pip/flatpak-pip-generator --requirements-file=requirements.txt

The required modules’ meta information is generated & saved as python3-requirements.json in Build's step 3. Then, python3-requirements.json is invoked as a module by the flatpak's manifest.

PS. flatpak-builder-tools depends on requirements-parser

Exported Resources to Desktop

According to Freedesktop.org Specifications:

Desktop Entry Specification defines desktop entry, or known as desktop launcher <application ID>.dekstop. The desktop launcher should be saved under path $XDG_DATA_DIRS/applications.
Icon Theme Specification defines the dekstop launcher's icon. The icon should be saved under path $XDG_DATA_DIRS/icons.

Because this flatpak demo is in user installations, the desktop launcher and the icon in the flatpak are exported into user's ~/.local/share/flatpak/exports/share:

$ echo $XDG_DATA_DIRS
/home/zack/.local/share/flatpak/exports/share:/var/lib/flatpak/exports/share:/usr/local/share/:/usr/share/

$ ls -l ~/.local/share/flatpak/exports/share/applications/io.github.starnight.http.desktop 
lrwxrwxrwx 1 zack zack 111 Nov 10 22:16 /home/zack/.local/share/flatpak/exports/share/applications/io.github.starnight.http.desktop -> ../../../app/io.github.starnight.http/current/active/export/share/applications/io.github.starnight.http.desktop
$ ls -l ~/.local/share/flatpak/exports/share/icons/hicolor/scalable/apps/io.github.starnight.http.svg 
lrwxrwxrwx 1 zack zack 131 Nov 10 22:16 /home/zack/.local/share/flatpak/exports/share/icons/hicolor/scalable/apps/io.github.starnight.http.svg -> ../../../../../../app/io.github.starnight.http/current/active/export/share/icons/hicolor/scalable/apps/io.github.starnight.http.svg

Flatpak Installation Path

According to flatpak-installation:

system-wide: $prefix/var/lib/flatpak/

$ flatpak info --show-location org.gnome.gedit
/var/lib/flatpak/app/org.gnome.gedit/x86_64/stable/09a23c12f530b56b84db84dc8cbc24d949f352e154c1a5aef5cdaaf3df2f573c

user: $HOME/.local/share/flatpak/

$ flatpak info --show-location io.github.starnight.http
/home/zack/.local/share/flatpak/app/io.github.starnight.http/x86_64/master/e44f532e79374461e4e3c32db5f11ef75c1a7dee03fa7634c64a46c88dff5f19

Appendix

Publish to Flathub

Flathub's For app authors:

Update Modules (Half) Automatically

Flatpak app builds with external data (git checkouts, tarballs, simple files, etc.) listed as modules in the manifest. Maintaining the external data's source/link is important. Flatpak External Data Checker is a tool to create pull requests to the repository on GitHub automatically, if there is new version of the external data's source/link.

Runner: GitHub's action as the runner
And, add "x-checker-data" into each modules of the manifest

Will Thompson shared a talk: "Automate your Flatpak manifest updates today"

Image Not Showing Possible Reasons

The image file may be corrupted
The server hosting the image is unavailable
The image path is incorrect
The image format is not supported

Learn More →

The WebView Demo uses Flatpak External Data Checker to update the dependencies:

GitHub action
The x-checker-data section as an example

AppStream MetaInfo

This is more related to the original application, because it should come from there. However, Flathub reads the application's metainfo, then renders the introduction on Flathub. And, Software/App Center does the same thing.

AppStream metadata:

AppStream's Metadata Quickstart
AppData guidelines

Cassidy James Blaede shared a talk: "How to make a delightful app listing"

Image Not Showing Possible Reasons

The image file may be corrupted
The server hosting the image is unavailable
The image path is incorrect
The image format is not supported

Learn More →

Note: The talk starts at 12 minute of the video.

Package Applications as Flatpaks

tags: flatpak, GTK, pywebview, HTTP server, python, bottle

Documents from Flatpak

The Comparison Between Container and Flatpak

Install Flatpak Tools

Manual

Flatpak Runtime

Common Usage

Installation

Execute the Application

Uninstallation

Build A Simple Flatpak App

A GTK Demo Flatpak App

A WebView Demo Flatpak Using pywebview

Dependent Modules

Exported Resources to Desktop

Flatpak Installation Path

Appendix

Publish to Flathub

Update Modules (Half) Automatically

AppStream MetaInfo

Read more

Use Godot First Time

DBus

PyCon TW 2023

Developing with [新唐科技(Nuvoton)](https://www.nuvoton.com/)'s ARM Cortex-M Development Board

tags: `flatpak`, `GTK`, `pywebview`, `HTTP server`, `python`, `bottle`