Add uwsm instructions

pages/Configuring/Dispatchers.md

@@ -85,6 +85,14 @@ layout pages (See the sidebar).
 
 {{< callout type=warning >}}
 
+[uwsm](../../Systemd-start) users should avoid using `exit` dispatcher, as exiting Hyprland this way causes various systemd-related problems after restarting the compositor, such xdg-desktop-portal-hyprland and other services do not restart. Use `loginctl terminate-user ""` instead.
+
+It's also strongly advised to replace the `exit` dispatcher with `loginctl terminate-user ""` inside `hyprland.conf` keybinds section.
+
+{{< /callout >}}
+
+{{< callout type=warning >}}
+
 It is NOT recommended to set DPMS with a keybind directly, as it might cause
 undefined behavior. Instead, consider something like
 

pages/Configuring/Environment-variables.md

@@ -72,6 +72,12 @@ them explicitly.
 If your [desktop portal](https://wiki.archlinux.org/title/XDG_Desktop_Portal) is malfunctioning for seemingly
 no reason (no errors), it's likely your XDG env isn't set correctly.
 
+ {{< callout type=info >}}
+
+ [uwsm](../../Systemd-start) users don't need to explicitly set XDG environment variables, as uwsm sets them, automatically.
+
+ {{< /callout >}}
+
 ## Qt Variables
 
 - `env = QT_AUTO_SCREEN_SCALE_FACTOR,1` -

pages/Getting Started/Master-Tutorial.md

@@ -47,7 +47,8 @@ Please bear in mind 3D acceleration in VMs may be pretty slow.
 
 Hyprland can be executed by typing `Hyprland` in your tty.
 
-Systemd users can also start Hyprland, by typing `systemctl --user start hyprland-session.service` in tty. This method provides additional features, such as [xdg-autostart](https://www.freedesktop.org/software/systemd/man/latest/systemd-xdg-autostart-generator.html) support and ability to enable services for programs that rely on a graphical session and provide such services (e.g waybar).
+Systemd users can also start Hyprland, using [uwsm](https://github.com/Vladimir-csp/uwsm). This is the recommended method of launching Hyprland on systemd-based distros, as it provides additional features such as [xdg-autostart](https://www.freedesktop.org/software/systemd/man/latest/systemd-xdg-autostart-generator.html) support, launching any application as a systemd-unit with `uwsm app` helper, and the ability to enable services for programs that rely on a graphical session and provide such services (e.g waybar). See [uwsm](../../Systemd-start) page for further instructions.
+
 
 {{< callout type=warning >}}
 

pages/Hypr Ecosystem/hypridle.md

@@ -9,7 +9,7 @@ hypridle is Hyprland's idle management daemon.
 
 Configuration is done via the config file at `~/.config/hypr/hypridle.conf`. A
 config file is required; hypridle won't run without one. To run hypridle at
-startup, edit `hyprland.conf` and add: `exec-once = hypridle`. If Hyprland is started as a systemd service, you can use `systemctl --user enable --now hypridle.service`.
+startup, edit `hyprland.conf` and add: `exec-once = hypridle`. If Hyprland is started with [uwsm](../../Systemd-start), you can use `systemctl --user enable --now hypridle.service`.
 
 ### General
 

pages/Hypr Ecosystem/hyprpaper.md

@@ -124,7 +124,7 @@ preload another and set it to your monitor(s). It has the same syntax as
 ### Run at startup
 
 To run hyprpaper at startup edit `hyprland.conf` and add: `exec-once =
-hyprpaper`. If you start Hyprland as a systemd service, you can also use `systemctl --user enable --now hyprpaper.service` command.
+hyprpaper`. If you start Hyprland with [uwsm](../../Systemd-start), you can also use `systemctl --user enable --now hyprpaper.service` command.
 
 ### Misc options
 

pages/Hypr Ecosystem/hyprpolkitagent.md

@@ -14,7 +14,7 @@ or use a different agent, e.g. [KDE's one](https://github.com/KDE/polkit-kde-age
 Add `exec-once = systemctl --user start hyprpolkitagent` to your Hyprland config and restart hyprland.
 (obviously change that to whatever you are using if you are not using the hypr one)
 
-If Hyprland is started as a systemd service, you can autostart for polkit with the command `systemctl --user enable --now hyprpolkitagent.service`.
+If Hyprland is started with [uwsm](../../Systemd-start), you can autostart for polkit with the command `systemctl --user enable --now hyprpolkitagent.service`.
 
 On distributions that use a different init system, such as Gentoo, it may be
 necessary to use

pages/Useful Utilities/Other.md

@@ -65,10 +65,6 @@ exec-once = udiskie
 
 [See more uses here](https://github.com/coldfix/udiskie/wiki/Usage).
 
-### Advanced Systemd Session Management
-
-[UWSM](https://github.com/Vladimir-csp/uwsm) by _Vladimir-csp_: Wraps standalone Wayland compositors into a set of Systemd units on the fly. Provides robust session management including environment, XDG autostart support, bi-directional binding with login session, login shell integration, and clean shutdown. Optional user unit control utility via dmenu-like menu, failed unit monitor.
-
 ### Other useful utilities
 
 The website [We Are Wayland Now](https://wearewaylandnow.com/) details some other useful utilities and applications for Wayland like docks, email clients, and so on, along with some other useful information about compatibility on Wayland.

pages/Useful Utilities/Status-Bars.md

@@ -27,6 +27,12 @@ Hyprland, add this line to your Hyprland configuration:
 exec-once = waybar
 ```
 
+Waybar also provides a systemd service. If you use Hyprland with [uwsm](../../Systemd-start), you can enable it, using the following command.
+
+```ini
+systemctl --user enable --now waybar.service
+```
+
 ### Waybar FAQ
 
 #### Waybar popups render behind the windows

pages/Useful Utilities/Systemd-start.md

@@ -0,0 +1,102 @@
+---
+weight: 12
+title: Systemd startup
+---
+
+## UWSM
+
+- [Universal Wayland Session Manager](https://github.com/Vladimir-csp/uwsm) is a recommended way to start Hyprland session on systemd distros. uwsm wraps standalone Wayland compositors into a set of Systemd units and provides robust session management including environment, XDG autostart support, bi-directional binding with login session, and clean shutdown.
+
+## Installation
+
+{{% details title="Arch" closed="true" %}}
+
+uwsm is available in AUR. You can install it either with an AUR helper, or build PKGBUILD manually. Here's an example for yay.
+
+```sh
+yay -S uwsm
+```
+
+{{% /details %}}
+
+{{% details title="Nix/NixOS" closed="true" %}}
+
+```nix
+programs.uwsm = {
+  enable = true;
+  waylandCompositors.hyprland = {
+    binPath = "/run/current-system/sw/bin/Hyprland";
+    comment = "Hyprland session managed by uwsm";
+    prettyName = "Hyprland";
+  };
+};
+```
+
+The above option generates a new desktop entry, `hyprland-uwsm.desktop`, which will be available in display managers.
+
+For more info, read the [option](https://search.nixos.org/options?channel=unstable&show=programs.uwsm.enable&from=0&size=50&sort=relevance&type=packages&query=uwsm).
+
+{{< callout >}}
+
+If you use the [Home Manager module](../../Nix/Hyprland-on-Home-Manager), make sure to disable the systemd integration, as it conflicts with uwsm.
+
+```nix
+wayland.windowManager.hyprland.systemd.enable = false;
+```
+
+{{< /callout >}}
+
+{{% /details %}}
+
+{{< callout type=info >}}
+
+For instructions for other distros and manual building, see [building and installing](https://github.com/Vladimir-csp/uwsm?tab=readme-ov-file#installation) section on the project's page.
+
+{{< /callout >}}
+
+## Launching Hyprland with uwsm
+
+{{< callout type=info >}}
+
+Pay attention to the warnings in [Environment variables](../../Environment-variables#xdg-specifications) and [Dispatchers](../../Dispatchers) sections.
+
+{{< /callout >}}
+
+### In tty
+
+To launch Hyprland with uwsm, add this code in your shell profile.
+
+```
+if uwsm check may-start && uwsm select; then
+	exec systemd-cat -t uwsm_start uwsm start default
+fi
+```
+
+This will bring uwsm compositor selection menu after you log in tty1. Choose Hyprland entry and you're good to go.
+
+If you want to bypass compositor selection menu and launch Hyprland directly, use this code in your shell profile, instead.
+
+```
+if uwsm check may-start; then
+    exec uwsm start hyprland.desktop
+fi
+```
+
+### Using a display manager
+
+If you use a display manager, choose `hyprland (uwsm-managed)` entry in a display manager selection menu.
+
+## Launching applications inside session
+
+The concept of a session managed by Systemd implies also running applications as units. Uwsm [provides](https://github.com/Vladimir-csp/uwsm#3-applications-and-slices) a helper to do it.
+
+Prefix application startup commands with `uwsm app --`. It also supports launching Desktop Entries by IDs or paths. See `man uwsm` or `uwsm app --help`.
+
+Examples for autostart and bind entries:
+
+```
+exec-once = uwsm app -- mycommand --arg1 --arg2
+bind = SUPER, E, exec, uwsm app -- pcmanfm-qt.desktop
+```
+
+Running applications as child processes inside compositor's unit is discouraged.