add: Managing Kanshi with Systemd User Service This guide explains how to configure kanshi

-- manus-ai generated guide for kanshi systemd
2026-05-18 03:03:12 +00:00
parent ba6723b749
commit 85818487e9
1 changed files with 86 additions and 0 deletions
@@ -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)