Flatpak - Simple guide on how to make bloat your friend and not your enemy

2021-07-05

(last time edited: 2021-11-22)

tags: flatpak, programs, isolation, security

I can't believe I'm writing this blog post. I appreciate minimal software a lot, especially sysadmin tools and minimal servers to get things working quickly. But I need to run big useful programs lately and I don't have the right distribution to do so. Let's embrace Flatpak.

Flatpak

Flatpak is a utility for software deployment and package management for Linux. It is advertised as offering a sandbox environment in which users can run application software in isolation from the rest of the system. Flatpak was developed as part of the freedesktop.org project (formerly known as X Desktop Group or XDG) and was originally called xdg-app.

Package mantainers from different Linux distributions have no problem updating minimal packages because they don't have to deal with many dependencies; debugging and compiling gets a lot easier. The problem resides when packages are too big and bloaty, but also very useful! For example the Open Broadcaster Studio or any other from the Flathub repository. Linux systems are very diverse, some distributions don't depend on glibc and use musl, or use LibreSSL instead of OpenSSL. Things get complicated for package mantainers and even for us who want to run a program with a feature that is not available (compiled) for our system.

This blog post goes to show that Flatpak can resolve many problems and brings lots of goodies:

This can bring a few other new problems we have never met before. Such as managing permissions correctly, using D-Bus correctly, connecting to PulseAudio server socket, displaying desktop themes correctly.

Flatpak relays on static library linking making disk usage a lot more bigger. And programs need X11 permissions which that could also compromise your system.

Creating the panacea of software security is something really difficult to achieve. Here comes the big dilema of security vs convenience. Flatpak is still not very mature and needs to be polished in the next years to come.

Flatpak have many dependencies, some of the most important are Bubblewrap, D-Bus, FUSE and many more libs.

You will encounter different problems, it really depends on the distribution you're installing Flatpak. So cross fingers.

Also, Flatpak is not very popular yet. It goes very against the UNIX philosophy and lots of developers have started flame wars and more flame wars about the technology behind it. Isolation is very difficult to achieve when a program requires many permissions. If you are into security you might want to check other software based on isolation, such as Snap Packages which is close competitor to Flatpak, Firejail or AppArmor.

Anyways, Flatpak is still the only sane and balanced option I found to run the programs I need. Also it's the best way to separate bloat programs from system programs without creating a dependency hell. I guess Flatpak is my new friend.

Let's get going and install the bloat manager master. Remember Flatpak is the program and Flathub is the remote repository.

Requirements

Flatpak works out of the box but depends on D-Bus (Desktop Bus) for communication between processes and also relies heavily on XDG (X Desktop Group) specifications, which is a standard created by the Freedesktop.org community.

There are some things you wanna check before using Flatpak graphical programs.

These variables are read when your login user session starts and Flatpak will read them. You can change timezone, locale, etc.

Also the XDG environment variables are absolutely crucial for Flatpak. You need them declared otherwise you will encounter many problems.

Using Elogind there is no need to declare XDG_* environment variables. But if I can recall correctly there is a chance that if you don't use any session manager you will have to declare them manually.

Elogind sets up these variables automatically. You can read them by using:

$ printenv | grep XDG

XDG_DATA_DIRS
XDG_SESSION_CLASS
XDG_SEAT
XDG_VTNR
XDG_RUNTIME_DIR
XDG_SESSION_TYPE
XDG_SESSION_ID

The content of your ~/.profile file should be somethiung like this, although like I said before it's not necessary to set up XDG.

# ...

LANG_en_US.UTF-8
export LANG

GTK_THEME=Adwaita:dark
export GTK_THEME

TZ=Africa/Kampala
export TZ

QT_QPA_PLATFORMTHEME=gtk3
export QT_QPA_PLATFORMTHEME

XDG_DATA_HOME="$HOME/local/share"
export XDG_DATA_HOME

XDG_CACHE_HOME="$HOME/.cache"
export XDG_CACHE_HOME

XDG_CONFIG_HOME="$HOME/.config"
export XDG_CONFIG_HOME

XDG_RUNTIME_DIR=$(mktemp -d /tmp/$(id -u)-runtime-dir.XXX)
export XDG_RUNTIME_DIR

# ...

The content of your ~/.xprofile file should be like this. You need to export the DBUS_SESSION_BUS_ADDRESS environment variable. You do this by installing dbus-x11 previously and exporting the variable in ~/.xprofile. using the dbus-launch binary.

# ...

export "$(dbus-launch)"

# ...

Of course the ~/.xprofile file needs to be run every time to start a X11 session. This is done by ~/.xinitrc when you run startx.

Example:

#!/bin/sh

[ -f ~/.xprofile ] && . ~/.xprofile

openbox-session

Basic installation and usage

First check all added remote repositories in our system.

$ flatpak remotes -v

It should list something like this.

Name    Options
flathub system
flathub user

Remotes

Flathub is the official repository for Flatpak and it contains software under many licenses. FLOSS and propietary can be found in Flathub.

Fedora also has their own only-FLOSS repository for Flatpak. At the day of editing this blog (18-10-2021) the Fedora remote contains only 96 packages. You can find it here and add it using:

$ flatpak remote-add -v --user --if-not-exists fedora oci+https://registry.fedoraproject.org

If your Flatpak installation it's not listing the Flathub repository for user then add it.

$ flatpak remote-add -v --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

Then start installing applications for any architecture, usually x86_64 is default and there is no need to declare it via argument.

$ flatpak install --user --arch x86_64 flathub io.gitlab.librewolf-community

List all the current installed applications.

$ flatpak list

List all packages inside the Flathub remote.

$ flatpak remote-ls flathub

List all packages inside the Fedora remote.

$ flatpak remote-ls fedora

Run

Run an application from our virtual terminal.

$ flatpak run io.gitlab.librewolf-community

or just click graphically on the .desktop file icon created at the directory path ~/.local/share/flatpak/exports/share/applications.

The program will usually appear automatically in X11 graphical launchers such as jgmenu, Rofi, or even j4-desktop-dmenu.

Flatpak applications won't read your system dark theme automatically unless you export an specific shell variable to your X11 session.

Add this text in ~/.profile

export GTK_THEME=Adwaita:dark

But as I explained before, you can also set up shell environments variables when you launch the window manager. It's up to your taste.

Permissions

Show permissions of a certain application.

$ flatpak info --show-permissions programid

It's possible to manage permissions via Flatseal.

Flatseal is a graphical friendly utility to change Flatpak application permissions.

You can install it by just doing:

$ flatpak install com.github.tchx84.Flatseal

and run it by clicking on the desktop application icon for Flatseal, or using the command line command:

$ flatpak run com.github.tchx84.Flatseal

It's possible to manage permissions using plain terminal but Flatseal is a lot way faster and easier to use.

Be aware that if you remove multiple socket permissions from any app will end up with a non-working application. X11 windowing system permission (socket=x11) is most likely the only permission you need to run a graphical application. Some applications need more permissions, for example: Firefox heavily requires Network (share=network).

Run a program sandboxed

The --sandbox argument is very useful to disable all permissions of a program we want to run.

You can just run any program in an isolated environment in this similar fashion and then via some arguments start enabling what we need.

$ flatpak run --sandbox --no-session-bus --no-a11y-bus --no-documents-portal --socket=x11 --socket=pulseaudio --share=network --device=dri --filesystem=~/.mozilla:create org.mozilla.firefox

We are disabling mostly all permissions and:

We are permitting:

This is by far the best way I've found to isolate programs with Flatpak.

Other programs make use of different permissions. You just need to figure out which permissions you require the most for each program.

For more information on sandbox permissions take a look at the docs.

Programs IDs

Programs in a repository are identified with this name style, explained here. These IDs are not so comfy to remember but you'll use them all the time to install, search, get information of a program, etc. Some are very redundant but it's for a good purpose.

Examples:

com.obsproject.Studio
io.gitlab.librewolf-community
org.mozilla.firefox
org.libretro.RetroArch
info.mumble.Mumble

Search for a program

$ flatpak search programid

or

$ flatpak search --arch=x86_64 programid

Processes

Check current processes.

$ flatpak ps

Reset application configurations

There isn't an specific command to do a clean reset for Flatpak apps. You just need to do:

$ rm -rf ~/.var/app/${FLATPAK_APP_ID}

Replace the ${FLATPAK_APP_ID} variable with the Flatpak ID application, duh.

Other remote repositories

If you are not able to find a package in the default remote repository there is a possibility it's in the beta remote repository. For example the Lutris flatpak package is still in beta development.

Add the beta remote repository and then look for a package using the search argument.

$ flatpak remote-add --user flathub-beta https://flathub.org/beta-repo/flathub-beta.flatpakrepo

$ flatpak search lutris

$ flatpak install --user net.lutris.Lutris

Lutris also needs several dependencies installed. It's not necessary to install the beta version for these dependencies (runtimes). Lutris (beta) will run with non-beta release of dependencies.

runtime/org.gnome.Platform/x86_64/41
runtime/org.gnome.Platform.Compat.i386/x86_64/41
runtime/org.freedesktop.Platform.GL.default/x86_64/21.08
runtime/org.freedesktop.Platform.GL32.default/x86_64/21.08

$ flatpak install --user org.freedesktop.Platform.GL.default org.gnome.Platform.Compat.i386 org.freedesktop.Platform.GL32.default

There are other repos like the GNOME nightly repository if you wanna install Nautilus. Though I don't recommend using it since it's a program in development.

$ flatpak remote-add --user gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo

$ flatpak search Nautilus

$ flatpak install --user org.gnome.NautilusDevel

Locales

Changing language localization in Flatpak it's just as easy as setting up an environment variable.

In your ~/.profile you can set up a global env for your session and it will maintain the setting for that session and for every Flatpak package.

#...

LANG=es_US.UTF-8
export LANG

#...

It is also possible to run a program with a different locale overriding the global environment variable.

$ LANG=en_US.UTF-8 flatpak run org.libretro.RetroArch

Remember changing locales will only work with programs that have a Locale package installed in your Flatpak directories.

If you wanna check which packages have locales available just do:

$ flatpak list --user -a | grep Locale

Those are the programs with translations available. If a program isn't listed is most likely that it doesn't have localization.

Steam and Flatpak

Some games require some tinkering to work on Linux.

For example, the game Fight'N Rage requires .NET Framework 4.0.

First install Protontricks. This configuration wrapper for Proton is already bundled in the Flathub repositories.

$ flatpak install flathub com.github.Matoking.protontricks

Then execute Protontricks from terminal to install dotnet40 (.NET Framework 4.0). You need to have the game installed already.

$ flatpak run --command=protontricks com.valvesoftware.Steam $STEAM_APP_ID dotnet40

Other random tips

It's usually convenient to periodically run:

$ flatpak remove --unused

Check size of Flatpak apps:

$ flatpak list --columns=name,application,size

If by some reason you cannot install packages with Flatpak and you get nasty errors such as:

error: Failed to read commit 102nd1829nc1982ne9128dnasoiddnad: No such metadata object 1920j1920wj1209.dirtree

You can try many debugging commands, the recommended one is:

$ flatpak repair --user

These other commands can help with different errors.

$ flatpak update -v

Debugging

If you wanna login into the container of your Flatpak application you need to declare a shell login via the --command argument, for example.

$ flatpak run --user --sandbox --no-a11ybus --no-session-bus --no-documents-portal --command=bash --socket=x11 --share=network org.nmap.Zenmap

I called the Bash Unix shell to be run inside the Zenmap flatpak. Now every command I run will be done inside the org.nmap.Zenmap sandboxed instance/container that is running.

If you compare the output of

$ ls

with a ls outside the container, you will see the difference.

What can you do inside the container? You can modify settings or read how configuration files are stored by each container.

When your Flatpak application needs access to MTP devices you can debug if the device is being mounted properly using this type of command shell login.


There are other ways to debug what's going on everytime we run a Flatpak program and how it communicates with the local or system Session Bus (if there is one). If your Flatpak program is sandboxed with --no-session-bus you will not see much verbose information.

D-Bus monitor depends on a binary called dbus-launch which comes included in a package called dbus-x11.

$ dbus-monitor

and

$ dbus-monitor --profile

will show information.

It is not necessary to run D-Bus as a root service (OpenRC / SystemD / Runit) to run flatpak programs but I do totally recommend using Elogind as service daemon in the default init runlevel.

Elogind takes care of D-Bus. With Elogind you don't need to use dbus-run-session to start your Window Manager from ~/.xinitrc. Elogind makes Flatpak usage absolutely simple.

Understanding the File Chooser portal

Even if your Flatpak programs are sandboxed or not, you might need access to your directories. Especially if these directories were explicitly declared when you run the Flatpak program in this similar format: $ flatpak run --sandbox --filesystem=home:ro org.mozilla.firefox.

The file chooser portal, along many other things, is an implementation part of the Freedesktop (also known as Freedesktop.org or X Desktop Group).

As I did my research, I've found that it's possible to use native or external file chooser GUIs.

First install xdg-desktop-portal-gtk.

Then I was able to run the file chooser correctly in Qt apps by setting up this environment variable in the ~/.profile file.

# ...

QT_QPA_PLATFORMTHEME=gtk3
export QT_QPA_PLATFORMTHEME

# ...

You will see a slightly change in the Qt theme but the file chooser dialog will load correctly.

Plugins

Flatpak makes it able so you can install plugins for Flatpak programs.

I found this tool for input display, input-overlay which was built into the Flathub repository.

You can install it doing:

$ flatpak install --user com.obsproject.Studio.Plugin.InputOverlay

Once it's done, you can see the files were downloaded separately in a different runtime directory than the OBS.

~/.local/share/flatpak/runtime/com.obsproject.Studio.Plugin/InputOverlay/x86_64/stable/active/files

The OBS program will still be able to read the plugin correctly.

You can see more info doing:

$ flatpak info com.obsproject.Studio.Plugin.InputOverlay

By the date I wrote this 22/10/2021 the version I downloaded from Flathub is probably lower than 5.0 and only reads .ini files for input mapping.

The standalone release from Github is version 5.0 and now only reads .json mapping instead of .ini files.

I don't recommend install plugins for OBS via Flathub, but it's a nice option to keep in mind for other applications.

SDKs access

Some programs like Geany, Neovim or VSCode want access to development tools also known as SDK (software development kit) or additional programming languages and their interpreters. Flatpak can't provide access to these tools when you're running a program in a sandbox (isolated).

What you need to do is first install the extensions using Flatpak. In this example I'm installing Go.

$ flatpak install --user flathub org.freedesktop.Sdk.Extension.golang

Then you need to pass this variable so Flatpak can read it.

$ FLATPAK_ENABLE_SDK_EXT=golang run im.neovim.nvim

Of course this is just example on how to make Go accessible to Neovim.

To search for other SDKs use the search utility.

$ flatpak search <package>

Downgrade Flatpak package version

First look for a commit.

$ flatpak remote-info --log flathub <application>

Then deploy that commit.

$ flatpak --user update --commit=d1290jnd10928dn1029dn1029dn1290d <application>

And disable updates for that specific application.

$ flatpak --user mask <application>