From f4b8bda4327e81e2c7d3f5b6fae578a9e57ab93d Mon Sep 17 00:00:00 2001
From: sbs20 <sam.strachan@gmail.com>
Date: Tue, 14 Nov 2023 12:41:01 +0000
Subject: [PATCH] Fix various `v3` snagging issues

Closes #686
Closes #692
Closes #693
Closes #694

This is mostly documentation. But it also defines the least awful way to resolve `require(...)` paths where a plugin (i.e. `config.local.js`) is in a symlinked directory.

Node uses the absolute path of a module to determine how `require` works. When the module is in a symlinked directory then things go bad.
---
 app-server/config/config.default.js |  3 +++
 docs/01-install.md                  | 21 +++++++++++++++++----
 docs/10-configuration.md            |  3 ++-
 docs/12-recipes.md                  |  9 ++++++---
 4 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/app-server/config/config.default.js b/app-server/config/config.default.js
index 18c45838..55913e12 100644
--- a/app-server/config/config.default.js
+++ b/app-server/config/config.default.js
@@ -1,4 +1,7 @@
 /* eslint-disable no-unused-vars */
+const options = { paths: ['/usr/lib/scanservjs'] };
+const Process = require(require.resolve('./server/classes/process', options));
+const dayjs = require(require.resolve('dayjs', options));
 
 /**
  * This file is ignored. If you want to apply overrides, make a copy in this
diff --git a/docs/01-install.md b/docs/01-install.md
index bb5495a1..0abe9f2d 100644
--- a/docs/01-install.md
+++ b/docs/01-install.md
@@ -32,15 +32,16 @@ and it's a one-off process. Further, you may be using some of the packages that
 this script proposes removing.
 
 ```sh
-# backup scans to home directory
-sudo mv /var/www/scanservjs/data/output ~/scanservjs-scans
-sudo chown $USER:$USER ~/scanservjs-scans
-
 # Stop and remove service
 sudo systemctl stop scanservjs > /dev/null
 sudo rm -vf /etc/systemd/system/scanservjs.service
 sudo systemctl daemon-reload
 
+# backup scans to home directory
+mkdir -p /tmp/scanservjs.bkp
+sudo mv -v /var/www/scanservjs/data /tmp/scanservjs.bkp
+sudo mv -v /var/www/scanservjs/config /tmp/scanservjs.bkp
+
 # Remove all old application files
 sudo rm -rvf /var/www/scanservjs
 
@@ -58,6 +59,18 @@ sudo apt-get remove -yq \
 sudo apt-get autoremove
 ```
 
+To restore backed up files after install:
+
+```sh
+sudo cp -v /tmp/scanservjs.bkp/data/output/* /usr/lib/scanservjs/data/output
+sudo cp -v /tmp/scanservjs.bkp/config/*.local.js /usr/lib/scanservjs/config
+sudo chown $USER:$USER /usr/lib/scanservjs/data/output/*
+```
+
+Note that if you have a `config.local.js` then you may need to amend it to work
+in `v3.x`. Please refer to the updated `config.default.js` or documentation to
+reference the recommended pattern for using node `require(...)`.
+
 ## Arch
 
 If you're using Arch, then [@dadosch](https://github.com/dadosch) created a
diff --git a/docs/10-configuration.md b/docs/10-configuration.md
index 01953ddf..e93688b3 100644
--- a/docs/10-configuration.md
+++ b/docs/10-configuration.md
@@ -67,7 +67,8 @@ action object must have a name and async execute method taking a `FileInfo`:
 ## Example file
 
 ```javascript
-const Process = require('../server/classes/process');
+const options = { paths: ['/usr/lib/scanservjs'] };
+const Process = require(require.resolve('./server/classes/process', options));
 
 module.exports = {
   /**
diff --git a/docs/12-recipes.md b/docs/12-recipes.md
index 779dfa24..52213d22 100644
--- a/docs/12-recipes.md
+++ b/docs/12-recipes.md
@@ -142,7 +142,8 @@ Then, add the following pipeline:
 ## Change the log level and default scan filename
 
 ```javascript
-const dayjs = require('dayjs');
+const options = { paths: ['/usr/lib/scanservjs'] };
+const dayjs = require(require.resolve('dayjs', options));
 module.exports = {
   afterConfig(config) {
     config.filename = () => {
@@ -258,7 +259,8 @@ integrating with `paperless-ng`. The example below defines a pipeline which
 creates a PDF and then copies it to the home directory on completion.
 
 ```javascript
-const Process = require('../src/classes/process');
+const options = { paths: ['/usr/lib/scanservjs'] };
+const Process = require(require.resolve('./server/classes/process', options));
 
 module.exports = {
   /**
@@ -354,7 +356,8 @@ pipeline then something like the following may help:
 Now create the following pipeline in your `config/config.local.js`
 
 ```javascript
-const Process = require('../server/classes/process');
+const options = { paths: ['/usr/lib/scanservjs'] };
+const Process = require(require.resolve('./server/classes/process', options));
 
 module.exports = {
   afterConfig(config) {