nixos/paperless: move paperless-manage to proper systemPackage (#367496)

nixos/doc/manual/release-notes/rl-2505.section.md

@@ -223,6 +223,9 @@
 - The `services.locate` module does no longer support findutil's `locate` due to its inferior performance compared to `mlocate` and `plocate`. The new default is `plocate`.
   As the `service.locate.localuser` option only applied when using findutil's `locate`, it has also been removed.
 
+- `services.paperless` now installs `paperless-manage` as a normal system package instead of creating a symlink in `/var/lib/paperless`.
+  `paperless-manage` now also changes to the appropriate user when being executed.
+
 - `kmonad` is now hardened by default using common `systemd` settings.
   If KMonad is used to execute shell commands, hardening may make some of them fail.  In that case, you can disable hardening using {option}`services.kmonad.keyboards.<name>.enableHardening` option.
 

nixos/modules/services/misc/paperless.nix

@@ -32,11 +32,22 @@ let
     else toString s
   ) cfg.settings);
 
-  manage = pkgs.writeShellScript "manage" ''
+  manage = pkgs.writeShellScriptBin "paperless-manage" ''
     set -o allexport # Export the following env vars
     ${lib.toShellVars env}
     ${lib.optionalString (cfg.environmentFile != null) "source ${cfg.environmentFile}"}
-    exec ${cfg.package}/bin/paperless-ngx "$@"
+
+    cd '${cfg.dataDir}'
+    sudo=exec
+    if [[ "$USER" != ${cfg.user} ]]; then
+      ${
+        if config.security.sudo.enable then
+          "sudo='exec ${config.security.wrapperDir}/sudo -u ${cfg.user} -E'"
+        else
+          ">&2 echo 'Aborting, paperless-manage must be run as user `${cfg.user}`!'; exit 2"
+      }
+    fi
+    $sudo ${lib.getExe cfg.package} "$@"
   '';
 
   defaultServiceConfig = {
@@ -94,14 +105,13 @@ in
       type = lib.types.bool;
       default = false;
       description = ''
-        Enable Paperless.
+        Whether to enable Paperless-ngx.
 
-        When started, the Paperless database is automatically created if it doesn't
+        When started, the Paperless database is automatically created if it doesn't exist
-        exist and updated if the Paperless package has changed.
+        and updated if the Paperless package has changed.
         Both tasks are achieved by running a Django migration.
 
-        A script to manage the Paperless instance (by wrapping Django's manage.py) is linked to
+        A script to manage the Paperless-ngx instance (by wrapping Django's manage.py) is available as `paperless-manage`.
-        `''${dataDir}/paperless-manage`.
       '';
     };
 
@@ -139,8 +149,7 @@ in
         A file containing the superuser password.
 
         A superuser is required to access the web interface.
-        If unset, you can create a superuser manually by running
+        If unset, you can create a superuser manually by running `paperless-manage createsuperuser`.
-        `''${dataDir}/paperless-manage createsuperuser`.
 
         The default superuser name is `admin`. To change it, set
         option {option}`settings.PAPERLESS_ADMIN_USER`.
@@ -288,6 +297,8 @@ in
   };
 
   config = lib.mkIf cfg.enable (lib.mkMerge [ {
+    environment.systemPackages = [ manage ];
+
     services.redis.servers.paperless.enable = lib.mkIf enableRedis true;
 
     services.postgresql = lib.mkIf cfg.database.createLocally {
@@ -336,7 +347,9 @@ in
       environment = env;
 
       preStart = ''
-        ln -sf ${manage} ${cfg.dataDir}/paperless-manage
+        # remove old papaerless-manage symlink
+        # TODO: drop with NixOS 25.11
+        [[ -L '${cfg.dataDir}/paperless-manage' ]] && rm '${cfg.dataDir}/paperless-manage'
 
         # Auto-migrate on first run or if the package has changed
         versionFile="${cfg.dataDir}/src-version"
@@ -504,10 +517,10 @@ in
         OnSuccess = services;
       };
       enableStrictShellChecks = true;
+      path = [ manage ];
       script = ''
-        ./paperless-manage document_exporter ${cfg.exporter.directory} ${lib.cli.toGNUCommandLineShell {} cfg.exporter.settings}
+        paperless-manage document_exporter ${cfg.exporter.directory} ${lib.cli.toGNUCommandLineShell {} cfg.exporter.settings}
       '';
     };
-  })
+  })]);
-  ]);
 }

nixos/tests/paperless.nix

@@ -99,7 +99,7 @@ import ./make-test-python.nix ({ lib, ... }: {
           # Double check that our attrset option override works as expected
           cmdline = node.succeed("grep 'paperless-manage' $(systemctl cat paperless-exporter | grep ExecStart | cut -f 2 -d=)")
           print(f"Exporter command line {cmdline!r}")
-          assert cmdline.strip() == "./paperless-manage document_exporter /var/lib/paperless/export --compare-checksums --delete --no-progress-bar --no-thumbnail", "Unexpected exporter command line"
+          assert cmdline.strip() == "paperless-manage document_exporter /var/lib/paperless/export --compare-checksums --delete --no-progress-bar --no-thumbnail", "Unexpected exporter command line"
 
     test_paperless(simple)
     simple.send_monitor_command("quit")