From f876c38505829d397bf7daf3509e4ff0cf063919 Mon Sep 17 00:00:00 2001
From: rnhmjoj <rnhmjoj@inventati.org>
Date: Mon, 10 Mar 2025 16:58:07 +0100
Subject: [PATCH] nixos/doc: document how to use startx

---
 .../manual/configuration/x-windows.chapter.md | 48 +++++++++++++++++++
 nixos/doc/manual/redirects.json               |  3 ++
 2 files changed, 51 insertions(+)

diff --git a/nixos/doc/manual/configuration/x-windows.chapter.md b/nixos/doc/manual/configuration/x-windows.chapter.md
index 2c77c638ca2d..7adf321f2b06 100644
--- a/nixos/doc/manual/configuration/x-windows.chapter.md
+++ b/nixos/doc/manual/configuration/x-windows.chapter.md
@@ -114,6 +114,54 @@ using lightdm for a user `alice`:
 }
 ```
 
+## Running X without a display manager  {#sec-x11-startx}
+
+It is possible to avoid a display manager entirely and starting the X server
+manually from a virtual terminal. Add to your configuration
+```nix
+{
+  services.xserver.displayManager.startx = {
+    enable = true;
+    generateScript = true;
+  };
+}
+```
+then you can start the X server with the `startx` command.
+
+The second option will generate a base `xinitrc` script that will run your
+window manager and set up the systemd user session.
+You can extend the script using the [extraCommands](#opt-services.xserver.displayManager.startx.extraCommands) for example:
+```nix
+{
+  services.xserver.displayManager.startx = {
+    generateScript = true;
+    extraCommands = ''
+      xrdb -load .Xresources
+      xsetroot -solid '#666661'
+      xsetroot -cursor_name left_ptr
+    '';
+  };
+}
+```
+or, alternatively, you can write your own from scratch in `~/.xinitrc`.
+
+In this case, remember you're responsible for starting the window manager, for
+example
+```shell
+sxhkd &
+bspwm &
+```
+and if you have enabled some systemd user service, you will probably want to
+also add these lines too:
+```shell
+# import required env variables from the current shell
+systemctl --user import-environment DISPLAY XDG_SESSION_ID
+# start all graphical user services
+systemctl --user start nixos-fake-graphical-session.target
+# start the user dbus daemon
+dbus-daemon --session --address="unix:path=/run/user/$(id -u)/bus" &
+```
+
 ## Intel Graphics drivers {#sec-x11--graphics-cards-intel}
 
 The default and recommended driver for Intel Graphics in X.org is `modesetting`
diff --git a/nixos/doc/manual/redirects.json b/nixos/doc/manual/redirects.json
index 1acabd14592f..950266de4e35 100644
--- a/nixos/doc/manual/redirects.json
+++ b/nixos/doc/manual/redirects.json
@@ -272,6 +272,9 @@
   "sec-x11-auto-login": [
     "index.html#sec-x11-auto-login"
   ],
+  "sec-x11-startx": [
+    "index.html#sec-x11-startx"
+  ],
   "sec-x11--graphics-cards-intel": [
     "index.html#sec-x11--graphics-cards-intel"
   ],