From f156e9e951e2fb6e4d6ca87d16b298eb82f99f4b Mon Sep 17 00:00:00 2001 From: mlsmaycon Date: Mon, 27 Jul 2026 12:47:59 +0200 Subject: [PATCH] Correct Linux desktop app requirements and drop libappindicator The Wails 3 desktop app links GTK 4.10+ (GtkFileDialog) and WebKitGTK 6.0, verified against the shipped v0.75.0 netbird-ui binary. The previously documented floor of Debian 12 / Ubuntu 22.04 is below that: both ship WebKitGTK 6.0 but only GTK 4.8 and 4.6, where the app starts and then crashes on the first file dialog. - Document the real floor per distribution and mark RHEL 9, Amazon Linux 2 and Amazon Linux 2023 as CLI only. - Name the GTK 4 and WebKitGTK 6.0 packages in the install commands, since netbird-ui does not declare them as dependencies. - Note that EPEL provides webkitgtk6.0 on RHEL/AlmaLinux/Rocky 10. - Remove libappindicator from the RPM install lines. The tray is a D-Bus StatusNotifierItem and does not link libappindicator; keep the GNOME extension step, which is still required for the tray to appear. - Note that Linux netbird-ui packages are x86_64 only. --- src/pages/get-started/install/linux.mdx | 65 ++++++++++++++++++------- 1 file changed, 47 insertions(+), 18 deletions(-) diff --git a/src/pages/get-started/install/linux.mdx b/src/pages/get-started/install/linux.mdx index 0f023ea0d..9b7e8b613 100644 --- a/src/pages/get-started/install/linux.mdx +++ b/src/pages/get-started/install/linux.mdx @@ -6,26 +6,42 @@ The NetBird client (agent) allows a peer to join a pre-existing NetBird deployme ## Desktop App Dependencies -The desktop app introduced in NetBird v0.75.0 renders its interface in a GTK 4 WebKit webview. Supported packages normally install these dependencies automatically. For manual or unsupported deployments, install the corresponding packages before launching the GUI. +The desktop app introduced in NetBird v0.75.0 renders its interface in a GTK 4 WebKit webview. The `netbird-ui` package does not declare these libraries as dependencies, so install them alongside it. -**Debian 12+ / Ubuntu 22.04+** + +The desktop app requires **GTK 4.10 or newer** and **WebKitGTK 6.0**. On older GTK 4 releases the app starts but crashes as soon as it opens a file dialog, so install the `netbird` CLI only on those systems. + + +Minimum releases that satisfy both requirements: + +| Distribution | Desktop app | CLI | +| --- | --- | --- | +| Ubuntu | 24.04 LTS and newer | any supported release | +| Debian | 13 (trixie) and newer | any supported release | +| Fedora | 43 and newer | any supported release | +| RHEL / AlmaLinux / Rocky | 10 and newer, with [EPEL](https://docs.fedoraproject.org/en-US/epel/getting-started/) | any supported release | +| Amazon Linux | not available | 2 and 2023 | + +Ubuntu 22.04 (GTK 4.6) and Debian 12 (GTK 4.8) ship WebKitGTK 6.0 but their GTK 4 is below 4.10, so the desktop app is not supported there. RHEL 9 provides neither GTK 4.10 nor WebKitGTK 6.0. + +**Debian 13+ / Ubuntu 24.04+** ```bash sudo apt-get install libgtk-4-1 libwebkitgtk-6.0-4 xdg-utils ``` -**Fedora / RHEL 10+** +**Fedora 43+ / RHEL 10+** ```bash sudo dnf install gtk4 webkitgtk6.0 xdg-utils ``` +On other distributions, install the equivalent **GTK 4** (4.10+), **WebKitGTK 6.0**, and **xdg-utils** packages from your package manager. Many desktop systems already include some or all of them. + -RHEL 9 includes GTK 4 but does not provide WebKitGTK 6.0, which the desktop app requires. RHEL 10 is supported after enabling [EPEL](https://docs.fedoraproject.org/en-US/epel/getting-started/), which provides the `webkitgtk6.0` package. +Linux `netbird-ui` packages are built for **x86_64** only. On arm64 and other architectures, use the `netbird` CLI. -On other distributions, install the equivalent **GTK 4**, **WebKitGTK 6.0**, and **xdg-utils** packages from your package manager, many systems may already include some of all of these packages. - ## Linux Install Script ```bash @@ -51,11 +67,15 @@ curl -fsSL https://pkgs.netbird.io/install.sh | sh ```bash # for CLI only sudo apt-get install netbird - # for GUI package - sudo apt-get install netbird-ui + # for the desktop app (Ubuntu 24.04+ / Debian 13+) + sudo apt-get install netbird-ui libgtk-4-1 libwebkitgtk-6.0-4 xdg-utils ``` -### RHEL/Amazon Linux 2 (RPM) +### RHEL 9 / Amazon Linux 2 (YUM) + + +These releases do not provide GTK 4.10 or WebKitGTK 6.0, so the desktop app is not available. Install the CLI and manage NetBird with `netbird` commands. + 1. Add the repository: ```bash @@ -71,13 +91,10 @@ EOF ``` 2. Install the package ```bash - # for CLI only sudo yum install netbird - # for GUI package - sudo yum install libappindicator-gtk3 libappindicator netbird-ui ``` -### Fedora/Amazon Linux 2023 (DNF) +### Fedora / RHEL 10+ / Amazon Linux 2023 (DNF) 1. Create the repository file: ```bash @@ -102,10 +119,18 @@ EOF ```bash # for CLI only sudo dnf install netbird - # for GUI package - sudo dnf install libappindicator-gtk3 libappindicator netbird-ui + # for the desktop app (Fedora 43+ / RHEL 10+) + sudo dnf install netbird-ui gtk4 webkitgtk6.0 xdg-utils +``` + +On RHEL, AlmaLinux and Rocky Linux 10, `webkitgtk6.0` comes from EPEL, so enable it before installing the desktop app: +```bash + sudo dnf install epel-release -y ``` -On some recent releases, the default behaviour for `libappindicator` was changed, so we need to install `gnome-shell-extension-appindicator` and enable it: + +Amazon Linux 2023 does not provide GTK 4 or WebKitGTK 6.0, so install the CLI only there. + +The tray icon uses the D-Bus StatusNotifierItem protocol. GNOME does not support it natively, so on GNOME desktops install `gnome-shell-extension-appindicator` and enable it: ``` sudo dnf install gnome-shell-extension-appindicator sudo gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com @@ -132,8 +157,8 @@ EOF ```bash # for CLI only rpm-ostree install netbird - # for GUI package - rpm-ostree install netbird-ui + # for the desktop app + rpm-ostree install netbird-ui gtk4 webkitgtk6.0 xdg-utils # Don't forget to reboot to apply ``` 4. Start the service @@ -239,6 +264,10 @@ reboot zypper in netbird ``` + +These commands install the CLI. To use the desktop app, install `netbird-ui` together with your distribution's GTK 4.10+ and WebKitGTK 6.0 packages; openSUSE names them differently from Debian and Fedora, so check with `zypper search webkitgtk`. + + ### NixOS 22.11+/unstable 1. Edit your [`configuration.nix`](https://nixos.org/manual/nixos/stable/index.html#sec-changing-config)