sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-08-24 16:51:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

Correct Linux desktop app requirements and drop libappindicator (#888)

Browse Source 
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.
This commit is contained in:
Maycon Santos
2026-07-28 18:34:37 +09:00
committed by GitHub
parent 302f76bd41
commit c53c0831a5
1 changed files with 48 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
src/pages/get-started/install/linux.mdx
View File

@@ -6,25 +6,41 @@ 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+**
<Warning>
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.
</Warning>
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
```
<Note>
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.
</Note>
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.
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.
<Note>
Linux `netbird-ui` packages are built for **x86_64** only. On arm64 and other architectures, use the `netbird` CLI.
</Note>
## Linux Install Script
@@ -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)
<Note>
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.
</Note>
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 some recent releases, the default behaviour for `libappindicator` was changed, so we need to install `gnome-shell-extension-appindicator` and enable it:
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
```
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
```
<Note>
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`.
</Note>
### NixOS 22.11+/unstable
1. Edit your [`configuration.nix`](https://nixos.org/manual/nixos/stable/index.html#sec-changing-config)