diff --git a/guides/manus-ai/managing-kanshi-with-systemd-user-service b/guides/manus-ai/managing-kanshi-with-systemd-user-service new file mode 100644 index 0000000..364e13c --- /dev/null +++ b/guides/manus-ai/managing-kanshi-with-systemd-user-service @@ -0,0 +1,86 @@ +# Managing Kanshi with Systemd User Service + +This guide explains how to configure `kanshi` as a `systemd` user service, ensuring it starts automatically with your `niri` Wayland session and runs reliably in the background. Using a `systemd` user service is generally preferred over simply running `kanshi &` in a startup script, as it provides better process management, logging, and automatic restarts if `kanshi` crashes. + +## Prerequisites + +* **Kanshi Installed**: Ensure `kanshi` is installed on your system. If not, install it using your distribution's package manager (e.g., `sudo apt install kanshi` for Debian/Ubuntu, `sudo pacman -S kanshi` for Arch Linux). +* **Kanshi Configuration**: You should have your `kanshi` configuration file set up at `~/.config/kanshi/config` as provided in the previous interaction. +* **Systemd User Session**: Your `niri` session should be managed by `systemd` user services. This is typically the default for modern Linux distributions. + +## Step 1: Create the Systemd User Service File + +Create a new file named `kanshi.service` in your `~/.config/systemd/user/` directory. If the `user` directory doesn't exist, create it first: + +```bash +mkdir -p ~/.config/systemd/user/ +``` + +Then, place the following content into `~/.config/systemd/user/kanshi.service`: + +```ini +[Unit] +Description=Dynamic output configuration for Wayland compositors +Documentation=man:kanshi(1) +PartOf=graphical-session.target + +[Service] +Type=simple +ExecStart=/usr/bin/kanshi +Restart=always + +[Install] +WantedBy=graphical-session.target +``` + +### Explanation of the Service File + +* **`[Unit]` Section**: + * `Description`: A human-readable description of the service. + * `Documentation`: Points to the `kanshi` man page for further information. + * `PartOf=graphical-session.target`: This directive ensures that `kanshi` is considered part of your graphical session. If your graphical session stops, `kanshi` will also stop. For `niri`, `graphical-session.target` is a suitable target to bind to, as `niri` is a Wayland compositor that typically runs within a graphical session [1]. + +* **`[Service]` Section**: + * `Type=simple`: Indicates that the `ExecStart` command is the main process of the service. + * `ExecStart=/usr/bin/kanshi`: Specifies the command to execute when the service starts. This should be the full path to your `kanshi` executable. + * `Restart=always`: Configures `systemd` to automatically restart `kanshi` if it crashes or exits unexpectedly. + +* **`[Install]` Section**: + * `WantedBy=graphical-session.target`: This makes `kanshi.service` a dependency of `graphical-session.target`. When you enable the service, a symlink will be created, ensuring `kanshi` starts when your graphical session starts. + +## Step 2: Reload Systemd Daemon + +After creating or modifying a `systemd` unit file, you need to tell `systemd` to reload its configuration: + +```bash +systemctl --user daemon-reload +``` + +## Step 3: Enable and Start the Kanshi Service + +Now, enable the `kanshi` service so it starts automatically on login, and then start it immediately: + +```bash +systemctl --user enable --now kanshi.service +``` + +* `enable`: Creates the necessary symlinks for the service to start on boot. +* `--now`: Starts the service immediately after enabling it. + +## Step 4: Verify Service Status + +To check if `kanshi` is running correctly as a `systemd` user service, you can check its status: + +```bash +systemctl --user status kanshi.service +``` + +You should see output indicating that the service is `active (running)`. + +## Important Considerations for Niri + +For `kanshi` (and other Wayland-related services) to function correctly as `systemd` user services, your `niri` session needs to correctly set up the Wayland environment variables (`WAYLAND_DISPLAY`, `XDG_RUNTIME_DIR`). Most display managers (like GDM, SDDM, LightDM) and `niri` session scripts handle this automatically. If you encounter issues, ensure these variables are correctly exported in your `niri` startup process. + +## References + +[1] kanshi - ArchWiki. (n.d.). Retrieved from [https://wiki.archlinux.org/title/Kanshi](https://wiki.archlinux.org/title/Kanshi)