nix-config/docs/uwsm-migration-summary.md

UWSM Migration Complete ✅

Summary

The Niri desktop environment has been fully migrated to UWSM (Universal Wayland Session Manager) for comprehensive systemd-based session management.

What Changed

1. Session Launch (Host-Level)

Before:

• Manual desktop entry files in /etc/wayland-sessions/
• Manual UWSM package installation

After:

programs.uwsm = {
  enable = true;
  waylandCompositors.niri = {
    prettyName = "Niri";
    comment = "Niri scrollable-tiling Wayland compositor managed by UWSM";
    binPath = "/run/current-system/sw/bin/niri-session";
  };
};

2. Startup Applications (Home-Manager)

Before: Using programs.niri.settings.spawn-at-startup

After: Using systemd.user.services with proper targets

Service	Type	Purpose
nm-applet	simple	Network manager tray icon
zenbook-autostart	oneshot	Initial display setup
zenbook-delayed-setup	oneshot	Secondary setup after delay
zenbook-inotify-monitor	simple	DRM status change monitor
zenbook-udev-monitor	simple	udev event monitor

All services:

• PartOf = ["graphical-session.target"] - proper lifecycle
• After = ["graphical-session.target"] - correct ordering
• WantedBy = ["graphical-session.target"] - auto-start
• Restart policies for resilience

3. Application Launches (Keybinds)

Before: Direct binary execution

programs.niri.settings.binds."Mod+Return".action.spawn = ["${pkgs.fuzzel}/bin/fuzzel"];

After: UWSM app wrapper

programs.niri.settings.binds."Mod+Return".action.spawn = ["uwsm" "app" "--" "${pkgs.fuzzel}/bin/fuzzel"];

All keybinds now use uwsm app --:

• Mod+Return → fuzzel launcher
• Mod+L → swaylock
• Mod+Z → zenbook-set-displays

4. Fuzzel Launcher Configuration

Fuzzel now has launch-prefix configured:

settings.main.launch-prefix = "uwsm app -- ";

This means apps launched from fuzzel are automatically placed in the correct systemd slice.

Benefits Achieved

1. ✅ Environment Variable Inheritance

   • Login shell → PAM → systemd → compositor → applications
   • All environment properly propagated

2. ✅ Systemd Integration

   • All services bound to graphical-session.target
   • Proper dependency ordering and lifecycle management

3. ✅ Application Slicing

   • Apps launched via uwsm app -- go into app-graphical.slice
   • Better resource management and isolation

4. ✅ Clean Shutdown

   • Proper cleanup when session ends
   • Services stopped in correct order

5. ✅ Resilience

   • Services auto-restart on failure
   • Configurable restart policies

6. ✅ Standards Compliance

   • Follows systemd graphical session standards
   • Compatible with XDG autostart (if needed)

How to Use

From Display Manager

Select "Niri" from your display manager (GDM, SDDM, etc.)

The session is now automatically launched via UWSM with full session management.

From TTY

# Launch via UWSM
uwsm start niri

Verify UWSM is Active

# Check UWSM status
uwsm status

# List UWSM-managed units
systemctl --user list-units 'wayland-*'

# Check graphical session services
systemctl --user list-units --type=service | grep graphical

Monitoring

# Check specific service
systemctl --user status nm-applet

# View logs
journalctl --user -u zenbook-inotify-monitor -f

# List all services in graphical session
systemctl --user list-dependencies graphical-session.target

Files Modified

File	Changes
hosts/common/optional/niri.nix	Added programs.uwsm module
home/.../niri/waybar.nix	nm-applet → systemd service
home/.../niri/zenbook-screen.nix	All tools → systemd services, keybind uses uwsm app
home/.../niri/fuzzel.nix	Keybind + launch-prefix use uwsm app
home/.../niri/swaylock.nix	Keybind uses uwsm app
docs/uwsm-niri-integration.md	Updated documentation

Testing

After rebuilding:

1. Log out and select "Niri" from display manager

2. Log in and verify all components work:

   • Waybar appears with tray icons
   • nm-applet icon visible in tray
   • Mod+Return opens fuzzel
   • Mod+L locks screen
   • Zenbook displays configured correctly

3. Check systemd services:

   systemctl --user status nm-applet waybar zenbook-autostart
   

4. Launch an app from fuzzel and verify it's in the right slice:

   systemctl --user list-units --type=service | grep app-
   

Documentation

See docs/uwsm-niri-integration.md for:

• Detailed UWSM concepts
• Troubleshooting guide
• Advanced configuration options
• Environment variable management

References

• UWSM GitHub
• NixOS UWSM Module
• UWSM Documentation