Alpine Linux - User contributions [en]

Flatpak

2025-12-06T14:27:38Z

H8d13:

[https://flatpak.org/ Flatpak] is a technology for building and distributing applications with the goal of having a universal package format for all Linux distributions.

== Prerequisites ==

* [[Repositories#Managing_repositories|Enable]] community repository.
* Enable [[D-Bus]], specifically [[D-Bus#D-Bus session|D-Bus session]] needs to be started separately for each user.
* Enable [[Polkit]].
* Ensure that [[#Portals|portal]] packages are installed and running.

== Installation ==

Following instructions are based on [https://flathub.org/setup/Alpine official Flatpak guide] with additional customisations.

=== Install Flatpak ===

Install {{Pkg|flatpak}} package using the command: {{cmd|# apk add {{Pkg|flatpak}}}}

=== Install the flatpak plugin for software managers ===

Install the Flatpak plugin Software for either the GNOME Software (since v3.13) or KDE Discover (since v3.11), making it possible to install apps without needing the command line.
:To install, for GNOME Software run:{{cmd|# apk add gnome-software-plugin-flatpak}}
:For KDE Discover run:{{cmd|# apk add discover-backend-flatpak}}

=== Add the Flathub repository ===

Next you need to add a repository, for this guide we will use the recommended repository, [https://flathub.org Flathub]. {{cmd|$ flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo}}

Flatpak is now ready to use immediately, however flatpak desktop entries will not appear until you restart your desktop session by logging out and then logging back in.

Now all you have to do is install apps!

== Flatpak usage ==

To get all of the available options to use with the '''flatpak''' command run: '''flatpak --help''' or '''flatpak -h'''

=== Search for flatpak apps ===

To search for applications run '''flatpak --user search <appplicationname>'''

Example:

~'''$''' flatpak --user search chromium

Name Description Application ID Version Branch Remotes
Chromium Web Browser The web browser from Chromium project org.chromium.Chromium 96.0.4664.93 stable flathub
Chromium B.S.U. Fast paced, arcade-style, top-scrolling space shooter net.sourceforge.chromium-bsu 0.9.16.1 stable flathub
ungoogled-chromium A lightweight approach to removing Google web service dependency com.github.Eloston.UngoogledChromium 96.0.4664.45 stable flathub


=== Install flatpak apps ===

When installing a flatpak app, a number of questions regarding what permissions the app requires and what runtimes or other software it needs will be asked.

To install a package run '''flatpak --user install <applicationname>'''

~'''$''' flatpak --user install com.github.Eloston.UngoogledChromium

Looking for matches…

com.github.Eloston.UngoogledChromium permissions:
ipc network cups pulseaudio wayland x11
devices file access [1] dbus access [2] bus ownership [3] system dbus access [4]

[1] /run/.heim_org.h5l.kcm-socket, home, xdg-run/pipewire-0
[2] org.freedesktop.FileManager1, org.freedesktop.Notifications, org.freedesktop.secrets, org.gnome.SessionManager
[3] org.mpris.MediaPlayer2.chromium.*
[4] org.freedesktop.Avahi, org.freedesktop.UPower

ID Branch Op Remote Download
1. com.github.Eloston.UngoogledChromium.Codecs stable i flathub < 1.1 MB
2. com.github.Eloston.UngoogledChromium.Locale stable i flathub < 112.8 kB
3. com.github.Eloston.UngoogledChromium stable i flathub < 119.0 MB

Proceed with these changes to the system installation? [Y/n]:


or if you don't know or don't want to type the exact package name:

~'''$''' flatpak --user install chromium

Looking for matches…
Similar refs found for ‘chromium’ in remote ‘flathub’ (system):

1) app/net.sourceforge.chromium-bsu/x86_64/stable
2) runtime/com.github.Eloston.UngoogledChromium.Codecs/x86_64/stable
3) runtime/org.chromium.Chromium.Codecs/x86_64/stable
4) app/org.chromium.Chromium/x86_64/stable
5) app/com.github.Eloston.UngoogledChromium/x86_64/stable

Which do you want to use (0 to abort)? [0-5]:


=== Remove flatpak apps ===

To remove a package run: '''flatpak --user remove <applicationname>'''

~'''$''' flatpak --user remove com.github.Eloston.UngoogledChromium

ID Branch Op
1. com.github.Eloston.UngoogledChromium stable r
2. com.github.Eloston.UngoogledChromium.Codecs stable r
3. com.github.Eloston.UngoogledChromium.Locale stable r

Proceed with these changes to the system installation? [Y/n]:


or if you don't know or don't want to type the exact package name:

~'''$''' flatpak --user remove chromium

Similar installed refs found for ‘chromium’:

1) app/com.github.Eloston.UngoogledChromium/x86_64/stable (system)
2) runtime/com.github.Eloston.UngoogledChromium.Codecs/x86_64/stable (system)
3) All of the above

Which do you want to use (0 to abort)? [0-3]:


== Portals ==

Due to their sandboxing, flatpaks require the use of [https://docs.flatpak.org/en/latest/desktop-integration.html#portals portal]. The portal frontend service for Flatpak i.e [https://flatpak.github.io/xdg-desktop-portal/ XDG Desktop Portal] relies on backends provided by the toolkits. So ensure that {{Pkg|xdg-desktop-portal}} package along with the appropriate backend package from the list of {{pkg|xdg-desktop-portal-*}} packages is installed.

Once installed, [[Desktop_environments_and_Window_managers#Desktop_environments|Desktop Environment]] autostart these portals. However, minimal desktops like [[Sway#Flatpaks|Sway]] require configuration to start the portals and may even require multiple backends.

To test, if portals are properly configured, issue the command:{{Cmd|<nowiki>$ dbus-send --session --print-reply --dest=org.freedesktop.portal.Desktop /org/freedesktop/portal/desktoporg.freedesktop.portal.Desktop.GetApplications</nowiki>}}

The output "Error org.freedesktop.DBus.Error.ServiceUnknown: The name org.freedesktop.portal.Desktop was not provided by any .service files" for the above command indicates that portals are not configured properly.

== Troubleshooting ==

=== Permission errors ===

If you receive errors about permissions then you may need to add your user to the '''flatpak''' group.

{{Note|You need to log out and log back in or reboot for the group change(s) to take effect}}

=== Application launch errors ===

If the application is not starting try running it with {{Cmd|<nowiki>flatpak run the.application.name</nowiki>}} on a terminal. If this yields an a dbus error starting with ''Failed to connect to session bus'' then you might solve this by adding

{{Cmd|<nowiki>export $(dbus-launch)</nowiki>}}

in {{Path|/etc/profile}}.

=== Fixing audio issues ===

Make sure that [[XDG_RUNTIME_DIR]] is properly configured and re-login if necessary.

When you launch a Flatpak you will need to start pulseaudio as well:

{{Cmd|$ pulseaudio --start && flatpak run com.example.Example}}

=== Unable to upload files ===

If you are unable to upload files from the host, this maybe due to [https://docs.flatpak.org/en/latest/sandbox-permissions.html Flatpak sandbox] and you may have to manually add the authorization.

This can be done with the following commands:

{{Cmd|<nowiki>$ flatpak override ApplicationID --filesystem=/home/user/Downloads</nowiki>}}

Where ''ApplicationID'' is given by:

{{Cmd|$ flatpak list}}

For example:

{{Cmd|<nowiki>$ flatpak override org.signal.Signal --filesystem=/home/user/Downloads</nowiki>}}

=== Error while opening repository ===

There is a current issue where sometimes flatpak will try to read the system-wide repository even if your install is with --user. This will result in failure to launch a flatpak application with the terminal reading ""error: While opening repository /var/lib/flatpak/repo: opening repo: opendir(/var/lib/flatpak/repo): No such file or directory". An alpine user has posted more information, as well as a workaround, at https://github.com/flatpak/flatpak/issues/5488

=== GDBus Error ===

Below errors occur, if your flatpak application fails to interface with the portal. This can cause issues such as with opening your file directories from a flatpak application.

<pre>
(firefox:12345): Gtk-WARNING **: 12:00:00.000: Unable to load an interface for org.freedesktop.portal.FileChooser: **GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown:** The name **org.freedesktop.portal.Desktop** was not provided by any .service files
</pre>

Ensure that [[#Portals|portals]] are installed and started.

=== SSL Certificates errors Electron ===

Bellow error occurs when running specific runtimes. Especially Electron dependent apps (a good reason to use Flatpak in the first place).

<pre>
ERROR:ssl_client_socket_impl.cc(960) handshake failed; returned -1, SSL error code 1, net_error -202
</pre>

Fixed using:

{{Cmd|<nowiki>$ doas apk add p11-kit-trust p11-kit-server nss-tools
$ doas update-ca-certificates</nowiki>}}

== See also ==

* [https://flatpak.org/setup/Alpine/ Official setup Guide]
* [https://docs.flatpak.org/en/latest/available-runtimes.html Flatpak - available runtimes]
* [https://flatpak.org/ Flatpak]
* [https://flathub.org/ Flathub]
* [https://winepak.github.io/ Winepak]

[[Category:Package Manager]]

GNOME

2025-11-29T14:14:19Z

H8d13:

[https://www.gnome.org/ Gnome Desktop] aims to get things done with ease, comfort, and control.

== Prerequisites ==
{{:Include:Desktop prerequisites}}
{{Tip|Except for the first two [[#Prerequisites|Prerequisites]], all the others are automatically handled by [[#Installation|setup-desktop]] script.}}
== Installation ==
{{:Include:Setup-desktop}}

When gnome is chosen, the above script enables community repository and additionally installs [[D-Bus]], [[eudev]], [[PipeWire]] and {{Pkg|gdm}} as [[Display manager|display manager]] .

== Configuration ==

To manage network through GUI, configure [[NetworkManager]]. You may need to [[Install]] necessary subpackages like {{Pkg|networkmanager-wifi}}.

=== Software ===

GNOME [https://apps.gnome.org/Software/ Software] can be used as GUI front end for [[Alpine Package Keeper]] and [[Flatpak|Flatpak]].
* [[Install]] the packages {{pkg|gnome-software-plugin-apk}} and {{pkg|gnome-software-plugin-flatpak}}, if not already installed.
* Ensure that {{ic|apk-polkit-server}} service from {{pkg|apk-polkit-rs}} package is running:{{cmd|# rc-update add apk-polkit-server default && rc-service apk-polkit-server start}}

== Updating GNOME packages ==

Most GNOME apps and core systems follow a common versioning pattern, and have a similar release cadence. In order to reduce the workload on maintainers, the [https://gitlab.alpinelinux.org/pabloyoyoista/gnome-aports-utils gnome-aports-utils] project exists. It contains a series of scripts that can be used to detect changes on GNOME-related projects, and commit them. When doing major GNOME updates, and doing minor updates on many projects, these scripts can help warranty that no project is forgotten, and reduce the time needed to build and test the upgrades.

We recommend everybody to '''use and contribute''' to that repository instead of pushing updates for every GNOME component individually.

=== Major GNOME upgrade ===

About every half year, GNOME publishes a new major release. These are announced at: https://release.gnome.org/calendar/ (note the dates are the tarball-due-dates and not the actual release drop).

With this release the whole GNOME stack gets upgraded, this includes G-related libraries, the GNOME shell with mutter, [https://apps.gnome.org/ GNOME core apps] and other packages following the same schedule. The [https://matrix.to/#/%23release-team:gnome.org GNOME release engineering team] publishes dates for alpha, beta, release candidates and stable versions for every major version, most GNOME core packages follow their schedules, but not all of them. Announcements of the releng team are posted on the GNOME forum (https://discourse.gnome.org/tag/release-team) and Release Notes for each phase (with it's upgraded packages) are at: https://download.gnome.org/core/

Therefore we should also upgrade along the dependency tree (glib -> gtk4 -> mutter -> gnome-shell -> other apps). Most important libraries are glib, gtk4, libadwaita. These are mostly already released in the alpha-phase and don't contain many breaking changed. To upgrade other GNOME core package to the latest version in a major version, you can use [https://gitlab.alpinelinux.org/pabloyoyoista/gnome-aports-utils gnome-aports-utils] or also check [https://download.gnome.org/sources/?C=M&O=D https://download.gnome.org/sources (sorted by date)] (that is where all GNOME core maintainers upload their tarballs).

Also take a look at Gentoo's upgrading guide: https://wiki.gentoo.org/wiki/Project:GNOME/GNOME_Bumping_Guide

The GNOME Foundation coordinates the development and other aspects of the GNOME Project. According to GNOME upstream, GNOME 40 is written with the systemd init system in mind. Meaning openrc and other init systems need specific changes and might be behind the upstream source.

== Troubleshooting ==

If you are unable to log in, check {{Path|/var/log/gdm/greeter.log}}, there may be info there from X that indicates failed modules, etc.

If GNOME Terminal doesn't start, add the following to /etc/profile.d/locale.sh: <code>LANG=en_US.UTF-8</code> and reboot.

If the on-screen keyboard shows up in GDM after installing other UIs such as Phosh, you need to disable it by opening the Accessibility menu (top right) when you are in the GDM login screen. You can disable the on-screen keyboard there. Or set <code>org.gnome.desktop.a11y.applications screen-keyboard-enabled</code> to <code>false</code> for the <code>gdm</code> user with <code>dconf</code>

=== Slow applications or rendering issues ===

Please note that some applications, i.e. Gnome Web (Epiphany), may require the installation of libraries related to hardware acceleration to work correctly.

In quite some cases, this can be solved by installing <code>mesa-gles</code> (OpenGL ES). Check if you you have issues loading the shared library <code>libGLESv2.so.2</code>. If so, you can install it with:{{Cmd|# apk add mesa-gles}}

== See also ==

* [https://wiki.archlinux.org/title/GNOME GNOME - Archwiki]
* [https://wiki.gentoo.org/wiki/GNOME GNOME - Gentoo Wiki]
* [https://github.com/dantrell/gentoo-project-gnome-without-systemd Github - GNOME without systemd]
* [https://wiki.postmarketos.org/wiki/GNOME GNOME - PostmarketOS Wiki]
* [https://wiki.postmarketos.org/wiki/GNOME_apps Alpine linux packages available for Gnome]

[[Category:Desktop Environments]]

GNOME

2025-11-29T14:13:15Z

H8d13:

[https://www.gnome.org/ Gnome Desktop] aims to get things done with ease, comfort, and control.

== Prerequisites ==
{{:Include:Desktop prerequisites}}
{{Tip|Except for the first two [[#Prerequisites|Prerequisites]], all the others are automatically handled by [[#Installation|setup-desktop]] script.}}
== Installation ==
{{:Include:Setup-desktop}}

When gnome is chosen, the above script enables community repository and additionally installs [[D-Bus]], [[eudev]], [[PipeWire]] and {{Pkg|gdm}} as [[Display manager|display manager]] .

== Configuration ==

To manage network through GUI, configure [[NetworkManager]]. You may need to [[Install]] necessary subpackages like {{Pkg|networkmanager-wifi}}.

=== Software ===

GNOME [https://apps.gnome.org/Software/ Software] can be used as GUI front end for [[Alpine Package Keeper]] and [[Flatpak|Flatpak]].
* [[Install]] the packages {{pkg|gnome-software-plugin-apk}} and {{pkg|gnome-software-plugin-flatpak}}, if not already installed.
* Ensure that {{ic|apk-polkit-server}} service from {{pkg|apk-polkit-rs}} package is running:{{cmd|# rc-update add apk-polkit-server default && rc-service apk-polkit-server start}}

== Updating GNOME packages ==

Most GNOME apps and core systems follow a common versioning pattern, and have a similar release cadence. In order to reduce the workload on maintainers, the [https://gitlab.alpinelinux.org/pabloyoyoista/gnome-aports-utils gnome-aports-utils] project exists. It contains a series of scripts that can be used to detect changes on GNOME-related projects, and commit them. When doing major GNOME updates, and doing minor updates on many projects, these scripts can help warranty that no project is forgotten, and reduce the time needed to build and test the upgrades.

We recommend everybody to '''use and contribute''' to that repository instead of pushing updates for every GNOME component individually.

=== Major GNOME upgrade ===

About every half year, GNOME publishes a new major release. These are announced at: https://release.gnome.org/calendar/ (note the dates are the tarball-due-dates and not the actual release drop).

With this release the whole GNOME stack gets upgraded, this includes G-related libraries, the GNOME shell with mutter, [https://apps.gnome.org/ GNOME core apps] and other packages following the same schedule. The [https://matrix.to/#/%23release-team:gnome.org GNOME release engineering team] publishes dates for alpha, beta, release candidates and stable versions for every major version, most GNOME core packages follow their schedules, but not all of them. Announcements of the releng team are posted on the GNOME forum (https://discourse.gnome.org/tag/release-team) and Release Notes for each phase (with it's upgraded packages) are at: https://download.gnome.org/core/

Therefore we should also upgrade along the dependency tree (glib -> gtk4 -> mutter -> gnome-shell -> other apps). Most important libraries are glib, gtk4, libadwaita. These are mostly already released in the alpha-phase and don't contain many breaking changed. To upgrade other GNOME core package to the latest version in a major version, you can use [https://gitlab.alpinelinux.org/pabloyoyoista/gnome-aports-utils gnome-aports-utils] or also check [https://download.gnome.org/sources/?C=M&O=D https://download.gnome.org/sources (sorted by date)] (that is where all GNOME core maintainers upload their tarballs).

Also take a look at Gentoo's upgrading guide: https://wiki.gentoo.org/wiki/Project:GNOME/GNOME_Bumping_Guide

The GNOME Foundation coordinates the development and other aspects of the GNOME Project. According to GNOME upstream, GNOME 40 is written with the systemd init system in mind. Meaning openrc and other init systems need specific changes and might be behind the upstream source.

== Troubleshooting ==

If you are unable to log in, check {{Path|/var/log/gdm/greeter.log}}, there may be info there from X that indicates failed modules, etc.

If GNOME Terminal doesn't start, add the following to /etc/profile.d/locale.sh: <code>LANG=en_US.UTF-8</code> and reboot.

If the on-screen keyboard shows up in GDM after installing other UIs such as Phosh, you need to disable it by opening the Accessibility menu (top right) when you are in the GDM login screen. You can disable the on-screen keyboard there. Or set <code>org.gnome.desktop.a11y.applications screen-keyboard-enabled</code> to <code>false</code> for the <code>gdm</code> user with <code>dconf</code>

=== Slow applications or rendering issues ===

Please note that some applications, i.e. Gnome Web (Epiphany), may require the installation of libraries related to hardware acceleration to work correctly.

In quite some cases, this can be solved by installing <code>mesa-gles</code> (OpenGL ES). Check if you you have issues loading the shared library <code>libGLESv2.so.2</code>. If so, you can install it with:{{Cmd|# apk add mesa-gles}}

== See also ==

* [https://wiki.archlinux.org/title/GNOME GNOME - Archwiki]
* [https://wiki.gentoo.org/wiki/GNOME GNOME - Gentoo Wiki]
* [https://github.com/dantrell/gentoo-project-gnome-without-systemd - Github GNOME without systemd]
* [https://wiki.postmarketos.org/wiki/GNOME GNOME - PostmarketOS Wiki]
* [https://wiki.postmarketos.org/wiki/GNOME_apps Alpine linux packages available for Gnome]

[[Category:Desktop Environments]]

GNOME

2025-11-29T14:08:23Z

H8d13: Full disclosure about GNOME and stolen from gentoo docs.

[https://www.gnome.org/ Gnome Desktop] aims to get things done with ease, comfort, and control.

== Prerequisites ==
{{:Include:Desktop prerequisites}}
{{Tip|Except for the first two [[#Prerequisites|Prerequisites]], all the others are automatically handled by [[#Installation|setup-desktop]] script.}}
== Installation ==
{{:Include:Setup-desktop}}

When gnome is chosen, the above script enables community repository and additionally installs [[D-Bus]], [[eudev]], [[PipeWire]] and {{Pkg|gdm}} as [[Display manager|display manager]] .

== Configuration ==

To manage network through GUI, configure [[NetworkManager]]. You may need to [[Install]] necessary subpackages like {{Pkg|networkmanager-wifi}}.

=== Software ===

GNOME [https://apps.gnome.org/Software/ Software] can be used as GUI front end for [[Alpine Package Keeper]] and [[Flatpak|Flatpak]].
* [[Install]] the packages {{pkg|gnome-software-plugin-apk}} and {{pkg|gnome-software-plugin-flatpak}}, if not already installed.
* Ensure that {{ic|apk-polkit-server}} service from {{pkg|apk-polkit-rs}} package is running:{{cmd|# rc-update add apk-polkit-server default && rc-service apk-polkit-server start}}

== Updating GNOME packages ==

Most GNOME apps and core systems follow a common versioning pattern, and have a similar release cadence. In order to reduce the workload on maintainers, the [https://gitlab.alpinelinux.org/pabloyoyoista/gnome-aports-utils gnome-aports-utils] project exists. It contains a series of scripts that can be used to detect changes on GNOME-related projects, and commit them. When doing major GNOME updates, and doing minor updates on many projects, these scripts can help warranty that no project is forgotten, and reduce the time needed to build and test the upgrades.

We recommend everybody to '''use and contribute''' to that repository instead of pushing updates for every GNOME component individually.

=== Major GNOME upgrade ===

About every half year, GNOME publishes a new major release. These are announced at: https://release.gnome.org/calendar/ (note the dates are the tarball-due-dates and not the actual release drop).

With this release the whole GNOME stack gets upgraded, this includes G-related libraries, the GNOME shell with mutter, [https://apps.gnome.org/ GNOME core apps] and other packages following the same schedule. The [https://matrix.to/#/%23release-team:gnome.org GNOME release engineering team] publishes dates for alpha, beta, release candidates and stable versions for every major version, most GNOME core packages follow their schedules, but not all of them. Announcements of the releng team are posted on the GNOME forum (https://discourse.gnome.org/tag/release-team) and Release Notes for each phase (with it's upgraded packages) are at: https://download.gnome.org/core/

Therefore we should also upgrade along the dependency tree (glib -> gtk4 -> mutter -> gnome-shell -> other apps). Most important libraries are glib, gtk4, libadwaita. These are mostly already released in the alpha-phase and don't contain many breaking changed. To upgrade other GNOME core package to the latest version in a major version, you can use [https://gitlab.alpinelinux.org/pabloyoyoista/gnome-aports-utils gnome-aports-utils] or also check [https://download.gnome.org/sources/?C=M&O=D https://download.gnome.org/sources (sorted by date)] (thats where all GNOME core maintainers upload their tarballs).

Also take a look at Gentoo's upgrading guide: https://wiki.gentoo.org/wiki/Project:GNOME/GNOME_Bumping_Guide

The GNOME Foundation coordinates the development and other aspects of the GNOME Project. According to GNOME upstream, GNOME 40 is written with the systemd init system in mind. Meaning openrc and other init systems need specific changes and might be behind the upstream source.

== Troubleshooting ==

If you are unable to log in, check {{Path|/var/log/gdm/greeter.log}}, there may be info there from X that indicates failed modules, etc.

If GNOME Terminal doesn't start, add the following to /etc/profile.d/locale.sh: <code>LANG=en_US.UTF-8</code> and reboot.

If the on-screen keyboard shows up in GDM after installing other UIs such as Phosh, you need to disable it by opening the Accessibility menu (top right) when you are in the GDM login screen. You can disable the on-screen keyboard there. Or set <code>org.gnome.desktop.a11y.applications screen-keyboard-enabled</code> to <code>false</code> for the <code>gdm</code> user with <code>dconf</code>

=== Slow applications or rendering issues ===

Please note that some applications, i.e. Gnome Web (Epiphany), may require the installation of libraries related to hardware acceleration to work correctly.

In quite some cases, this can be solved by installing <code>mesa-gles</code> (OpenGL ES). Check if you you have issues loading the shared library <code>libGLESv2.so.2</code>. If so, you can install it with:{{Cmd|# apk add mesa-gles}}

== See also ==

* [https://wiki.archlinux.org/title/GNOME GNOME - Archwiki]
* [https://wiki.gentoo.org/wiki/GNOME GNOME - Gentoo Wiki]
* [https://github.com/dantrell/gentoo-project-gnome-without-systemd]
* [https://wiki.postmarketos.org/wiki/GNOME GNOME - PostmarketOS Wiki]
* [https://wiki.postmarketos.org/wiki/GNOME_apps Alpine linux packages available for Gnome]

[[Category:Desktop Environments]]