flatpak.org/setup/: Improved documentation

[davidhedlund]

Checklist

• I agree to follow the Code of Conduct that this project adheres to.
• If this is an issue with a particular app, I have tried filing it in the appropriate issue tracker for the app (e.g. under https://github.com/flathub/) and determined that it is an issue with Flatpak itself.
• I have searched the issue tracker for a bug that matches the one I want to file, without success.
• This issue is not a report of a security vulnerability (see here if you need to report a security issue).

Flatpak version

1.12.7-1

What Linux distribution are you using?

Ubuntu

Linux distribution version

22.04

What architecture are you using?

x86_64

How to reproduce

Ubuntu [MATE] 22.04 does not require session restart

Tested and reproduced in the following LTS releases:

• ubuntu-mate-22.04.2-desktop-amd64.iso

Install Flatpak

sudo apt install flatpak

Add the Flathub repository

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

Install a package that is small enough for the live distro:

flatpak install flathub org.libretro.RetroArch

No issues found:

• In "Menu" located to the top left a new "Game" section is created where "RetroArch" is added. There is no need to log out/log in for it to be added there.
• Also, flatpak run org.libretro.RetroArch opens RetroArch as expected and without any error output.

Ubuntu [MATE] 24.04 (issue)

Tested and reproduced in the following LTS releases:

• ubuntu-mate-24.04-desktop-amd64.iso
• ubuntu-mate-24.04.1-desktop-amd64.iso

Follow https://flatpak.org/setup/Ubuntu EXCEPT the Restart section

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

Note that the directories 

'/var/lib/flatpak/exports/share'
'/home/x/.local/share/flatpak/exports/share'

are not in the search path set by the XDG_DATA_DIRS environment variable, so
applications installed by Flatpak may not appear on your desktop until the
session is restarted.
$ flatpak install flathub org.libretro.RetroArch
$ flatpak run org.libretro.RetroArch

Note that the directories 

'/var/lib/flatpak/exports/share'
'/home/ubuntu-mate/.local/share/flatpak/exports/share'

are not in the search path set by the XDG_DATA_DIRS environment variable, so
applications installed by Flatpak may not appear on your desktop until the
session is restarted.

bwrap: Creating new namespace failed: Permission denied
error: ldconfig failed, exit status 256

Log out/log in to solve the menu issue:

• Click on "Menu" located in the top left. No menu entry called "Game" have been created, and "RetroArch" is not located there yet.
• Log out and log in again from the desktop environment
• Click on "Menu" located in the top left. A new menu entry called "Game" has been created, and "RetroArch" is now located there.

Flatpak cannot be run in live mode in Ubuntu 24.04 because it requires restart.

After session restart the above issue persists:

$ flatpak run org.libretro.RetroArch
bwrap: Creating new namespace failed: Permission denied
error: ldconfig failed, exit status 256

Also, installing with the --user flag did not help.

Expected Behavior

Change the "Add the Flathub repository" section

From

Flathub is the best place to get Flatpak apps. To enable it, run:
flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

To

Flathub is the best place to get Flatpak apps. To enable it, run:
flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

Note: Flatpak may message "applications installed by Flatpak may not appear on your desktop until the session is restarted." Additionally, when installing packages in live mode, which relies on RAM instead of the HDD, it is advised to have at least 8 GB of RAM to ensure the installation of at least one package and in particular all its dependencies.[1]

Reference
1: For instance, if you use the default RAM allocation of 4 GB in virt-manager, you'll likely encounter difficulties installing most packages. This is due to the limited capacity of the /cow filesystem, which is a copy-on-write filesystem created in RAM. See more info here:

• [Feature request]: Add options to set default setting values for New Virtual Machine virt-manager/virt-manager#789

Change the "Restart" section

From

To complete setup, restart your system. Now all you have to do is install some apps!

To

Now you can install some apps. Note that you may need to restart you system if they do not work.[1]

1: Some distributions may require a reboot, such as Ubuntu 24.04, which makes it impossible to run Flatpak in live mode, while others, like Ubuntu 23.04 and earlier versions, may not have this requirement.

Actual Behavior

Most pages in https://flatpak.org/setup/ says "To complete setup, restart your system.":

• https://flatpak.org/setup/Ubuntu
• https://flatpak.org/setup/Manjaro
• https://flatpak.org/setup/Chrome%20OS
• https://flatpak.org/setup/Red%20Hat%20Enterprise%20Linux
• https://flatpak.org/setup/openSUSE
• https://flatpak.org/setup/Arch
• https://flatpak.org/setup/Debian
• https://flatpak.org/setup/Rocky%20Linux
• https://flatpak.org/setup/Gentoo
• https://flatpak.org/setup/Kubuntu
• https://flatpak.org/setup/Solus
• https://flatpak.org/setup/Alpine
• https://flatpak.org/setup/Mageia
• https://flatpak.org/setup/Pop!_OS
• https://flatpak.org/setup/Raspberry%20Pi%20OS
• https://flatpak.org/setup/Void%20Linux
• https://flatpak.org/setup/SulinOS
• https://flatpak.org/setup/Ataraxia%20Linux
• https://flatpak.org/setup/Deepin
• https://flatpak.org/setup/Pardus
• https://flatpak.org/setup/MX%20Linux
• https://flatpak.org/setup/Pisi%20GNU%20Linux
• https://flatpak.org/setup/EndeavourOS
• https://flatpak.org/setup/GNU%20Guix

Additional Information

"Random idea: We can make flatpak check if the environment looks ok, and if it doesn't, emit a warning." @matthi

• Need to restart after installing flatpak is awkward flatpak#1256 (comment)

[davidhedlund]

@smcv Thank you for transferring the issue to the correct repo.

[razzeee]

"Applications installed by Flatpak may not appear on your desktop until the session is restarted. However, Ubuntu 24.04 requires restart."

That's quiet a bit more technical and not easy to understand, then just saying reboot. That's a problem

[razzeee]

I'm not a native speaker, but the use and understandability of session for normal users is something that worries me.

[davidhedlund]

I'm not a native speaker, but the use and understandability of session for normal users is something that worries me.

I respect your concern, and I'm not a native speaker either. @smcv Can you please opt in?

[davidhedlund]

I dedicated at least three additional hours to thoroughly evaluate flatpak and document the top post in order to improve the guide and provide clearer instructions for users.